如何在 MUI X Data Grid 中通过自定义按钮导出单条记录为 CSV

本文介绍如何利用 mui x data grid 的 exportdataascsv api，在点击自定义按钮时精准导出当前行（或指定行）数据为 csv 文件，无需依赖内置工具栏，支持灵活筛选与配置。

在 MUI X Data Grid（社区版）中，内置的 CSV 导出功能默认通过 组件触发，但实际业务中常需更精细的控制——例如：仅导出用户点击的某一行、导出筛选后的子集、或集成到操作列（Action column）中的「下载」按钮。这完全可通过 useGridApiContext 获取 Grid API 实例，并调用 apiRef.current.exportDataAsCsv() 方法实现。

✅ 核心思路

exportDataAsCsv() 接收一个可选的 GridCsvExportOptions 对象，其中关键配置项包括：

• allColumns: 是否导出所有字段（含隐藏列），默认 false
• fileName: 自定义导出文件名（如 ‘record-123.csv’）
• skipHeader: 是否跳过表头，默认 false
• getRowsToExport: 最关键——用于指定要导出的行 ID 数组，实现「单行导出」

? 示例：为每行添加「下载此行」按钮（操作列）

import { DataGrid, GridActionsCellItem, GridColDef, GridRowParams, useGridApiContext } from '@mui/x-data-grid'; import { FileDownload as FileDownloadIcon } from '@mui/icons-material'; import { Button } from '@mui/material';  // 自定义操作列 const columns: GridColDef[] = [   // ...其他列   {     field: 'actions',     type: 'actions',     headerName: '操作',     width: 120,     getActions: (params: GridRowParams) => [       }         label="下载本行"         onClick={() => {           const apiRef = useGridApiContext();           // 仅导出当前行           apiRef.current.exportDataAsCsv({             fileName: `record-${params.id}.csv`,             getRowsToExport: () => [params.id], // ? 关键：只传入当前行 ID           });         }}       />,     ],   }, ];

⚠️ 注意：useGridApiContext() 必须在 DataGrid 组件树内部使用（如列定义函数内不可直接调用）。因此推荐将导出逻辑封装为独立 Hook 或在事件回调中通过 params.api 访问（v6.15+ 支持 params.api.exportDataAsCsv）：

// ✅ 更安全的写法（推荐） getActions: (params: GridRowParams) => [   }     label="下载本行"     onClick={() => {       params.api.exportDataAsCsv({         fileName: `user-${params.row.id}.csv`,         getRowsToExport: () => [params.id],       });     }}   />, ],

?️ 进阶：导出多选行或自定义数据

若需导出当前多选行，可结合 apiRef.current.getSelectedRows()：

const handleExportSelected = () => {   const selectedIds = Array.from(apiRef.current.getSelectedRows().keys());   apiRef.current.exportDataAsCsv({     fileName: 'selected-records.csv',     getRowsToExport: () => selectedIds,   }); };

? 注意事项

• exportDataAsCsv 是客户端纯前端导出，不发送网络请求；
• 导出内容严格基于当前 Grid 渲染的数据模型（即 rows prop + 过滤/排序后状态）；
• 若需导出原始未处理数据（如服务端全量），应改用 fetch + 后端接口生成 CSV 流；
• 文件名不支持路径字符（如 /, ），建议对 id 做 URL 安全转义（如 encodeURIComponent）。

通过以上方式，你即可完全脱离默认工具栏，按需触发任意粒度的 CSV 导出，大幅提升交互自由度与用户体验。