从 v6 迁移到 v7

本指南描述了将 Data Grid 从 v6 迁移到 v7 所需的更改。

简介

这是将 @mui/x-data-grid 从 v6 升级到 v7 的参考指南。要了解有关新主要版本更改的更多信息，请查看关于 MUI X v7 发布的博文。

开始使用新版本

在 package.json 中，将 Data Grid 包的版本更改为 ^7.0.0。

-"@mui/x-data-grid": "^6.0.0",
+"@mui/x-data-grid": "^7.0.0",

-"@mui/x-data-grid-pro": "^6.0.0",
+"@mui/x-data-grid-pro": "^7.0.0",

-"@mui/x-data-grid-premium": "^6.0.0",
+"@mui/x-data-grid-premium": "^7.0.0",

由于 v7 是一个主要版本，它包含影响公共 API 的更改。这些更改是为了保持一致性、提高稳定性和为新功能腾出空间而进行的。下面描述的是从 v6 迁移到 v7 所需的步骤。

更新 `@mui/material` 包

为了可以选择使用来自 @mui/material 的最新 API，包的对等依赖版本已更新为 ^5.15.14。这只是次要版本更改，因此不应导致任何重大更改。请将您的 @mui/material 包更新到此版本或更高版本。

更新许可证包

如果您使用的是 Data Grid 的商业版本（Pro 和 Premium 计划），则需要更新导入路径

-import { LicenseInfo } from '@mui/x-license-pro';
+import { LicenseInfo } from '@mui/x-license';

如果您的 package.json 的 dependencies 部分中有 @mui/x-license-pro，请重命名许可证包并更新到最新版本

-"@mui/x-license-pro": "^6.0.0",
+"@mui/x-license": "^7.0.0",

运行 codemod

preset-safe codemod 将自动调整您的大部分代码，以应对 v7 中的重大更改。您可以运行 v7.0.0/data-grid/preset-safe 仅针对 Data Grid，或运行 v7.0.0/preset-safe 以针对其他 MUI X 组件，如 Date and Time pickers。

当选择 <path> 参数时，您可以对特定文件、文件夹或整个代码库运行它。

// Data Grid specific
npx @mui/x-codemod@latest v7.0.0/data-grid/preset-safe <path>

// Target other MUI X components as well
npx @mui/x-codemod@latest v7.0.0/preset-safe <path>

由 preset-safe codemod 处理的重大更改在屏幕右侧的目录中或在由其处理的特定点旁边用 ✅ emoji 表示。

如果您已经应用了 v7.0.0/data-grid/preset-safe（或 v7.0.0/preset-safe）codemod，那么您应该不需要对这些项目采取任何进一步的操作。如果重大更改的特定部分不属于 codemod 或需要一些手动工作，它将在每个部分的末尾列出。

所有其他更改都必须手动处理。

并非所有用例都由 codemod 覆盖。在某些情况下，例如 props 展开、跨文件依赖项等，更改未正确识别，因此必须手动处理。

例如，如果 codemod 尝试重命名一个 prop，但此 prop 被 spread 运算符隐藏，则它不会按预期转换。

<DataGrid {...newProps} />

运行 codemod 后，请务必测试您的应用程序，并确保您没有任何控制台错误。

如果您在迁移过程中需要帮助，请随时打开 issue 寻求支持。

这是一个示例，说明如何在 Webpack 4 上使用 @babel/preset-env preset 转换这些功能

 // webpack.config.js

 module.exports = (env) => ({
   // ...
   module: {
     rules: [
       {
         test: /\.[jt]sx?$/,
-        exclude: /node_modules/,
+        exclude: [
+          {
+            test: path.resolve(__dirname, 'node_modules'),
+            exclude: [
+              // Covers @mui/x-data-grid, @mui/x-data-grid-pro, and @mui/x-data-grid-premium
+              path.resolve(__dirname, 'node_modules/@mui/x-data-grid'),
+              path.resolve(__dirname, 'node_modules/@mui/x-license'),
+            ],
+          },
+        ],
       },
     ],
   },
 });

DOM 更改

Data Grid 的布局已进行重大更改，以使用 CSS sticky 定位元素。因此，进行了以下更改

主元素现在对应于虚拟滚动器元素。
标题现在包含在虚拟滚动器中。
固定的行和列部分现在包含在虚拟滚动器中。
单元格内部包装器 .MuiDataGrid-cellContent 已删除。

重命名的 props

props rowBuffer 和 columnBuffer 已重命名为 rowBufferPx 和 columnBufferPx。它们的值现在是像素值，而不是项目数。它们的默认值现在为 150。

删除的 props

✅ 已删除已弃用的 props components 和 componentsProps。请改用 slots 和 slotProps。有关更多详细信息，请参阅组件部分。
已删除 slots.preferencesPanel slot 和 slotProps.preferencesPanel prop。请改用 slots.panel 和 slotProps.panel。

已从以下组件中删除 getOptionValue 和 getOptionLabel props

GridEditSingleSelectCell
GridFilterInputSingleSelect
GridFilterInputMultipleSingleSelect

请改为在 singleSelect 列定义上使用 getOptionValue 和 getOptionLabel 属性

const column: GridColDef = {
  type: 'singleSelect',
  field: 'country',
  valueOptions: [
    { code: 'BR', name: 'Brazil' },
    { code: 'FR', name: 'France' },
  ],
  getOptionValue: (value: any) => value.code,
  getOptionLabel: (value: any) => value.name,
};

已删除 props rowThreshold 和 columnThreshold。如果您已将 rowThreshold prop 设置为 0 以强制更频繁地渲染新行 – 这不再是必需的。
✅ 已从 experimentalFeatures prop 中删除一些功能标志。这些功能现在已稳定并默认启用

行为更改

现在可以使用 initialState、相应的受控模型或 API 对象以编程方式控制禁用的列特定功能，如 hiding、sorting、filtering、pinning、row grouping 等。

以下是受影响的功能列表、禁用它们所需的列定义标志和 props，以及以编程方式控制它们的相关 props 和 API 方法。

状态访问

某些选择器现在需要传递 instanceId 作为第二个参数

-gridColumnFieldsSelector(apiRef.current.state);
+gridColumnFieldsSelector(apiRef.current.state, apiRef.current.instanceId);

但是，最好将 apiRef 作为第一个参数传递

gridColumnFieldsSelector(apiRef);

有关更多信息，请参阅直接状态访问页面。

列

GridColDef['type'] 的类型已缩小为仅接受内置列类型。TypeScript 用户在定义列时需要使用 GridColDef 接口

// 🛑 `type` is inferred as `string` and is too wide
const columns = [{ type: 'number', field: 'id' }];
<DataGrid columns={columns} />;

// ✅ `type` is `'number'`
const columns: GridColDef[] = [{ type: 'number', field: 'id' }];
<DataGrid columns={columns} />;

// ✅ Alternalively, `as const` can be used to narrow down the type
const columns = [{ type: 'number' as const, field: 'id' }];
<DataGrid columns={columns} />;

