从 v5 迁移到 v6

本指南描述了从 v5 迁移到 v6 的数据网格所需的更改。

简介

开始使用新版本

在 package.json 中，将数据网格包的版本更改为 ^6.0.0。

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

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

运行 codemods

preset-safe codemod 将自动调整您的大部分代码，以适应 v6 中的重大更改。您可以运行 v6.0.0/data-grid/preset-safe 仅针对数据网格，或运行 v6.0.0/preset-safe 以同时针对日期和时间选择器。

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

// Data Grid specific
npx @mui/x-codemod@latest v6.0.0/data-grid/preset-safe <path>
// Target Date and Time Pickers as well
npx @mui/x-codemod@latest v6.0.0/preset-safe <path>

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

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

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

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

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

<DataGrid {...newProps} />

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

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

重大更改

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

✅ 重命名的属性

为了避免与将为单元格选择功能添加的属性混淆，一些与行选择相关的属性已重命名为在名称中包含“row”。重命名的属性如下

旧名称	新名称
`selectionModel`	`rowSelectionModel`
`onSelectionModelChange`	`onRowSelectionModelChange`
`disableSelectionOnClick`	`disableRowSelectionOnClick`
`disableMultipleSelection`	`disableMultipleRowSelection`
`showCellRightBorder`	`showCellVerticalBorder`
`showColumnRightBorder`	`showColumnVerticalBorder`
`headerHeight`	`columnHeaderHeight`

rowSelectionModel（以前为 selectionModel）的相应类型已从 GridSelectionModel 重命名为 GridRowSelectionModel。

移除的属性

disableIgnoreModificationsIfProcessingProps 属性已被移除，其 true 时的行为已作为默认行为合并。旧行为可以通过使用 apiRef.current.stopRowEditMode({ ignoreModifications: true }) 或 apiRef.current.stopCellEditMode({ ignoreModifications: true }) 来恢复。
onColumnVisibilityChange 属性已被移除。请改用 onColumnVisibilityModelChange。
components.Header 插槽已被移除。请改用 components.Toolbar 或 slots.toolbar 插槽。
✅ disableExtendRowFullWidth 属性已被移除。使用 showCellVerticalBorder 或 showColumnVerticalBorder 属性来分别显示或隐藏单元格和表头单元格的右边框。
columnTypes 属性已被移除。有关自定义列类型，请参阅自定义列类型文档。

✅ onCellFocusOut 属性已被移除。请改用 slotProps.cell.onBlur。

<DataGrid
  slotProps={{
    cell: {
      onBlur: (event) => {
        const cellElement = event.currentTarget;
        const field = cellElement.getAttribute('data-field');
        const rowId = cell.parentElement.getAttribute('data-id');
      },
    },
  }}
/>

error 和 onError 属性已被移除 - 网格不再捕获渲染期间的错误。要捕获渲染期间发生的错误，请使用错误边界。components.ErrorOverlay 插槽也已被移除。

状态访问

✅ gridSelectionStateSelector 选择器已重命名为 gridRowSelectionStateSelector。
✅ allGridColumnsFieldsSelector 选择器已移除。请改用 gridColumnFieldsSelector。
✅ allGridColumnsSelector 选择器已移除。请改用 gridColumnDefinitionsSelector。
✅ visibleGridColumnsSelector 选择器已移除。请改用 gridVisibleColumnDefinitionsSelector。
✅ filterableGridColumnsSelector 选择器已移除。请改用 gridFilterableColumnDefinitionsSelector。
✅ gridVisibleSortedRowIdsSelector 选择器已重命名为 gridExpandedSortedRowIdsSelector。
✅ gridVisibleSortedRowEntriesSelector 选择器已重命名为 gridExpandedSortedRowEntriesSelector。
✅ gridVisibleRowCountSelector 选择器已重命名为 gridExpandedRowCountSelector。
✅ gridVisibleSortedTopLevelRowEntriesSelector 选择器已重命名为 gridFilteredSortedTopLevelRowEntriesSelector。
✅ gridVisibleTopLevelRowCountSelector 选择器已重命名为 gridFilteredTopLevelRowCountSelector。
✅ getGridNumericColumnOperators 选择器已移除。请改用 getGridNumericOperators。
gridVisibleRowsSelector 选择器已移除。请改用 gridExpandedSortedRowIdsSelector。

