企业官网建设流程全解析

如何在 Refine 中把 @mui/x-data-grid 从 v4 升级到 v5？

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

这篇文章面向使用 Refine（Material UI 集成@refinedev/mui）搭建后台管理界面的开发者。当@mui/x-data-grid发布新的主版本后，@refinedev/mui的useDataGrid钩子和<DataGrid>组件的用法也随之调整，直接升级数据表格包会导致编译失败或分页等交互失效。目标是完成 Refine 侧适配：更新配套包版本、改写useDataGrid的分页 props、替换被移除的GridColumns类型，让表格功能恢复可用。

有一个版本命名问题需要先说明，它直接来自源文档：Refine 官方迁移文档 的标题是 "v4 to v5"，但正文明确写道 "Material UI released a new major version for@mui/x-data-gridpackage as v6"，并且@refinedev/mui的 peer dependency 更新为^6.6.0。也就是说，文档标题说的是 v5，正文给出的实际目标版本是 v6。本文按文档指定的版本范围操作：@mui/x-data-grid升到 6.x、@refinedev/mui升到 5.x。

升级前确认现状

开始之前，先确认项目当前的依赖状态，这决定后面哪些步骤是必做的：

• 正在使用@refinedev/mui的useDataGrid钩子和<DataGrid>组件；
• @mui/x-data-grid当前是 v4；
• 是否使用了@refinedev/inferencer（Inferencer 包）。因为useDataGrid返回值有变化，Refine 为它发布了主版本升级，文档明确要求："If you're using the Inferencer package, you'll need to update it to4.x.xas well"。没有用到 Inferencer 的项目可以跳过这一步。

第一步：更新配套包版本

文档要求@refinedev/mui必须更新到5.x.x才能配合新版@mui/x-data-grid使用；使用 Inferencer 的项目同时更新它到4.x.x。文档只给出了版本范围，未指定包管理器，下面以 npm 为例（使用 pnpm 等其他包管理器时命令形式相应调整）：

npm install @refinedev/mui@5 npm install @mui/x-data-grid@6

如果项目使用了@refinedev/inferencer：

npm install @refinedev/inferencer@4

除了这两个包，Refine 的 MUI v5 到 v6 迁移文档 给出了一张版本对齐表，用来确认整套@mui/*依赖没有版本错位（该表同时覆盖本次升级，@refinedev/mui5.x 对应@mui/x-data-grid6.x）：

注意第一行的条件：@refinedev/mui5.x 要求@mui/material等保持在 5.x，而不是升到 6.x。如果你同时在做 Material UI v5 到 v6 的升级，那是另一个独立任务，应参考 MUI v5 到 v6 迁移文档，不要和本次数据表格升级混在同一次改动里。

第二步：改写 useDataGrid 的分页 props

useDataGrid钩子的返回值变了：不再返回page、pageSize、onPageChange、onPageSizeChange，改为返回paginationModel和onPaginationModelChange。如果你之前从dataGridProps中解构过这些旧 props，需要按下面文档中的 diff 修改（以posts/list.tsx为例）：

const PostList = () => { const { dataGridProps } = useDataGrid(); - const { page, pageSize, onPageChange, onPageSizeChange, ...restDataGridProps } = dataGridProps; + const { paginationModel, onPaginationModelChange, ...restDataGridProps } = dataGridProps; /* ... */ /* Your changes to use the new values */ /* ... */ return ( <DataGrid {...restDataGridProps} - page={page} - pageSize={pageSize} - onPageChange={onPageChange} - onPageSizeChange={onPageSizeChange} + paginationModel={paginationModel} + onPaginationModelChange={onPaginationModelChange} /> ); }

判断标准是全局搜索项目中的旧属性名：凡是把page、pageSize、onPageChange、onPageSizeChange传给<DataGrid>或做自定义处理的地方，都要换成新 API。useDataGrid 的当前文档 也确认了升级后的分页用法：钩子通过paginationMode、paginationModel、onPaginationModelChange三个 props 与<DataGrid>配合，其中paginationMode保留在restDataGridProps展开里即可，文档示例中单独显式传出的只有paginationModel和onPaginationModelChange。

第三步：GridColumns 换成 GridColDef 数组

@mui/x-data-grid新版本移除了GridColumns类型，定义<DataGrid>的columns时必须改用GridColDef数组。这是 Refine 在更新 Material UI 示例时实际遇到的问题，文档专门列出：

import React from "react"; import { List, useDataGrid } from "@refinedev/mui"; - import { DataGrid, GridColumns } from "@mui/x-data-grid"; + import { DataGrid, GridColDef } from "@mui/x-data-grid"; import { ICategory, IPost } from "interfaces"; export const PostList: React.FC = () => { const { dataGridProps } = useDataGrid<IPost>(); - const columns = React.useMemo<GridColumns<IPost>>( + const columns = React.useMemo<GridColDef<IPost>[]>( () => [/* ... */], [], ); return ( <List> <DataGrid {...dataGridProps} columns={columns} /> </List> ); };

ICategory、IPost是示例中的业务接口，替换成你项目里定义的记录类型即可；列定义数组本身不用改动。

结果验证

Refine 的迁移文档没有给出统一的成功日志或验收命令，它明确说明本文档 "won't cover all the changes"，完整的变更清单以 MUI 官方的 DataGrid 迁移指南为准。因此验证分两层：

1. Refine 侧检查项（来自上述文档列出的全部必改点）：
   • 依赖版本：@refinedev/mui为 5.x.x，@mui/x-data-grid为 6.x.x（peer dependency 为^6.6.0）；使用 Inferencer 时其为 4.x.x，且与版本对齐表一致；
   • 代码中没有残留page、pageSize、onPageChange、onPageSizeChange传给<DataGrid>的用法，也没有GridColumns的 import；
   • 运行 TypeScript 编译，由GridColumns类型被移除引发的类型错误全部消除。
2. DataGrid 侧完整变更：Refine 文档只覆盖与 Refine 相关的部分，@mui/x-data-grid自身其余的破坏性变更不在本文范围内，需要对照 MUI 官方的 DataGrid 迁移指南逐项核对（Refine 文档中的外链指向 mui.com 官方页面）。

如果验证中发现某个 API 行为不符，先确认版本对齐表没有错位（例如@mui/material被误升到 6.x），再回到官方指南查找对应条目。

限制与后续

• 本文只覆盖 Refine 相关的最小改动集：包版本、useDataGrid分页 props、GridColumns类型三处。数据表格的其他破坏性变更不在 Refine 文档承诺范围内。
• 如果之后要继续把@mui/x-data-grid升到 7.x（伴随 Material UI v6），那是另一条升级路径，@refinedev/mui需要升到 6.x、@refinedev/inferencer升到 5.x，见 MUI v5 到 v6 迁移文档；所有 MUI 相关迁移文档的入口是 Migration Guides for Material UI。

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine