数据表格 - 导出

轻松导出各种文件格式的行，例如 CSV、Excel 或 PDF。

启用导出

要启用导出菜单，请在 Toolbar 组件插槽中传递 GridToolbar 组件。

<DataGrid {...data} loading={loading} slots={{ toolbar: GridToolbar }} />

<DataGrid {...data} loading={loading} slots={{ toolbar: GridToolbar }} />

按 Enter 开始编辑

导出菜单在名为 GridToolbarExport 的独立组件中提供。您可以在自定义工具栏组件中按如下方式使用它。

function CustomToolbar() {
  return (
    <GridToolbarContainer>
      <GridToolbarExport />
    </GridToolbarContainer>
  );
}

导出选项

默认情况下，导出菜单会根据您的许可证显示所有可用的导出格式，包括

打印
CSV
Excel
剪贴板 (🚧 尚未交付)

您可以通过将选项对象作为 prop 传递给 GridToolbar 或 GridToolbarExport 来自定义它们各自的行为。

<DataGrid slotProps={{ toolbar: { csvOptions } }} />

// same as

<GridToolbarExport csvOptions={csvOptions} />

每个导出选项都有其自己的 API 页面

禁用格式

您可以通过将其选项属性 disableToolbarButton 设置为 true，从工具栏中删除导出格式。在以下示例中，禁用了打印导出。

<DataGrid
  slotProps={{ toolbar: { printOptions: { disableToolbarButton: true } } }}
/>

导出的列

默认情况下，导出将仅包含数据表格的可见列。有几种方法可以包含或隐藏其他列。

对于您不想导出的列，请在 GridColDef 中将 disableExport 属性设置为 true。

<DataGrid columns={[{ field: 'name', disableExport: true }, { field: 'brand' }]} />

在导出选项中将 allColumns 设置为 true，以同时包含隐藏列。具有 disableExport=true 的列将不会被导出。

<DataGrid slotProps={{ toolbar: { csvOptions: { allColumns: true } } }} />

在导出选项中设置要导出的确切列。设置 fields 会覆盖其他属性。这样，导出的列将完全是 fields 中的列，顺序也相同。

<DataGrid slotProps={{ toolbar: { csvOptions: { fields: ['name', 'brand'] } } }} />

导出的行

默认情况下，数据表格会导出选定的行（如果有）。否则，它会导出除页脚外的所有行（根据活动规则筛选和排序的行），包括折叠的行。

自定义要导出的行

或者，您可以设置 getRowsToExport 函数并导出您想要的任何行，如下例所示。网格导出了一些选择器，可以帮助您获取最常见用例的行

选择器	行为
`gridRowIdsSelector`	行按其原始顺序排列。
`gridSortedRowIdsSelector`	应用排序规则后的行。
`gridFilteredSortedRowIdsSelector`	应用排序规则和筛选规则后的行。
`gridExpandedSortedRowIdsSelector`	应用排序规则、筛选规则且不包含折叠行的行。
`gridPaginatedVisibleSortedGridRowIdsSelector`	应用排序规则、筛选规则、不包含折叠行且仅针对当前页面的行（注意：如果禁用分页，它仍将采用 `page` 和 `pageSize` 的值）。

当使用行分组时，从 CSV 导出中删除组可能很有用。

CSV 导出

导出的单元格

当字段的值是对象或提供了 renderCell 时，CSV 导出可能无法正确显示该值。您可以提供带有字符串表示形式的 valueFormatter 以供使用。

<DataGrid
  columns={[
    {
      field: 'progress',
      valueFormatter: (value) => `${value * 100}%`,
      renderCell: ({ value }) => <ProgressBar value={value} />,
    },
  ]}
/>

文件编码

您可以使用 csvOptions 来指定导出的格式，例如用于分隔字段的 delimiter 字符、fileName 或 utf8WithBom，以在导出的文件前添加 UTF-8 字节顺序标记 (BOM)。有关这些选项的更多详细信息，请访问 csvOptions API 页面。

<GridToolbarExport
  csvOptions={{
    fileName: 'customerDataBase',
    delimiter: ';',
    utf8WithBom: true,
  }}
/>

转义公式

默认情况下，单元格中的公式会被转义。这是为了防止在在 Excel 中打开 CSV 文件时执行公式。