gridColumnsSelector 选择器已移除。请改用更具体的网格列选择器。

-const { all, lookup, columnVisibilityModel } = gridColumnsSelector(apiRef);
+const all = gridColumnFieldsSelector(apiRef);
+const lookup = gridColumnLookupSelector(apiRef);
+const columnVisibilityModel = gridColumnVisibilityModelSelector(apiRef);

filterableGridColumnsIdsSelector 选择器已移除。请改用 gridFilterableColumnLookupSelector。

-const filterableFields = filterableGridColumnsIdsSelector(apiRef);
+const lookup = gridFilterableColumnLookupSelector(apiRef);
+const filterableFields = gridColumnFieldsSelector(apiRef).filter(field => lookup[field]);

visibleGridColumnsLengthSelector 选择器已移除。请改用 gridVisibleColumnDefinitionsSelector。

-const visibleColumnsLength = visibleGridColumnsLengthSelector(apiRef);
+const visibleColumnsLength = gridVisibleColumnDefinitionsSelector(apiRef).length;

gridColumnsMetaSelector 选择器已移除。请改用 gridColumnsTotalWidthSelector 或 gridColumnPositionsSelector。

-const { totalWidth, positions } = gridColumnsMetaSelector(apiRef);
+const totalWidth = gridColumnsTotalWidthSelector(apiRef);
+const positions = gridColumnPositionsSelector(apiRef);

gridRowGroupingStateSelector 选择器已移除。
gridFilterStateSelector 选择器已移除。
gridRowsStateSelector 选择器已移除。
gridSortingStateSelector 选择器已移除。
gridTotalHeaderHeightSelector 选择器已移除。
gridDensityRowHeightSelector 选择器已移除。
gridDensityHeaderHeightSelector 选择器已移除。
gridEditRowsStateSelector 选择器已移除。
apiRef.current.state.density.headerHeight 属性已被移除。
apiRef.current.state.density.rowHeight 属性已被移除。

事件

✅ selectionChange 事件已重命名为 rowSelectionChange。
✅ rowsScroll 事件已重命名为 scrollPositionChange。
columnVisibilityChange 事件已被移除。请改用 columnVisibilityModelChange。
cellNavigationKeyDown 事件已被移除。请使用 cellKeyDown 并检查事件参数中提供的 key。
columnHeaderNavigationKeyDown 事件已被移除。请使用 columnHeaderKeyDown 并检查事件参数中提供的 key。

对于在 Portals 中使用组件内发生的键盘事件，也会触发 cellKeyDown 事件。这尤其影响自定义编辑组件，其中按下快捷键将触发停止编辑例程。例如，在 Portal 内按下 Enter 将导致更改被保存。onCellEditStop（或 onRowEditStop）属性可用于恢复旧行为。

<DataGrid
  onCellEditStop={(params, event) => {
    if (params.reason !== GridCellEditStopReasons.enterKeyDown) {
      return;
    }
    // Check if the target is inside a Portal
    if (
      (event.target as any).nodeType === 1 &&
      !event.currentTarget.contains(event.target)
    ) {
      event.defaultMuiPrevented = true;
    }
  }}
/>

componentError 事件已被移除。使用错误边界来捕获渲染期间抛出的错误。
GridCallbackDetails['api'] 已从事件详情中移除。请改用 useGridApiContext 或 useGridApiRef 返回的 apiRef。
cellFocusIn 和 cellFocusOut 事件现在是内部事件。请改用 slotProps.cell.onFocus 和 slotProps.cell.onBlur 属性。

列

GridColDef['hide'] 属性已被移除。请改用 columnVisibilityModel。
在 column.renderCell 或 column.renderEditCell 中返回 null 现在会渲染一个空单元格，而不是默认的格式化值。要回退到默认的格式化值，请返回 undefined 而不是 null。
```
 const renderCell = () => {
  if (condition) {
    return <CustomComponent />;
  }
- return null;
+ return undefined;
 }
```
仅当重新排序的列放置在另一个位置时，才会调用 onColumnOrderChange 属性回调。
当 valueOptions 是对象数组时，singleSelect 列类型现在具有一个默认值格式化程序，该格式化程序返回与所选值对应的 label。因此，任何现有的值格式化程序将不再应用于单个选项，而仅应用于单元格的文本。建议将 valueOptions 迁移到对象数组，以便能够为每个值添加自定义标签。要覆盖单元格处于编辑模式或在过滤器面板中时用于每个选项的标签，以下组件现在支持 getOptionLabel 属性
- GridEditSingleSelectCell
- GridFilterInputSingleSelect
- GridFilterInputMultipleSingleSelect
此属性接受一个回调，该回调使用 valueOptions 中的项目调用，并且必须返回要用作新标签的字符串。