类型 GridPinnedColumns 已重命名为 GridPinnedColumnFields。
类型 GridPinnedPosition 已重命名为 GridPinnedColumnPosition。
列分组 API 方法 getColumnGroupPath 和 getAllGroupDetails 不再以 unstable_ 为前缀。
列分组选择器 gridFocusColumnGroupHeaderSelector 和 gridTabIndexColumnGroupHeaderSelector 不再以 unstable_ 为前缀。
列管理组件已重新设计，并且该组件是从 ColumnsPanel 中提取的，ColumnsPanel 现在仅用作包装器，以在标题上方显示该组件作为面板。因此，引入了一个新的 slot columnsManagement 和相应的 prop slotProps.columnsManagement。先前传递给 prop slotProps.columnsPanel 的与列管理组件对应的 props 现在应传递给 slotProps.columnsManagement。slotProps.columnsPanel 仍可用于覆盖与 ColumnsPanel 中使用的 Panel 组件对应的 props，该组件在底层使用 Popper 组件。

 <DataGrid
  slotProps={{
-   columnsPanel: {
+   columnsManagement: {
      sort: 'asc',
      autoFocusSearchField: false,
    },
  }}
 />

ColumnsPanel 中的 Show all 和 Hide all 按钮已合并为一个新的列管理组件中的 Show/Hide All 复选框。相关的 props disableShowAllButton 和 disableHideAllButton 已替换为新的 prop disableShowHideToggle。

GridColDef['valueGetter'] 的签名已更改以提高性能

-valueGetter: ({ value, row }) => value,
+valueGetter: (value, row, column, apiRef) => value,

GridValueGetterParams 接口已删除

-const customValueGetter = (params: GridValueGetterParams) => params.row.budget;
+const customValueGetter: GridValueGetterFn = (value, row) => row.budget;

GridColDef['valueFormatter'] 的签名已更改以提高性能

-valueFormatter: ({ value }) => value,
+valueFormatter: (value, row, column, apiRef) => value,

GridValueFormatterParams 接口已删除

-const gridDateFormatter = ({ value, field, id }: GridValueFormatterParams<Date>) => value.toLocaleDateString();
+const gridDateFormatter: GridValueFormatter = (value: Date) => value.toLocaleDateString();

GridColDef['valueSetter'] 的签名已更改以提高性能

-valueSetter: (params) => {
-  const [firstName, lastName] = params.value!.toString().split(' ');
-  return { ...params.row, firstName, lastName };
-}
+valueSetter: (value, row) => {
+  const [firstName, lastName] = value!.toString().split(' ');
+  return { ...row, firstName, lastName };
+}

GridValueSetterParams 接口已删除

-const setFullName = (params: GridValueSetterParams) => {
-  const [firstName, lastName] = params.value!.toString().split(' ');
-  return { ...params.row, firstName, lastName };
-};
+const setFullName: GridValueSetter<Row> = (value, row) => {
+  const [firstName, lastName] = value!.toString().split(' ');
+  return { ...row, firstName, lastName };
+}

GridColDef['valueParser'] 的签名已更改以提高性能

-valueParser: (value, params: GridCellParams) => value.toLowerCase(),
+valueParser: (value, row, column, apiRef) => value.toLowerCase(),

GridColDef['colSpan'] 的签名已更改以提高性能

-colSpan: ({ row, field, value }: GridCellParams) => (row.id === 'total' ? 2 : 1),
+colSpan: (value, row, column, apiRef) => (row.id === 'total' ? 2 : 1),

GridColDef['pastedValueParser'] 的签名已更改以提高性能

-pastedValueParser: (value, params) => new Date(value),
+pastedValueParser: (value, row, column, apiRef) => new Date(value),

GridColDef['groupingValueGetter'] 的签名已更改以提高性能

-groupingValueGetter: (params) => params.value.name,
+groupingValueGetter: (value: { name: string }, row, column, apiRef) => value.name,

密度

density 现在是一个受控 prop，如果您之前将 density prop 传递给 Data Grid，您需要执行以下操作之一

将其移动到 initialState.density 以初始化它。

 <DataGrid
-  density="compact"
+  initialState={{ density: "compact" }}
 />

将其移动到状态并使用 onDensityChange 回调相应地更新 density prop，使其按预期工作。

 const [density, setDensity] = React.useState<GridDensity>('compact');
 <DataGrid
-  density="compact"
+  density={density}
+  onDensityChange={(newDensity) => setDensity(newDensity)}
 />

已删除选择器 gridDensityValueSelector，请改用 gridDensitySelector。

剪贴板

✅ 与剪贴板相关的导出 ignoreValueFormatterDuringExport 和 splitClipboardPastedText 不再以 unstable_ 为前缀。

打印导出

如果存在任何选定的行，则打印导出现在只会打印选定的行。如果没有选定的行，它将打印所有行。这使得打印导出与其他导出保持一致。您可以使用 getRowsToExport 函数自定义要导出的行。

选择

✅ 已从下面列出的单元格选择 props 中删除 unstable_ 前缀。

旧名称新名称

unstable_cellSelection cellSelection

unstable_cellSelectionModel cellSelectionModel

unstable_onCellSelectionModelChange onCellSelectionModelChange

旧名称	新名称
`unstable_cellSelection`	`cellSelection`
`unstable_cellSelectionModel`	`cellSelectionModel`
`unstable_onCellSelectionModelChange`	`onCellSelectionModelChange`

已从下面列出的单元格选择 API 方法中删除 unstable_ 前缀。

旧名称	新名称
`unstable_getCellSelectionModel`	`getCellSelectionModel`
`unstable_getSelectedCellsAsArray`	`getSelectedCellsAsArray`
`unstable_isCellSelected`	`isCellSelected`
`unstable_selectCellRange`	`selectCellRange`
`unstable_setCellSelectionModel`	`setCellSelectionModel`

筛选

GridFilterOperator 中的 getApplyFilterFnV7 已重命名为 getApplyFilterFn。如果您直接使用 getApplyFilterFnV7 - 请将其重命名为 getApplyFilterFn。
getApplyFilterFn 返回的函数的签名已更改以提高性能

 const getApplyFilterFn: GetApplyFilterFn<any, unknown> = (filterItem) => {
   if (!filterItem.value) {
     return null;
   }

   const filterRegex = new RegExp(escapeRegExp(filterItem.value), 'i');
-  return (cellParams) => {
-    const { value } = cellParams;
+  return (value, row, colDef, apiRef) => {
     return value != null ? filterRegex.test(String(value)) : false;
   };
 }

GridColDef 中的 getApplyQuickFilterFnV7 已重命名为 getApplyQuickFilterFn。如果您直接使用 getApplyQuickFilterFnV7 - 请将其重命名为 getApplyQuickFilterFn。
getApplyQuickFilterFn 返回的函数的签名已更改以提高性能

 const getGridStringQuickFilterFn: GetApplyQuickFilterFn<any, unknown> = (value) => {
   if (!value) {
     return null;
   }
   const filterRegex = new RegExp(escapeRegExp(value), 'i');
-  return (cellParams) => {
-    const { formattedValue } = cellParams;
+  return (value, row, column, apiRef) => {
+    let formattedValue = apiRef.current.getRowFormattedValue(row, column);
     return formattedValue != null ? filterRegex.test(formattedValue.toString()) : false;
   };
 };

快速筛选现在默认忽略隐藏列。有关更多详细信息，请参阅包含隐藏列部分。

标头筛选器功能现在已稳定。已从 prop headerFilters 和以下导出中删除 unstable_ 前缀。

旧名称	新名称
`unstable_gridFocusColumnHeaderFilterSelector`	`gridFocusColumnHeaderFilterSelector`
`unstable_gridHeaderFilteringEditFieldSelector`	`gridHeaderFilteringEditFieldSelector`
`unstable_gridHeaderFilteringMenuSelector`	`gridHeaderFilteringMenuSelector`
`unstable_gridHeaderFilteringStateSelector`	`gridHeaderFilteringStateSelector`
`unstable_gridTabIndexColumnHeaderFilterSelector`	`gridTabIndexColumnHeaderFilterSelector`

筛选器面板不再对所有组件使用原生版本的 Select 组件。
filterModel 现在支持将 Date 对象作为 date 和 dateTime 列类型的值。filterModel 仍然接受字符串作为 date 和 dateTime 列类型的值，但来自 UI 的所有 filterModel 更新（例如筛选器面板）都将值设置为 Date 对象。

辅助功能

✅ 已删除 ariaV7 实验性标志，并且 Data Grid 现在默认使用改进的辅助功能实现。如果您正在使用 ariaV7 标志，则可以从 experimentalFeatures prop 中删除它
```
-<DataGrid experimentalFeatures={{ ariaV7: true }} />
+<DataGrid />
```
最值得注意的更改可能会影响您的应用程序或测试
- role="grid" 属性以及相关的 ARIA 属性现在应用于内部 div 元素，而不是根 div 元素
```
-<div class="MuiDataGrid-root" role="grid" aria-colcount="5" aria-rowcount="101" aria-multiselectable="false">
+<div class="MuiDataGrid-root">
   <div class="MuiDataGrid-toolbarContainer"></div>
-    <div class="MuiDataGrid-main"></div>
+    <div class="MuiDataGrid-main" role="grid" aria-colcount="5" aria-rowcount="101" aria-multiselectable="false"></div>
   <div class="MuiDataGrid-footerContainer"></div>
 </div>
```
- 当使用树状数据功能时，网格角色现在是 role="treegrid" 而不是 role="grid"。
- Data Grid 单元格现在具有 role="gridcell" 而不是 role="cell"。

编辑

已删除 rowEditCommit 事件和相关的 prop onRowEditCommit。可以使用 processRowUpdate prop 代替。

其他导出

locales 的导入路径已更改

-import { enUS } from '@mui/x-data-grid';
+import { enUS } from '@mui/x-data-grid/locales';

-import { enUS } from '@mui/x-data-grid-pro';
+import { enUS } from '@mui/x-data-grid-pro/locales';

-import { enUS } from '@mui/x-data-grid-premium';
+import { enUS } from '@mui/x-data-grid-premium/locales';

已弃用的常量 SUBMIT_FILTER_STROKE_TIME 和 SUBMIT_FILTER_DATE_STROKE_TIME 不再导出。使用 filterDebounceMs prop 自定义筛选器防抖时间。
GridPreferencesPanel 组件不再导出，因为它不打算在 Data Grid 外部使用。
工具栏可组合组件 GridToolbarColumnsButton、GridToolbarFilterButton、GridToolbarDensity 和 GridToolbarExport 中的按钮现在用 tooltip 组件包装，并具有一致的接口。为了覆盖与工具栏按钮或其对应的 tooltips 相关的一些 props，您可以使用 slotProps prop。以下是一个示例差异。有关更多详细信息，请参阅工具栏部分。

 function CustomToolbar() {
  return (
    <GridToolbarContainer>
      <GridToolbarColumnsButton />
      <GridToolbarFilterButton
-       title="Custom filter" // 🛑 This was previously forwarded to the tooltip component
+       slotProps={{ tooltip: { title: 'Custom filter' } }} // ✅ This is the correct way now
      />
      <GridToolbarDensitySelector
-       variant="outlined"    // 🛑 This was previously forwarded to the button component
+       slotProps={{ button: { variant: 'outlined' } }} // ✅ This is the correct way now
      />
    </GridToolbarContainer>
  );
 }

CSS 类和样式

您现在可以使用 :hover 而不是 .Mui-hovered 来设置行悬停状态的样式。
已删除固定列的 .MuiDataGrid--pinnedColumns-(left\|right) 类。
已删除 .MuiDataGrid-cell--withRenderer 类。
单元格元素默认不是 display: flex。您可以在列定义中添加 display: 'flex' 以恢复该行为。

注意：如果您使用的是动态行高，这也意味着单元格默认不再垂直居中，您可能需要为所有非动态列设置 display: 'flex'。这可能还会影响文本省略号，您可以通过添加自己的带有 text-overflow: ellipsis 的包装器来恢复它。
```
{
  display: 'flex',
  renderCell: ({ value }) => (
    <div style={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>
      {value}
    </div>
  ),
},
```
columnHeader--showColumnBorder 类已替换为 columnHeader--withLeftBorder 和 columnHeader--withRightBorder。
由于在我们简化 DOM 结构并提高辅助功能的努力中删除了内部包装器，因此已删除 columnHeadersInner、columnHeadersInner--scrollable 和 columnHeaderDropZone 类。
pinnedColumnHeaders、pinnedColumnHeaders--left 和 pinnedColumnHeaders--right 类已随它们所应用的元素一起删除。固定列标题现在使用 position: 'sticky'，并在与常规列标题相同的行元素中呈现。
列标题和固定部分现在需要显式颜色。默认情况下，将使用 MUI theme.palette.background.default 颜色。要自定义它，请参阅 https://mui.org.cn/material-ui/customization/palette/#customization 我们将向调色板添加新的颜色名称以进行额外自定义，请阅读 #12443 了解更多详细信息。

对公共 API 的更改

方法 getRootDimensions() 现在返回非空值。
字段 mainElementRef 现在始终为非空。
字段 rootElementRef 现在始终为非空。
字段 virtualScrollerRef 现在始终为非空。
事件 renderedRowsIntervalChange 参数从 GridRenderedRowsIntervalChangeParams 更改为 GridRenderContext，并且已删除前者。

对 slots 的更改

slot columnHeaders 已删除以下 props：columnPositions、densityFactor、minColumnIndex。
slot row 已删除以下 props：containerWidth、position。
slot row 现在具有类型化的 props。
slot headerFilterCell 已删除以下 props：filterOperators。
所有 slots 现在都是强类型的，以前是 React.JSXElementConstructor<any>。