如果要保持公式有效，可以将 escapeFormulas 选项设置为 false。

<DataGrid slotProps={{ toolbar: { csvOptions: { escapeFormulas: false } } }} />

// or

<GridToolbarExport csvOptions={{ escapeFormulas: false }} />

打印导出

修改数据表格样式

默认情况下，打印的网格等同于打印仅包含数据表格的页面。要修改用于打印的样式（例如颜色），您可以使用 @media print 媒体查询或 printOptions 的 pageStyle 属性。

例如，如果数据表格处于暗黑模式，则文本颜色将不适合打印（太浅）。

使用媒体查询，您必须以 @media print 键开头您的 sx 对象，以便仅在打印时应用内部的所有样式。

<DataGrid
  sx={{
    '@media print': {
      '.MuiDataGrid-main': { color: 'rgba(0, 0, 0, 0.87)' },
    },
  }}
  {/* ... */}
/>

使用 pageStyle 选项，您可以使用更具体的选择器覆盖主要内容颜色。

<DataGrid
  slotProps={{
    toolbar: {
      printOptions:{
        pageStyle: '.MuiDataGrid-root .MuiDataGrid-main { color: rgba(0, 0, 0, 0.87); }',
      }
    }
  }}
  {/* ... */}
/>

自定义网格显示

默认情况下，打印导出显示所有数据表格。可以通过分别将 hideFooter 和 hideToolbar 设置为 true 来删除页脚和工具栏。

<GridToolbarExport
  printOptions={{
    hideFooter: true,
    hideToolbar: true,
  }}
/>

如果在导出时选择了行，则复选框将不会包含在打印页面中。要导出复选框，您可以将 includeCheckboxes 设置为 true。

<GridToolbarExport
  printOptions={{
    includeCheckboxes: true,
  }}
/>

有关自定义打印导出的更多选项，请访问 printOptions API 页面。

自定义导出格式

您可以通过创建自己的导出菜单来添加自定义导出格式。为了简化其创建，您可以使用包含菜单逻辑的 <GridToolbarExportContainer />。默认的 <GridToolbarExport /> 定义如下

const GridToolbarExport = ({ csvOptions, printOptions, ...other }) => (
  <GridToolbarExportContainer {...other}>
    <GridCsvExportMenuItem options={csvOptions} />
    <GridPrintExportMenuItem options={printOptions} />
  </GridToolbarExportContainer>
);

<GridToolbarExportContainer /> 的每个子级都会收到一个 prop hideMenu，用于在导出后关闭导出菜单。下面的演示展示了如何添加 JSON 导出。

Excel 导出

此功能依赖于 exceljs。Excel 导出允许将数据表格的列类型和树状结构转换为 Excel 文件。

类型为 'boolean'、'number'、'singleSelect'、'date' 和 'dateTime' 的列以其在 Excel 中对应的类型导出。请确保 rows 值具有正确的类型，您可以随时根据需要转换它们。

自定义

自定义列

您可以使用 columnsStyles 属性来自定义列样式。此属性接受一个对象，其中键是列字段，值是 exceljs 样式对象。

这可以用于指定值格式或添加一些颜色。

<GridToolbarExport
  excelOptions={{
    columnsStyles: {
      // replace the dd.mm.yyyy default date format
      recruitmentDay: { numFmt: 'dd/mm/yyyy' },
      // set this column in green
      incomes: { font: { argb: 'FF00FF00' } },
    },
  }}
/>

自定义文档

您可以使用两个回调函数来自定义文档

在添加行数据集之前调用的 exceljsPreProcess。
在数据集导出到文档之后调用的 exceljsPostProcess。

这两个函数都接收 { workbook, worksheet } 作为输入。它们是 exceljs 对象，允许您直接操作 Excel 文件。

借助这两种方法，您可以修改导出的电子表格的元数据。您还可以使用它在工作表的顶部或底部添加自定义内容，如下所示

function exceljsPreProcess({ workbook, worksheet }) {
  workbook.created = new Date(); // Add metadata
  worksheet.name = 'Monthly Results'; // Modify worksheet name

  // Write on first line the date of creation
  worksheet.getCell('A1').value = `Values from the`;
  worksheet.getCell('A2').value = new Date();
}