date 和 dateTime 列现在仅支持 Date 对象作为值。要解析字符串值，请使用 valueGetter

<DataGrid
  columns={[
    {
      field: 'date',
      type: 'date',
      valueGetter: (params) => new Date(params.value),
    },
  ]}
/>

列菜单组件已重命名或与新设计合并，以实现一致性和 API 改进，新组件如下所示

旧名称	新名称
`GridFilterMenuItem`	`GridColumnMenuFilterItem`
`HideGridColMenuItem`	`GridColumnMenuHideItem`
`GridColumnsMenuItem`	`GridColumnMenuColumnsItem`
`SortGridMenuItems`	`GridColumnMenuSortItem`
`GridColumnPinningMenuItems`	`GridColumnMenuPinningItem`
`GridAggregationColumnMenuItem`	`GridColumnMenuAggregationItem`
`GridRowGroupingColumnMenuItems`, `GridRowGroupableColumnMenuItems`	`GridColumnMenuGroupingItem`

GridFilterItemProps 类型已重命名为 GridColumnMenuItemProps。

传递给 GridColumnMenu 和列菜单项的属性 column 和 currentColumn 已重命名为 colDef

-function CustomColumnMenu({ column }) {
-  if (column.field === 'name') {
+function CustomColumnMenu({ colDef }) {
+  if (colDef.field === 'name') {
     return <div>Custom column menu for name field</div>;
   }
   return (
     <div>
       <GridFilterMenuItem colDef={colDef} />
       <GridColumnMenuColumnsItem colDef={colDef} />
     </div>
   );
 }

行

GridRowParams['getValue'] 属性已被移除。请改用 params.row。
GridCellParams['getValue'] 属性已被移除。请改用 params.row。
GridCellParams['value'] 的默认类型已从 any 更改为 unknown。
GridActionsCellProps['api'] 属性已被移除。请改用 useGridApiContext hook 获取 apiRef。
GridActionsCellProps['getValue'] 属性已被移除。请改用 params.row。
GridFooterCellProps['getValue'] 属性已被移除。请改用 params.row。

cellFocus、cellTabIndex 和 editRowsState 属性不再传递给 Row 插槽。请改用 focusedCell 和 tabbableCell 属性。对于编辑状态，请使用 API 方法。

 function CustomRow(props) {
-  const focusedField = props.cellFocus.field;
-  const tabIndex = props.cellTabIndex.field && cellMode === 'view' ? 0 : 1;
+  const focusedField = props.focusedCell;
+  const tabIndex = props.tabbableCell === column.field ? 0 : 1;

更新 rows 属性或调用 apiRef.current.setRows 现在将删除网格的展开状态，因为这些方法旨在替换行。对于部分行更新，请改用apiRef.current.updateRows 方法。

分页

page 和 pageSize 属性及其各自的事件处理程序 onPageChange 和 onPageSizeChange 已被移除。请改用 paginationModel 和 onPaginationModelChange。

 <DataGrid
-  page={page}
-  pageSize={pageSize}
-  onPageChange={handlePageChange}
-  onPageSizeChange={handlePageSizeChange}
+  paginationModel={{ page, pageSize }}
+  onPaginationModelChange={(paginationModel) => handlePaginationModelChange(paginationModel)}
 />

属性 initialState.pagination.page 和 initialState.pagination.pageSize 也已被移除。请改用 initialState.pagination.paginationModel。
```
-initialState={{ pagination: { page: 1, pageSize: 10 } }}
+initialState={{ pagination: { paginationModel: { page: 1, pageSize: 10 } } }}
```

✅ rowsPerPageOptions 属性已重命名为 pageSizeOptions。

-<DataGrid rowsPerPageOptions={[10, 20, 50]} />
+<DataGrid pageSizeOptions={[10, 20, 50]} />

`apiRef` 方法

✅ apiRef.current.getRowIndex 方法已被移除。请改用 apiRef.current.getRowIndexRelativeToVisibleRows。
✅ apiRef.current.setFilterLinkOperator 方法已重命名为 apiRef.current.setFilterLogicOperator。

apiRef.current.updateColumn 方法已被移除。请改用 apiRef.current.updateColumns。

-apiRef.current.updateColumn({ field: 'name', width: 100 });
+apiRef.current.updateColumns([{ field: 'name', width: 100 }]);

apiRef.current.getColumnsMeta 方法已被移除。请改用 gridColumnsTotalWidthSelector 或 gridColumnPositionsSelector 选择器。

-const { totalWidth, positions } = apiRef.current.getColumnsMeta();
+const totalWidth = gridColumnsTotalWidthSelector(apiRef);
+const positions = gridColumnPositionsSelector(apiRef);

apiRef.current.setDensity 签名已更改。它仅接受 density: GridDensity 作为单个参数。
apiRef.current.getVisibleRowModels 方法已被移除。请改用 gridExpandedSortedRowEntriesSelector 选择器。
apiRef.current.showError 方法已被移除。用于错误的 UI 不再由网格处理。

一些内部未记录的 apiRef 方法和属性已被移除。

如果您不使用未记录的属性 - 您可以跳过下面的列表。否则，请检查列表，如果 apiRef 中缺少某些内容，请打开 issue。

已移除的未记录方法和属性列表


`getLogger`
`windowRef`
`footerRef`
`headerRef`
`columnHeadersElementRef`
`columnHeadersContainerElementRef`
`unstable_caches`
`unstable_eventManager`
`unstable_requestPipeProcessorsApplication`
`unstable_registerPipeProcessor`
`unstable_registerPipeApplier`
`unstable_storeDetailPanelHeight`
`unstable_detailPanelHasAutoHeight`
`unstable_calculateColSpan`
`unstable_rowHasAutoHeight`
`unstable_getLastMeasuredRowIndex`
`unstable_getViewportPageSize`
`unstable_updateGridDimensionsRef`
`unstable_getRenderContext`
`unstable_registerStrategyProcessor`
`unstable_applyStrategyProcessor`
`unstable_getActiveStrategy`
`unstable_setStrategyAvailability`
`unstable_setCellEditingEditCellValue`
`unstable_getRowWithUpdatedValuesFromCellEditing`
`unstable_setRowEditingEditCellValue`
`unstable_getRowWithUpdatedValuesFromRowEditing`
`unstable_runPendingEditCellValueMutation`
`unstable_moveFocusToRelativeCell`
`unstable_updateControlState`
`unstable_registerControlState`

筛选

✅ GridFilterItem['columnField'] 已重命名为 GridFilterItem['field']
✅ GridFilterItem['operatorValue'] 已重命名为 GridFilterItem['operator']
现在需要 GridFilterItem['operator']。
GridFilterInputValue 组件不能再与 singleSelect 列一起使用。请改用 GridFilterInputSingleSelect。
✅ GridLinkOperator 枚举已重命名为 GridLogicOperator。
GridFilterModel['linkOperator'] 类型已重命名为 GridFilterModel['logicOperator']。
✅ GridFilterForm 和 GridFilterPanel 组件的 linkOperators 属性已重命名为 logicOperators。
✅ GridFilterForm 组件的 linkOperatorInputProps 属性已重命名为 logicOperatorInputProps。
✅ GridFilterForm 组件中的 filterFormProps.linkOperatorInputProps 属性已重命名为 filterFormProps.logicOperatorInputProps。
✅ GridLocaleText['filterPanelLinkOperator'] 属性已重命名为 GridLocaleText['filterPanelLogicOperator']。

编辑

✅ 默认启用的编辑 API 已被新的 API 替换，该 API 包含对服务器端持久性、验证和自定义的更好支持。此新的编辑功能已在 v5 中通过 newEditingApi 实验性标志提供。在 v6 中，可以移除此标志。
```
 <DataGrid
-  experimentalFeatures={{ newEditingApi: true }}
 />
```
✅ 聚合和行固定不再是实验性功能。现在可以移除标志 experimentalFeatures.aggregation 和 experimentalFeatures.rowPinning。
```
 <DataGridPremium
-  experimentalFeatures={{
-   aggregation: true,
-   rowPinning: true,
-  }}
 />
```
editCellPropsChange 事件已被移除。如果您仍然需要它，请提交新的 issue，以便我们可以提出替代方案。
cellEditCommit 事件已被移除，可以使用 processRowUpdate 属性代替。更多信息，请查看有关该主题的文档部分。
editRowsModel 和 onEditRowsModelChange 属性已被移除。可以使用 cellModesModel 或 rowModesModel 属性来实现相同的目标。
GridEditRowsModel 类型已被移除。
以下 API 方法已被移除
- 使用 apiRef.current.stopCellEditMode 替换 apiRef.current.commitCellChange
- 使用 apiRef.current.startCellEditMode 替换 apiRef.current.setCellMode(id, field, 'edit')
- 使用 apiRef.current.stopRowEditMode 替换 apiRef.current.commitRowChange
- 使用 apiRef.current.startRowMode 替换 apiRef.current.setRowMode(id, 'edit')
- 使用 cellModesModel 或 rowModesModel 属性替换 apiRef.current.setEditRowsModel。

其他导出

useGridApi hook 已被移除。请改用 apiRef.current。
useGridState hook 已被移除。请改用 apiRef.current.state、apiRef.current.setState 和 apiRef.current.forceUpdate。
getGridColDef 实用程序函数已被移除。
GridColumns 类型已被移除。请改用 GridColDef[]。
GridActionsColDef 接口已被移除。请改用 GridColDef。
GridEnrichedColDef 类型已被移除。请改用 GridColDef。
GridStateColDef 类型已被移除。
GridDensityTypes 枚举已被移除。请改用 GridDensity 类型。

如果您使用它来键入 searchPredicate - 请改用 GridColumnsPanelProps['searchPredicate']。

如果您使用它来键入 getApplyFilterFn - 请改用 GridFilterOperator['getApplyFilterFn']。
GridHeaderPlaceholder 组件已被移除。
GridValueGetterFullParams 类型已被移除。
GridSortModelParams 接口已被移除。
GridApiRef 类型已被移除。请改用 React.MutableRefObject<GridApi>。
GridCellValue 类型已被移除。请改用 any 或传递给大多数接口的 V 泛型。
GridRowData 类型已被移除。请改用 GridRowModel。
filterPanelOperators 翻译键已重命名为 filterPanelOperator
MAX_PAGE_SIZE 常量已被移除。
DATA_GRID_DEFAULT_SLOTS_COMPONENTS 导出已被移除。
useGridScrollFn hook 已被移除。
GridCellParams 接口已更改。行泛型现在位于单元格泛型之前。
```
-extends GridCellParams<V, R, F, N> {
+extends GridCellParams<R, V, F, N> {
```
这意味着需要先提供 2 个泛型参数的值，然后再提供您已有的参数的值。
```
-renderCell: (params: GridRenderCellParams<number>) => {
+renderCell: (params: GridRenderCellParams<any, number>) => {
```
GridErrorOverlay 组件已被移除。
GridRowScrollEndParams["virtualRowsCount"] 参数已重命名为 GridRowScrollEndParams["visibleRowsCount"]。
GridCellIdentifier 类型已被移除。请改用 GridCellCoordinates。

✅ CSS 类

一些 CSS 类已被移除或重命名

MUI X v5 类	MUI X v6 类	注意
`.MuiDataGrid-withBorder`	`.MuiDataGrid-withBorderColor`	该类仅设置 `border-color` CSS 属性
`.MuiDataGrid-filterFormLinkOperatorInput`	`.MuiDataGrid-filterFormLogicOperatorInput`

从公共 API 中移除

getGridSingleSelectQuickFilterFn 函数已被移除。您可以复制旧函数并将其传递给 singleSelect 列定义的 getApplyQuickFilterFn 属性。

将 `components` 重命名为 `slots`（可选）

components 和 componentsProps 属性正在分别重命名为 slots 和 slotProps 属性。这是 MUI 维护的所有不同库之间正在进行的缓慢而持续的努力。为了平稳过渡，数据网格同时支持已弃用的 components 属性和新的 slots 属性。

如果您想使用新的 API 并且不想看到已弃用的属性用法，请考虑运行 rename-components-to-slots codemod 来处理属性重命名。

npx @mui/x-codemod@latest v6.0.0/data-grid/rename-components-to-slots <path>

查看 RFC 以获取更多信息。