從 v6 遷移至 v7

本指南描述了將資料網格從 v6 遷移至 v7 所需的變更。

簡介

這是將 @mui/x-data-grid 從 v6 升級至 v7 的參考指南。若要深入瞭解新主要版本的變更，請查看關於 MUI X v7 發佈的部落格文章。

開始使用新版本

在 package.json 中，將資料網格套件的版本變更為 ^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 套件更新至此版本或更新的版本。

更新授權套件

如果您使用的是資料網格的商業版本（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",

執行程式碼修改 (codemods)

preset-safe 程式碼修改將自動調整您的大部分程式碼，以應對 v7 中的重大變更。您可以執行 v7.0.0/data-grid/preset-safe 僅針對資料網格，或執行 v7.0.0/preset-safe 以針對其他 MUI X 元件，例如日期和時間選擇器。

當選擇 <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 程式碼修改處理的重大變更會以 ✅ 表情符號在螢幕右側的目錄中或在處理的特定點旁邊標示。

如果您已套用 v7.0.0/data-grid/preset-safe（或 v7.0.0/preset-safe）程式碼修改，則您應該不需要對這些項目採取任何進一步的動作。如果重大變更的特定部分不屬於程式碼修改或需要一些手動操作，則會在每個章節的末尾列出。

所有其他變更都必須手動處理。

並非所有使用案例都涵蓋在程式碼修改中。在某些情況下，例如 props 擴展、跨檔案依賴關係等，變更無法正確識別，因此必須手動處理。

例如，如果程式碼修改嘗試重新命名一個 prop，但此 prop 使用擴展運算符隱藏，則它將不會如預期般轉換。

<DataGrid {...newProps} />

執行程式碼修改後，請務必測試您的應用程式，並確保您沒有任何主控台錯誤。

如果您在進行遷移時需要協助，請隨時開啟 issue 以取得支援。

重大變更

由於 v7 是主要版本，因此包含一些影響公開 API 的變更。這些變更旨在提高一致性、改善穩定性，並為新功能騰出空間。以下說明從 v6 遷移至 v7 所需採取的步驟。

捨棄舊版套件 (bundle)

所有 MUI X 套件已移除對 IE 11 的支援。不再包含用於支援舊版瀏覽器（如 IE 11）的 legacy 套件。

捨棄 Webpack 4 支援

捨棄舊版瀏覽器支援也表示我們不再轉譯現代瀏覽器原生支援的某些功能，例如 Nullish Coalescing 和 Optional Chaining。

Webpack 4 不支援這些功能，因此如果您使用的是 Webpack 4，則需要自行轉譯這些功能，或升級至 Webpack 5。

以下是如何在 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 變更

資料網格的版面配置已大幅更改為使用 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 中移除一些功能旗標 (feature flags)。這些功能現在已穩定，並預設為啟用狀態

行為變更

現在可以使用 initialState、各自的受控模型或 API 物件，以程式設計方式控制已停用的欄位特定功能，例如 hiding、sorting、filtering、pinning、row grouping 等。

以下是受影響的功能、欄位定義旗標和用於停用它們的 props，以及用於以程式設計方式控制它們的相關 props 和 API 方法的清單。

狀態存取

某些 selectors 現在需要傳遞 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_ 為前綴。
欄位分組 selectors 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'] 的簽名 (signature) 已變更，以提高效能

-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 傳遞至資料網格，則需要執行以下其中一項操作

將其移至 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)}
 />

已移除 selector 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 實驗性旗標，資料網格現在預設使用改良的協助工具實作。如果您正在使用 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"。
- 資料網格儲存格現在具有 role="gridcell" 而不是 role="cell"。

編輯

已移除 rowEditCommit 事件和相關的 prop onRowEditCommit。可以使用 processRowUpdate prop 來代替。

其他匯出項目

已變更地區設定的匯入路徑

-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 元件不再匯出，因為它原本不打算在資料網格外部使用。
工具列可組合元件 GridToolbarColumnsButton、GridToolbarFilterButton、GridToolbarDensity 和 GridToolbarExport 中的按鈕現在都使用工具提示元件包裝，並具有一致的介面。為了覆寫與工具列按鈕或其對應工具提示相對應的某些 props，您可以使用 slotProps prop。以下是範例 diff。請參閱工具列章節以取得更多詳細資訊。

 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 來設定列的 hover 狀態樣式。
已移除釘選欄位的 .MuiDataGrid--pinnedColumns-(left\|right) 類別。
已移除 .MuiDataGrid-cell--withRenderer 類別。
儲存格元素預設不是 display: flex。您可以在欄位定義中新增 display: 'flex' 以還原此行為。

注意：如果您使用的是動態列高度，這也表示儲存格預設不再垂直置中，您可能需要為所有非動態欄位設定 display: 'flex'。這也可能會影響文字省略 (text-ellipsis)，您可以透過新增自己的包裝器並使用 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.dev.org.tw/material-ui/customization/palette/#customization 我們將在調色盤中新增一個新的色彩名稱以進行額外自訂，請閱讀 #12443 以取得更多詳細資訊。

公開 API 的變更

方法 getRootDimensions() 現在傳回非 null 值。
欄位 mainElementRef 現在始終為非 null。
欄位 rootElementRef 現在始終為非 null。
欄位 virtualScrollerRef 現在始終為非 null。
事件 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>。