function exceljsPostProcess({ worksheet }) {
  // Add a text after the data
  worksheet.addRow(); // Add empty row

  const newRow = worksheet.addRow();
  newRow.getCell(1).value = 'Those data are for internal use only';
}

// ...

<GridToolbarExport
  excelOptions={{
    exceljsPreProcess,
    exceljsPostProcess,
  }}
/>;

由于 exceljsPreProcess 在添加数据表格的内容之前应用，因此您可以使用它在文档顶部添加一些信息行。数据表格的内容将从 exceljsPreProcess 添加的行之后的下一行开始。

要自定义数据表格内容之后的行，您应该使用 exceljsPostProcess。由于它是在添加内容之后应用的，因此您也可以使用它来访问生成的单元格。

在以下演示中，这两种方法都用于设置自定义页眉和自定义页脚。

使用 Web Worker

您可以将任务委托给 Web Worker，而不是在主线程中生成 Excel 文件。此方法减少了主线程保持冻结的时间，从而允许在后台导出数据时与网格进行交互。要开始对 Excel 导出使用 Web Worker，首先您需要创建一个包含以下内容的文件。此文件稍后将用作 worker 脚本，因此必须可以通过直接 URL 访问。

// in file ./worker.ts
import { setupExcelExportWebWorker } from '@mui/x-data-grid-premium/setupExcelExportWebWorker';

setupExcelExportWebWorker();

最后一步是将创建的文件路径传递给 GridToolbarExport 或 API 方法

<GridToolbarExport
  excelOptions={{
    worker: () => new Worker('/worker.ts'),
  }}
/>;

// or

apiRef.current.exportDataAsExcel({
  worker: () => new Worker('/worker.ts'),
});

如果您使用的是 Next.js 或 Webpack 5，请改用以下语法。确保将相对路径（相对于当前文件）传递给 worker 脚本。

<GridToolbarExport
  excelOptions={{
    worker: () => new Worker(new URL('./worker.ts', import.meta.url)),
  }}
/>;

// or

apiRef.current.exportDataAsExcel({
  worker: () => new Worker(new URL('./worker.ts', import.meta.url)),
});

不必使脚本公开，因为 Webpack 会自动为您处理。

由于主线程在导出数据时未被锁定，因此向用户提供正在进行中的反馈非常重要。您可以将回调传递给 onExcelExportStateChange prop 并显示消息或加载器。以下演示包含使用 Snackbar 的示例

如果您想使用 exceljsPreProcess 和 exceljsPostProcess 选项来自定义最终电子表格，如上面的自定义部分所示，则必须将它们传递给 setupExcelExportWebWorker。这是必要的，因为函数无法传递给 Web Worker。

// Instead of
<GridToolbarExport
  excelOptions={{
    exceljsPreProcess,
    exceljsPostProcess,
  }}
/>;

// Do the following in the ./worker.ts file
setupExcelExportWebWorker({
  exceljsPreProcess,
  exceljsPostProcess,
});

转义公式

默认情况下，单元格中的公式会被转义。这是为了防止在在 Excel 中打开文件时执行公式。

如果要保持公式有效，可以将 escapeFormulas 选项设置为 false。

<DataGridPremium slotProps={{ toolbar: { excelOptions: { escapeFormulas: false } } }} />

// or

<GridToolbarExport excelOptions={{ escapeFormulas: false }} />

签名

exportDataAsCsv: (options?: GridCsvExportOptions) => void

getDataAsCsv()

将网格数据作为 CSV 字符串返回。此方法在内部由 exportDataAsCsv 使用。

签名

getDataAsCsv: (options?: GridCsvExportOptions) => string

打印

exportDataAsPrint()

打印网格数据。

签名

exportDataAsPrint: (options?: GridPrintExportOptions) => void

Excel

exportDataAsExcel()

下载并导出网格数据的 Excel 文件。

签名

exportDataAsExcel: (options?: GridExcelExportOptions) => Promise<void>

getDataAsExcel()

将网格数据作为 exceljs 工作簿返回。此方法在内部由 exportDataAsExcel 使用。

签名

getDataAsExcel: (options?: GridExcelExportOptions) => Promise<Excel.Workbook> | null