react-admin v5 升级完全指南:从 v4 到 v5 的破坏性变更、依赖迁移与代码改造手册
react-admin v5 升级完全指南:从 v4 到 v5 的破坏性变更、依赖迁移与代码改造手册
react-admin v5 以「清理废弃特性、升级底层依赖」为核心目标,相比以往版本升级路径更平滑,但仍然包含一批需要开发者逐一处理的破坏性变更。本文以 docs/Upgrade.md 为骨架,结合当前仓库源码(packages/ra-core、packages/ra-ui-materialui、packages/react-admin 等)对每项变更的原理与迁移步骤进行深度解读。读完本文,你将能够:把应用升级到 React 18 与 @tanstack/react-query v5;理解 v5 中布局、列表、表单、路由、类型系统与主题的每一项行为变化;掌握 TestMemoryRouter、codemod 等自动化迁移工具的正确用法,并能在升级后快速修复编译错误与回归问题。
IE11 已不再受支持
react-admin v5 基于 React 18 构建,而 React 18 官方已放弃对 Internet Explorer 的支持。因此 v5 不再支持 IE11。如果业务仍有 IE11 兼容的硬性需求,只能停留在 react-admin v4 上,并在后续规划浏览器兼容策略(例如针对旧浏览器的降级方案或独立入口)。
依赖升级
升级到 React 18
react-admin v5 使用 React 18(packages/react-admin/package.json 中 peerDependencies 声明为 react: ^18.0.0 || ^19.0.0)。如果你以库的方式在自己的应用中使用 react-admin,也必须同步升级到 React 18 或 19。
绝大多数项目的升级动作集中在应用入口文件:React 18 引入了新的并发渲染根 API createRoot,替代旧的 render 调用:
-import { render } from 'react-dom';
-const container = document.getElementById('app');
-render(<App tab="home" />, container);
+import { createRoot } from 'react-dom/client';
+const container = document.getElementById('app');
+const root = createRoot(container); // createRoot(container!) 若使用 TypeScript
+root.render(<App tab="home" />);
React 18 默认进行更多批处理(batching),因此在事件回调、Promise 回调、原生事件处理器等场景下的多次状态更新会被自动合并为一次渲染,带来开箱即用的性能提升。若应用中有依赖「非批处理」行为的代码(例如在异步回调中期望每次 setState 都触发一次渲染),需要调整这些假设。
用 @tanstack/react-query 替换 react-query
react-admin v5 将数据请求层从 react-query v3 升级到了 TanStack Query v5,包名随之改为 @tanstack/react-query(API 基本保持一致)。这一版本支持 React 18,并带来性能优化与新特性。在 react-admin 的依赖中可以看到 "@tanstack/react-query": "^5.83.0"。
如果你在业务代码中直接使用过 react-query,需要先改包名:
-import { useQuery } from 'react-query';
+import { useQuery } from '@tanstack/react-query';
v5 最核心的 API 变化是:所有 react-query hooks、queryClient 与 queryCache 的方法都改为接收单个对象参数:
- useQuery(key, fn, options)
+ useQuery({ queryKey, queryFn, ...options })
- useInfiniteQuery(key, fn, options)
+ useInfiniteQuery({ queryKey, queryFn, ...options })
- useMutation(fn, options)
+ useMutation({ mutationFn, ...options })
- useIsFetching(key, filters)
+ useIsFetching({ queryKey, ...filters })
- useIsMutating(key, filters)
+ useIsMutating({ mutationKey, ...filters })
- queryClient.isFetching(key, filters)
+ queryClient.isFetching({ queryKey, ...filters })
- queryClient.ensureQueryData(key, filters)
+ queryClient.ensureQueryData({ queryKey, ...filters })
- queryClient.getQueriesData(key, filters)
+ queryClient.getQueriesData({ queryKey, ...filters })
- queryClient.setQueriesData(key, updater, filters, options)
+ queryClient.setQueriesData({ queryKey, ...filters }, updater, options)
- queryClient.removeQueries(key, filters)
+ queryClient.removeQueries({ queryKey, ...filters })
- queryClient.resetQueries(key, filters, options)
+ queryClient.resetQueries({ queryKey, ...filters }, options)
- queryClient.cancelQueries(key, filters, options)
+ queryClient.cancelQueries({ queryKey, ...filters }, options)
- queryClient.invalidateQueries(key, filters, options)
+ queryClient.invalidateQueries({ queryKey, ...filters }, options)
- queryClient.refetchQueries(key, filters, options)
+ queryClient.refetchQueries({ queryKey, ...filters }, options)
- queryClient.fetchQuery(key, fn, options)
+ queryClient.fetchQuery({ queryKey, queryFn, ...options })
- queryClient.prefetchQuery(key, fn, options)
+ queryClient.prefetchQuery({ queryKey, queryFn, ...options })
- queryClient.fetchInfiniteQuery(key, fn, options)
+ queryClient.fetchInfiniteQuery({ queryKey, queryFn, ...options })
- queryClient.prefetchInfiniteQuery(key, fn, options)
+ queryClient.prefetchInfiniteQuery({ queryKey, queryFn, ...options })
- queryCache.find(key, filters)
+ queryCache.find({ queryKey, ...filters })
- queryCache.findAll(key, filters)
+ queryCache.findAll({ queryKey, ...filters })
使用 Codemod 自动化迁移
TanStack Query 官方提供了 codemod 来降低迁移成本。请注意以下前提:
免责声明
codemod 是「尽力而为」的迁移辅助工具,请务必彻底审查生成的代码!部分边界情况无法被 codemod 发现,请留意日志输出。
应用 codemod 后可能破坏代码格式,请记得运行
prettier和/或eslint。
在把 @tanstack/react-query 加入依赖后,对 .js / .jsx 文件运行:
npx jscodeshift@latest ./path/to/src/ \
--extensions=js,jsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
对 .ts / .tsx 文件运行:
npx jscodeshift@latest ./path/to/src/ \
--extensions=ts,tsx \
--parser=tsx \
--transform=./node_modules/@tanstack/react-query/build/codemods/src/v5/remove-overloads/remove-overloads.cjs
根据代码库实际情况,可能还需要运行以下 codemod:
v4/replace-import-specifier.cjs—— 替换导入路径v4/key-transformation.cjs—— 转换查询 keyv5/remove-overloads/remove-overloads.cjs—— 移除旧的重载签名v5/is-loading/is-loading.cjs—— 迁移isLoading语义(v5 中isLoading表示「无数据 + 加载中」,原isFetching的语义由isPending承担)v5/keep-previous-data/keep-previous-data.cjsv5/rename-properties/rename-properties.cjsv5/rename-hydrate/rename-hydrate.cjs
次要依赖的破坏性升级
react-admin 的若干次要依赖同步升级到了各自的最新大版本:
| 依赖 | 升级范围 | 影响面 |
|---|---|---|
| date-fns | v2 → v3 | 日期处理相关 API 变化 |
| inflection | v1 → v3 | 单词单复数/驼峰转换相关行为 |
| react-dropzone | v12 → v14 | 影响 <FileInput> / <ImageInput> 的 accept prop(见下文) |
| react-error-boundary | v3 → v4 | 错误边界组件 API 调整 |
| react-i18next | v13 → v14 | 国际化相关 hook/组件调整 |
每个大版本都带有各自的破坏性变更,需要对照其 changelog 检查业务代码。如果你在自己的应用中也直接使用这些依赖,请使用相近版本,避免同一依赖被打包两份(双实例会导致 context 不共享、行为异常)。
UI 变更
输入组件默认占满全宽
在默认主题中,v5 的所有输入组件默认 fullWidth。这让表单默认观感更好,也方便将输入嵌套在 <Grid> 下构建自定义表单布局。
如果这会破坏你现有的表单布局,可以在应用主题中重置 fullWidth 默认值。未使用自定义主题时,基于默认主题创建一个:
-import { Admin } from 'react-admin';
+import { Admin, defaultTheme } from 'react-admin';
+import { deepmerge } from '@mui/utils';
import { dataProvider } from './dataProvider';
+const theme = deepmerge(defaultTheme, {
+ components: {
+ MuiFormControl: { defaultProps: { fullWidth: undefined } },
+ MuiTextField: { defaultProps: { fullWidth: undefined } },
+ MuiAutocomplete: { defaultProps: { fullWidth: undefined } },
+ RaSimpleFormIterator: { defaultProps: { fullWidth: undefined } },
+ RaTranslatableInputs: { defaultProps: { fullWidth: undefined } },
+ }
+});
const MyApp = () => (
- <Admin dataProvider={dataProvider}>
+ <Admin dataProvider={dataProvider} theme={theme}>
...
</Admin>
);
如果已有自定义主题,则在其 components 中补上同样的五个 defaultProps 覆盖项(MuiFormControl、MuiTextField、MuiAutocomplete、RaSimpleFormIterator、RaTranslatableInputs)。注意此行为只影响「默认主题」下的表现,自定义主题默认不会自动获得全宽样式。
链接默认显示下划线
默认主题中,链接(<Link>)默认带下划线。若希望去掉下划线,给 react-admin 的 <Link> 组件显式设置 underline="none":
import { Link } from 'react-admin';
const MyComponent = () => (
- <Link to="/foo">Foo</Link>
+ <Link to="/foo" underline="none">Foo</Link>
);
部分内部使用 <Link> 的组件也会随之渲染下划线,包括:<Count>、<EmailField>、<FileField>、<ReferenceField>、<ReferenceManyCount>、<UrlField>。<SingleFieldList> 仍然默认关闭下划线。
对这些组件,需要通过 sx 属性移除下划线。例如 <ReferenceField>:
const CompanyField = () => (
- <ReferenceField source="company_id" reference="companies" />
+ <ReferenceField source="company_id" reference="companies" sx={{
+ '& a': { textDecoration: 'none' }
+ }} />
)
深色主题默认启用
v5 在浅色主题之外内置了深色主题:应用栏会渲染主题切换按钮(<ToggleThemeButton>),并根据用户操作系统的偏好自动选择默认主题(相关机制可参考 AppTheme.md 中的浅色/深色主题章节)。
如果不需要深色模式,必须显式关闭:
-<Admin>
+<Admin darkTheme={null}>
...
</Admin>
Data Provider 变更
ra-data-graphql 与 ra-data-graphql-simple 不再返回 Promise
以往 GraphQL data provider 构建函数返回一个 Promise,导致 admin 初始化代码复杂(需要 useState + useEffect 组合,并在加载完成前渲染占位内容)。v5 中这一层包装不再需要。
从源码看,ra-data-graphql-simple 的默认导出现在直接返回 DataProvider 对象(见 packages/ra-data-graphql-simple/src/index.ts),ra-data-graphql 的 buildDataProvider 同理。迁移后可以同步移除 data provider 的加载态:
// in App.js
import React from 'react';
import { Component } from 'react';
import buildGraphQLProvider from 'ra-data-graphql-simple';
import { Admin, Resource } from 'react-admin';
import { PostCreate, PostEdit, PostList } from './posts';
+ const dataProvider = buildGraphQLProvider({ clientOptions: { uri: 'http://localhost:4000' } });
const App = () => {
- const [dataProvider, setDataProvider] = React.useState(null);
- React.useEffect(() => {
- buildGraphQLProvider({ clientOptions: { uri: 'http://localhost:4000' } })
- .then(graphQlDataProvider => setDataProvider(() => graphQlDataProvider));
- }, []);
-
- if (!dataProvider) {
- return <div>Loading < /div>;
- }
return (
<Admin dataProvider={dataProvider} >
<Resource name="Post" list={PostList} edit={PostEdit} create={PostCreate} />
</Admin>
);
}
export default App;
应用根组件与布局
<Admin menu> 不再受支持
<Admin menu> prop 自 4.0 起已被标记废弃,v5 正式移除。自定义应用菜单需要在自定义 Layout 中完成:
-import { Admin } from 'react-admin';
+import { Admin, Layout } from 'react-admin';
import { MyMenu } from './MyMenu';
+const MyLayout = ({ children }) => (
+ <Layout menu={MyMenu}>{children}</Layout>
+);
const App = () => (
- <Admin menu={MyMenu} dataProvider={dataProvider}>
+ <Admin layout={MyLayout} dataProvider={dataProvider}>
...
</Admin>
);
<Admin history> prop 已被移除
<Admin history> prop 自 v4 起废弃,v5 移除。该 prop 最常见的用途是在单元测试与 story 中传入 MemoryRouter 并控制 initialEntries。为此 react-admin v5 导出了 TestMemoryRouter 组件。
从 packages/ra-core/src/routing/TestMemoryRouter.tsx 的源码可以看到:它本质上是 react-router createMemoryRouter + RouterProvider 的封装,因此支持 data router 的全部能力(这是旧 MemoryRouter 不具备的,也是 warnWhenUnsavedChanges 等特性能在测试中工作的前提),同时还额外提供 locationCallback(获取当前 location)与 navigateCallback(在测试中发起导航)两个回调 prop。
迁移示例:
import { render, screen } from '@testing-library/react';
-import { createMemoryHistory } from 'history';
-import { CoreAdminContext } from 'react-admin';
+import { CoreAdminContext, TestMemoryRouter } from 'react-admin';
import * as React from 'react';
describe('my test suite', () => {
it('my test', async () => {
- const history = createMemoryHistory({ initialEntries: ['/'] });
render(
+ <TestMemoryRouter initialEntries={['/']}>
- <CoreAdminContext history={history}>
+ <CoreAdminContext>
<div>My Component</div>
</CoreAdminContext>
+ </TestMemoryRouter>
);
await screen.findByText('My Component');
});
});
Codemod
仓库为迁移测试代码提供了 codemod(见 packages/ra-core/codemods/replace-Admin-history.ts),它会将 <Admin history> / <CoreAdminContext history> 等用法替换为 <TestMemoryRouter>,并自动处理 history 包的 import。
免责声明
该 codemod 用于迁移 react-admin 自身的测试套件,并非为覆盖所有场景而设计,也未在其他代码库上验证过。你可以把它作为迁移起点,但请务必彻底审查生成的改动!
应用 codemod 后可能破坏代码格式,请记得运行
prettier和/或eslint。
对 .js / .jsx 文件:
npx jscodeshift ./path/to/src/ \
--extensions=js,jsx \
--transform=./node_modules/ra-core/codemods/replace-Admin-history.ts
对 .ts / .tsx 文件:
npx jscodeshift ./path/to/src/ \
--extensions=ts,tsx \
--parser=tsx \
--transform=./node_modules/ra-core/codemods/replace-Admin-history.ts
仓库中还提供了 replace-MemoryRouter.ts 与 replace-Datagrid-DataTable.ts 等其他 codemod,可一并参考(见 packages/ra-core/codemods)。
<HistoryRouter> 已被移除
随 <Admin history> 一起移除的还有(未文档化的)<HistoryRouter> 组件。它的主要用途同样是测试中控制 initialEntries,因此同样用 TestMemoryRouter 替代:
import { render, screen } from '@testing-library/react';
-import { createMemoryHistory } from 'history';
-import { CoreAdminContext, HistoryRouter } from 'react-admin';
+import { CoreAdminContext, TestMemoryRouter } from 'react-admin';
import * as React from 'react';
describe('my test suite', () => {
it('my test', async () => {
- const history = createMemoryHistory({ initialEntries: ['/'] });
render(
- <HistoryRouter history={history}>
+ <TestMemoryRouter initialEntries={['/']}>
<CoreAdminContext>
<div>My Component</div>
</CoreAdminContext>
- </HistoryRouter>
+ </TestMemoryRouter>
);
await screen.findByText('My Component');
});
});
自定义 Layout 不再接收额外 props
react-admin 过去会向自定义 Layout 注入 4 个 props:children、dashboard、menu 和 title。v5 只注入 children。其余值需要通过 hooks 获取:
+import { useHasDashboard, useDefaultTitle } from 'react-admin';
-const MyLayout = ({ children, dashboard, title }) => (
+const MyLayout = ({ children }) => {
- const hasDashboard = !!dashboard;
+ const hasDashboard = useHasDashboard();
+ const title = useDefaultTitle();
// ...
}
const App = () => (
<Admin layout={MyLayout} dataProvider={dataProvider}>
...
</Admin>
);
关于 menu:由于 <Admin menu> 已移除,react-admin 不再注入该 prop,但你仍然可以通过默认 Layout 的 menu prop 自定义菜单:
import { Layout } from 'react-admin';
import { MyMenu } from './MyMenu';
const MyLayout = ({ children }) => (
<Layout menu={MyMenu}>{children}</Layout>
);
const App = () => (
<Admin layout={MyLayout} dataProvider={dataProvider}>
...
</Admin>
);
从源码看,这两个 hook 的实现非常轻量:useHasDashboard 读取 HasDashboardContext(见 packages/ra-core/src/core/HasDashboardContext.ts,默认 false),useDefaultTitle 读取 DefaultTitleContext(见 packages/ra-core/src/core/DefaultTitleContext.ts,默认值为 'React Admin')。两者都要求组件位于 <Admin> 提供的 context 之内才能拿到正确值。
自定义 AppBar 不再接收 props
react-admin 过去会向自定义 AppBar 注入 open 与 title 两个 prop,v5 不再注入。需要时改用 hooks:
+import { useSidebarState, useDefaultTitle } from 'react-admin';
-const MyAppBar = ({ open, title }) => (
+const MyAppBar = () => {
+ const [open] = useSidebarState();
+ const title = useDefaultTitle();
// ...
}
const MyLayout = ({ children }) => (
<Layout appBar={MyAppBar}>{children}</Layout>
);
自定义 Menu 不再接收 props
react-admin 过去会向自定义 Menu 注入 hasDashboard prop,v5 不再注入,改用 useHasDashboard hook:
+import { useHasDashboard } from 'react-admin';
-const MyMenu = ({ hasDashboard }) => (
+const MyMenu = () => {
+ const hasDashboard = useHasDashboard();
// ...
}
const MyLayout = ({ children }) => (
<Layout menu={MyMenu}>{children}</Layout>
);
自定义错误页面不再接收 title
react-admin 过去会向自定义错误页面注入 error、errorInfo 与应用默认 title。v5 不再注入 title,改用 useDefaultTitle:
+import { useDefaultTitle } from 'react-admin';
-const MyError = ({ error, errorInfo, title }) => (
+const MyError = ({ error, errorInfo }) => {
+ const title = useDefaultTitle();
// ...
}
const MyLayout = ({ children }) => (
<Layout error={MyError}>{children}</Layout>
);
自定义 Catch All 页面不再接收 title
react-admin 过去会向自定义 catch all 页面注入默认 title,v5 不再注入,改用 useDefaultTitle:
+import { useDefaultTitle } from 'react-admin';
-const MyCatchAll = ({ title }) => (
+const MyCatchAll = () => {
+ const title = useDefaultTitle();
// ...
}
const App = () => (
<Admin catchAll={MyCatchAll} dataProvider={dataProvider}>
...
</Admin>
);
List 组件变更
列表组件不能再脱离页面独立使用
v5 移除了一项未文档化特性:部分面向列表页的组件此前可以脱离列表页、仅凭 props 工作。v5 中这些组件必须处于 ListContext 之内:
<BulkActionsToolbar><BulkDeleteWithConfirmButton><BulkDeleteWithUndoButton><BulkExportButton><BulkUpdateWithConfirmButton><BulkUpdateWithUndoButton><EditActions><ExportButton><FilterButton><FilterForm><ListActions><Pagination><UpdateWithConfirmButton><UpdateWithUndoButton>
继续使用这些组件时,需要用 <ListContextProvider> 包裹:
const MyPagination = ({
page,
perPage,
total,
setPage,
setPerPage,
}) => {
return (
- <Pagination page={page} perPage={perPage} total={total} setPage={setPage} setPerPage={setPerPage} />
+ <ListContextProvider value={{ page, perPage, total, setPage, setPerPage }}>
+ <Pagination />
+ </ListContextProvider>
);
};
以下组件不受影响,仍可独立使用:<Datagrid>、<SimpleList>、<SingleFieldList>。
<List hasCreate> 不再受支持
要强制某个资源列表显示「创建」按钮(即使该资源没有定义 create 组件),改为给 List 传入自定义 actions:
-import { List } from 'react-admin';
+import { List, ListActions } from 'react-admin';
const PostList = () => (
- <List hasCreate>
+ <List actions={<ListActions hasCreate />}>
...
</List>
);
<Datagrid rowClick> 默认值不再是 false
只要资源定义了 Show 或 Edit 视图(依据 Resource.md 的资源定义),<Datagrid> 就会让行可点击。如果此前依赖「行默认不可点击」的行为,现在必须显式关闭:
-<Datagrid>
+<Datagrid rowClick={false}>
...
</Datagrid>
<Datagrid expand> 面板不再接收任何 props
此前 datagrid 展开面板可以从 props 中读取当前 resource、record、id(未文档化特性)。v5 中展开面板由 <Datagrid> 无 props 渲染。需要这些数据时改用 hooks:
-const PostExpandPanel = ({ record, resource, id }) => {
+const PostExpandPanel = () => {
+ const record = useRecordContext();
+ const resource = useResourceContext();
+ const id = record?.id;
// ...
}
独立使用的 <Datagrid> 必须传入 resource prop
在 <List> 之外使用 <Datagrid> 时,现在必须显式传入 resource:
const sort = { field: 'id', order: 'DESC' };
const MyCustomList = () => {
const { data, total, isPending } = useGetList('books', {
pagination: { page: 1, perPage: 10 },
sort,
});
return (
<Datagrid
+ resource="books"
data={data}
total={total}
isPending={isPending}
sort={sort}
bulkActionButtons={false}
>
<TextField source="id" />
<TextField source="title" />
</Datagrid>
);
};
setFilters 默认不再防抖
如果你用 useListContext 的 setFilters 更新过滤器,请注意 v5 中它默认不再防抖。需要防抖时,把第三个参数传 true:
import { useListContext } from 'react-admin';
const MyFilter = () => {
const { filterValues, setFilters } = useListContext();
const handleChange = (event) => {
- setFilters({ ...filterValues, [event.target.name]: event.target.value });
+ setFilters({ ...filterValues, [event.target.name]: event.target.value }, undefined, true);
};
return (
<form>
<input name="country" value={filterValues.country} onChange={handleChange} />
<input name="city" value={filterValues.city} onChange={handleChange} />
<input name="zipcode" value={filterValues.zipcode} onChange={handleChange} />
</form>
);
};
bulkActionButtons 语法更新
bulkActionButtons prop 从 <List> 移到了 <Datagrid> 上:
const PostList = () => (
- <List bulkActionButtons={<BulkActionButtons />}>
+ <List>
- <Datagrid>
+ <Datagrid bulkActionButtons={<BulkActionButtons />}>
...
</Datagrid>
</List>
);
此外,作为 bulkActionButtons 传入的按钮不再接收任何 prop。需要当前过滤器值或已选 ids 时,改用 useListContext:
-const BulkResetViewsButton = ({ resource, selectedIds }) => {
+const BulkResetViewsButton = () => {
+ const { resource, selectedIds } = useListContext();
const notify = useNotify();
const unselectAll = useUnselectAll(resource);
const [updateMany, { isPending }] = useUpdateMany();
const handleClick = () => {
updateMany(
resource,
{ ids: selectedIds, data: { views: 0 } },
{
onSuccess: () => {
notify('Views reset');
unselectAll();
},
onError: () => notify('Views not reset', { type: 'error' }),
}
);
}
return (
<Button
label="Reset views"
disabled={isPending}
onClick={() => updateMany()}
>
<VisibilityOff />
</Button>
);
};
<PaginationLimit> 组件已被移除
废弃已久的 <PaginationLimit> 组件在 v5 中被移除。分页数量限制功能可改用分页组件的相应参数(如 <Pagination> 的 perPage 相关配置)实现。
<DatagridBody> 不再向 <DatagridRow> 提供 record prop
<DatagridBody> 不再把 record 作为 prop 传给子级 <DatagridRow>,而是为每一行提供 RecordContext。自定义行组件应改从 useRecordContext 读取记录:
const MyDatagridRow = ({
- record,
- id,
onToggleItem,
children,
selected,
selectable,
}: DatagridRowProps) => {
+ const record = useRecordContext();
+ return record ? (
- <RecordContextProvider value={record}>
<TableRow>
</TableCell>
{selectable && (
<Checkbox
checked={selected}
onClick={event => {
if (onToggleItem) {
- onToggleItem(id, event);
+ onToggleItem(record.id, event);
}
}}
/>
)}
</TableCell>
{React.Children.map(children, field =>
React.isValidElement<FieldProps>(field) &&
field.props.source ? (
- <TableCell key={`${id}-${field.props.source}`}>{field}</TableCell>
+ <TableCell key={`${record.id}-${field.props.source}`}>{field}</TableCell>
) : null
)}
</TableRow>
- </RecordContextProvider>
) : null;
};
自定义行组件的完整写法可参考 Datagrid.md 的 body 章节。
useRecordSelection 的参数已改变
useRecordSelection 的参数从字符串改为包含 resource 属性的对象:
const MyComponent = () => {
- const [selectedIds, selectionModifiers] = useRecordSelection('posts');
+ const [selectedIds, selectionModifiers] = useRecordSelection( { resource: 'posts' });
...
};
从 packages/ra-core/src/controller/list/useRecordSelection.ts 的源码看,v5 的新签名 UseRecordSelectionArgs 还提供了两个可选字段:storeKey(自定义存储键,默认 ${resource}.selectedIds)与 disableSyncWithStore(设为 true 时关闭与全局 store 的同步,此时 resource 可选)。返回的 selectionModifiers 提供 select、unselect、toggle、clearSelection 四个操作。
Show 与 Edit 页面变更
自定义 Edit / Show Actions 不再接收任何 props
react-admin 过去会向自定义 edit/show actions 注入 record 与 resource props,v5 不再注入。需要时改用 useRecordContext 与 useResourceContext。若使用的是 <ShowButton> 这类标准按钮(内部已使用这些 hooks),则无需注入任何东西:
-const MyEditActions = ({ data }) => (
+const MyEditActions = () => (
<TopToolbar>
- <ShowButton record={data} />
+ <ShowButton />
</TopToolbar>
);
const PostEdit = () => (
<Edit actions={<MyEditActions />} {...props}>
...
</Edit>
);
输入组件默认 id 改为自动生成
此前输入组件的默认 id 就是其 source。v5 改用 React 的 useId() 自动生成默认 id(更安全,避免页面中重复 id 冲突)。
提示: 你仍可以给任何 react-admin 输入组件显式传 id prop,或者用 useRef 引用。
如果测试中依赖了输入组件的默认 id,请在对应输入上传入自己的 id:
-<TextInput source="name" />
+<TextInput source="name" id="post-name" />
<SimpleFormIterator> 不再克隆其按钮
<SimpleFormIterator> 过去会克隆添加、删除、重排按钮并注入 onClick、className 等 props。如果你的自定义按钮依赖这些注入,应改用以下 hooks:
- 不绑定具体条目的按钮(如添加按钮):使用
useSimpleFormIterator
- import { Button, ButtonProps } from 'react-admin';
+ import { Button, ButtonProps, useSimpleFormIterator } from 'react-admin';
export const MyAddButton = (props: ButtonProps) => {
+ const { add } = useSimpleFormIterator();
- return <Button {...props}>Add</Button>;
+ return <Button {...props} onClick={() => add()}>Add</Button>;
}
- 绑定具体条目的按钮(如删除、重排按钮):使用
useSimpleFormIteratorItem
- import { Button, ButtonProps } from 'react-admin';
+ import { Button, ButtonProps, useSimpleFormIteratorItem } from 'react-admin';
export const MyRemoveButton = (props: ButtonProps) => {
+ const { remove } = useSimpleFormIteratorItem();
- return <Button {...props}>Add</Button>;
+ return <Button {...props} onClick={() => remove()}>Add</Button>;
}
<SimpleFormIterator> 不再克隆其子元素
<SimpleFormIterator>(<ArrayInput> 的配套子组件)的实现改动基本向后兼容,但有一个例外:在 <ArrayInput> 上定义 disabled 不再会级联禁用子输入。若依赖此行为,需要在每个输入上单独指定 disabled:
<ArrayInput disabled={someCondition}>
<SimpleFormIterator>
- <TextInput source="lastName" />
- <TextInput source="firstName" />
+ <TextInput source="lastName" disabled={someCondition} />
+ <TextInput source="firstName" disabled={someCondition} />
</SimpleFormIterator>
</ArrayInput>
<FormDataConsumer> 不再传递 getSource 函数
在 <ArrayInput> 内使用 <FormDataConsumer> 时,其子函数不再收到 getSource 回调。v5 中所有输入组件都能在 <ArrayInput> 内无缝工作,无需再用 getSource 转换 source:
import { Edit, SimpleForm, TextInput, ArrayInput, SelectInput, FormDataConsumer } from 'react-admin';
const PostEdit = () => (
<Edit>
<SimpleForm>
<ArrayInput source="authors">
<SimpleFormIterator>
<TextInput source="name" />
<FormDataConsumer>
{({
formData, // 整个表单数据
scopedFormData, // 当前 ArrayInput 条目的数据
- getSource,
}) =>
scopedFormData && getSource && scopedFormData.name ? (
<SelectInput
- source={getSource('role')}
+ source="role" // 会自动转换为 "authors[0].role"
choices={[{ id: 1, name: 'Head Writer' }, { id: 2, name: 'Co-Writer' }]}
/>
) : null
}
</FormDataConsumer>
</SimpleFormIterator>
</ArrayInput>
</SimpleForm>
</Edit>
);
如果你仍需要访问 <ArrayInput> 内某个输入的有效(完整)source(例如用 setValue 以编程方式改值),请使用 useSourceContext hook:
import { ArrayInput, SimpleFormIterator, TextInput, useSourceContext } from 'react-admin';
import { useFormContext } from 'react-hook-form';
import { Button } from '@mui/material';
const MakeAdminButton = () => {
const sourceContext = useSourceContext();
const { setValue } = useFormContext();
const onClick = () => {
// sourceContext.getSource('role') 例如返回 'users.0.role'
setValue(sourceContext.getSource('role'), 'admin');
};
return (
<Button onClick={onClick} size="small" sx={{ minWidth: 120 }}>
Make admin
</Button>
);
};
const UserArray = () => (
<ArrayInput source="users">
<SimpleFormIterator inline>
<TextInput source="name" helperText={false} />
<TextInput source="role" helperText={false} />
<MakeAdminButton />
</SimpleFormIterator>
</ArrayInput>
);
提示: 如果只需要条目的索引,可以改用 useSimpleFormIteratorItem hook。
Mutation Middleware 不再接收 mutation options
Mutation 中间件不再接收 mutation options 参数:
import * as React from 'react';
import {
useRegisterMutationMiddleware,
CreateParams,
- MutateOptions,
CreateMutationFunction
} from 'react-admin';
const MyComponent = () => {
const createMiddleware = async (
resource: string,
params: CreateParams,
- options: MutateOptions,
next: CreateMutationFunction
) => {
// 在 mutation 之前做点什么
// 调用下一个中间件
- await next(resource, params, options);
+ await next(resource, params);
// 在 mutation 之后做点什么
}
const memoizedMiddleWare = React.useCallback(createMiddleware, []);
useRegisterMutationMiddleware(memoizedMiddleWare);
// ...
}
warnWhenUnsavedChanges 的行为变化
warnWhenUnsavedChanges 比以往更严格:
- 表单提交过程中若触发导航,会弹出确认对话框并阻止导航(提交会在后台继续)。
- 受浏览器限制(
beforeunload弹窗无法自定义文案),关闭浏览器标签页时确认对话框中的文案由浏览器接管,无法自定义。
这些变化能在更多场景下防止数据丢失,且无需修改代码。
但需要注意:warnWhenUnsavedChanges 现在依赖 react-router 的 Data Router 才能工作。react-admin 默认使用 data router,因此 v5 中该功能开箱即用。
如果使用了自定义路由(见 Routing.md 的自定义路由章节)且启用了 warnWhenUnsavedChanges,该功能会被禁用。要恢复它,需将自定义路由迁移到 data router。例如从 BrowserRouter 迁移到 createBrowserRouter + RouterProvider:
import * as React from 'react';
import { Admin, Resource } from 'react-admin';
import { createRoot } from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import dataProvider from './dataProvider';
import posts from './posts';
const App = () => (
- <BrowserRouter>
<Admin dataProvider={dataProvider}>
<Resource name="posts" {...posts} />
</Admin>
- </BrowserRouter>
);
+const router = createBrowserRouter([{ path: '*', element: <App /> }]);
const container = document.getElementById('root');
const root = createRoot(container);
root.render(
<React.StrictMode>
- <App />
+ <RouterProvider router={router} />
</React.StrictMode>
);
全局服务端校验错误消息必须通过 root.serverError 键传递
现在可以在 create/update 请求失败的响应中携带全局服务端错误消息,该消息会以通知(notification)形式渲染。做法是把错误消息放入响应体 errors 对象的 root.serverError 键:
{
"body": {
"errors": {
+ "root": { "serverError": "Some of the provided values are not valid. Please fix them and retry." },
"title": "An article with this title already exists. The title must be unique.",
"date": "The date is required",
"tags": { "message": "The tag 'agrriculture' doesn't exist" },
}
}
}
次要破坏性变更(Minor BC): 为避免 HTTP 错误通知与校验错误通知之间的竞态,当响应包含非空 errors 对象且 mutation mode 为 pessimistic 时,react-admin 不再为 HTTP 错误显示通知。如果你此前依赖该行为渲染全局服务端错误消息,应改为把消息放到 errors.root.serverError 键:
{
- "message": "Some of the provided values are not valid. Please fix them and retry.",
"body": {
"errors": {
+ "root": { "serverError": "Some of the provided values are not valid. Please fix them and retry." },
"title": "An article with this title already exists. The title must be unique.",
"date": "The date is required",
"tags": { "message": "The tag 'agrriculture' doesn't exist" },
}
}
}
输入组件变更
<FileInput> 与 <ImageInput> 的 accept prop 发生变化
由于 react-dropzone 从 v12 升级到 v14,<FileInput> 与 <ImageInput> 的 accept prop 语法改变——从 MIME 字符串变为「MIME 类型 → 扩展名数组」的对象:
-<FileInput source="attachments" accept="application/pdf">
+<FileInput source="attachments" accept={{ 'application/pdf': ['.pdf'] }}>
输入校验错误不再要求「已触碰」才显示
此前校验错误只会在输入被触碰(touched)或表单提交后才显示。v5 将校验错误的显示时机完全交给表单库 react-hook-form 决定。
提示: 可以通过 mode prop 配置校验策略(onSubmit、onBlur、onChange 或 onTouched)。
对大多数场景没有影响——react-hook-form 默认行为与之前类似(输入触碰后才触发校验)。但这有助于一些高级场景,例如在未触碰的字段上显示校验错误。同时表单的 isValid 状态将与输入上显示的错误消息保持一致(无论字段是否被触碰),改善用户体验。
<InputHelperText touched> prop 被移除
<InputHelperText> 不再接受 touched prop(此前用于只在输入被触碰后显示校验错误)。该行为现已由 react-hook-form 接管,直接移除该 prop 即可:
-<InputHelperText touched={touched} />
+<InputHelperText />
TypeScript 变更
react-admin v5 启用了 strictNullChecks 编译。这意味着基于 v4 的应用在 v5 下很可能无法直接编译通过——这是故意的:强迫你更新代码,换来更健壮、更不易出错的类型安全。
字段组件现在要求 source prop
FieldProps 接口现在要求 source prop 必须定义,因此所有默认字段组件也要求 source。这会影响用 FieldProps 标注 props 的自定义字段。如果你的自定义字段不打算用在 <Datagrid> 中,可以把 source 声明为可选:
import { FieldProps, useRecordContext } from 'react-admin';
-const AvatarField = (props: FieldProps) => {
+const AvatarField = (props: Omit<FieldProps, 'source'>) => {
const record = useRecordContext();
if (!record) return null;
return (
<Avatar
src={record.avatar}
alt={`${record.first_name} ${record.last_name}`}
{...props}
/>
);
}
useRecordContext 在无记录时返回 undefined
useRecordContext 从 RecordContext 读取当前记录。该 context 可能为空(例如记录仍在加载中),因此返回类型从 Record 改为 Record | undefined。如果你的代码未先判空就读取 record,TypeScript 编译会报错:
const MyComponent = () => {
const record = useRecordContext();
+ if (!record) return null;
return (
<div>
<h1>{record.title}</h1>
<p>{record.body}</p>
</div>
);
};
useAuthProvider 在无 authProvider 时返回 undefined
useAuthProvider 返回当前 authProvider。由于 authProvider 是可选的,该 context 可能为空,返回类型从 AuthProvider 改为 AuthProvider | undefined。需要先判空:
const useGetPermissions = (): GetPermissions => {
const authProvider = useAuthProvider();
const getPermissions = useCallback(
(params: any = {}) =>
+ authProvider ?
authProvider
.getPermissions(params)
.then(result => result ?? null)
+ : Promise.resolve([]),
[authProvider]
);
return getPermissions;
};
页面 Context 返回值由 interface 改为 type
页面控制器(controller)的返回类型现在是 type。如果你用 interface 继承过以下类型之一:
ListControllerResultInfiniteListControllerResultEditControllerResultShowControllerResultCreateControllerResult
需要改为 type 扩展:
import { ListControllerResult } from 'react-admin';
-interface MyListControllerResult extends ListControllerResult {
+type MyListControllerResult = ListControllerResult & {
customProp: string;
};
页面 Context 类型更严格
以下 hooks 的返回类型更加智能:
useListContextuseEditContextuseShowContextuseCreateContext
根据数据获取状态,data、error、isPending 的类型会更精确:
- 加载中:
{ data: undefined, error: undefined, isPending: true } - 成功:
{ data: <Data>, error: undefined, isPending: false } - 错误:
{ data: undefined, error: <Error>, isPending: false } - 刷新后出错:
{ data: <Data>, error: <Error>, isPending: false }
因此,未先判空就使用 data 会触发 TypeScript 报错,需要分别处理各状态:
const MyCustomList = () => {
const { data, error, isPending } = useListContext();
if (isPending) return <Loading />;
+ if (error) return <Error />;
return (
<ul>
{data.map(record => (
<li key={record.id}>{record.name}</li>
))}
</ul>
);
};
此外,这些 hooks 在页面 context 之外调用时会直接抛错。也就是说,不能在不是 <List>、<ListBase>、<Edit>、<EditBase>、<Show>、<ShowBase>、<Create>、<CreateBase> 子组件的自定义组件中调用它们。
EditProps 与 CreateProps 现在要求 children prop
EditProps 与 CreateProps 现在与 ListProps、ShowProps 一样要求 children。如果在自定义组件中使用这些类型,需要相应调整:
-const ReviewEdit = ({ id }: EditProps) => (
+const ReviewEdit = ({ id }: Omit<EditProps, 'children'>) => (
<Edit id={id}>
<SimpleForm>
...
BulkActionProps 类型被移除
BulkActionProps 因不含任何 prop 而被移除,可以直接从自定义 bulk actions 中删掉该类型标注。
ra-core 的 onError 类型被移除
ra-core 导出的 onError 类型被移除,改用 OnError。从源码看,OnError 类型定义在 packages/ra-core/src/types.ts(约第 283 行),并被 mutation 相关配置引用。
-import { onError } from 'ra-core';
+import { OnError } from 'ra-core';
PublicFieldProps 接口被移除
PublicFieldProps 接口被移除,改用 FieldProps。
InjectedFieldProps 接口被移除
InjectedFieldProps 接口被移除,改用 FieldProps。
FieldProps 的 formClassName prop 被移除
FieldProps 中已废弃的 formClassName prop 因不再使用而被移除。
CommonInputProps 的 formClassName prop 被移除
CommonInputProps 中已废弃的 formClassName prop 同样被移除。
认证(Authentication)变更
useCheckAuth 不再接受 disableNotification 参数
useCheckAuth 不再接受已废弃的 disableNotification 参数。要在 checkAuth 失败时禁用「Authentication required」通知,让 authProvider.checkAuth() 返回一个以 { message: false } 为值的 rejected promise:
const authProvider: AuthProvider = {
//...
checkAuth: () => Promise.reject({ message: false }),
}
useLogoutIfAccessDenied 不再接受 disableNotification 参数
useLogoutIfAccessDenied 不再接受已废弃的 disableNotification 参数。要在 checkError 触发时禁用「Authentication required」通知,让 authProvider.checkError() 返回以 { message: false } 为值的 rejected promise:
const authProvider: AuthProvider = {
//...
checkError: () => Promise.reject({ message: false }),
}
或者给 useLogoutIfAccessDenied 调用传入 error 参数:
const logoutIfAccessDenied = useLogoutIfAccessDenied();
logoutIfAccessDenied(new Error('Denied'));
usePermissionsOptimized hook 被移除
已废弃的 usePermissionsOptimized hook 被移除。在 packages/ra-core/src/auth 目录中已检索不到该 hook 的实现或导出。请改用 usePermissions(其实现位于 packages/ra-core/src/auth/usePermissions.ts)。
路由(Routing)变更
linkToRecord 辅助函数被移除
linkToRecord 辅助函数被移除,改用 useCreatePath:
-import { linkToRecord } from 'react-admin';
-const path = linkToRecord('posts', 123);
+import { useCreatePath } from 'react-admin';
+const createPath = useCreatePath();
+const path = createPath({ resource: 'posts', id: 123, type: 'edit' });
resolveRedirectTo 辅助函数被移除
resolveRedirectTo 辅助函数被移除,同样改用 useCreatePath。
主题(Theming)变更
useTheme 不再接受主题对象作为可选参数
useTheme 不再接受 RaTheme 对象参数来返回 RaTheme 对象;它现在只接受一个可选的主题偏好默认值(ThemeType,如 "light" / "dark"),并返回当前主题偏好及其 setter。
如果此前传入主题对象让 useTheme 推断默认值,请改传偏好值:
const myThemeObject = {
...
palette: {
type: "light",
...
}
...
};
- const [themeObject, setTheme] = useTheme(myThemeObject)
+ const [themePreference, setTheme] = useTheme(myThemeObject.palette.type)
// 或者
+ const [themePreference, setTheme] = useTheme("light")
// 或者(通常不需要为偏好提供默认值)
+ const [themePreference, setTheme] = useTheme();
<ToggleThemeButton> 不再接受 themes 作为 props
此前 <ToggleThemeButton> 接受 lightTheme 与 darkTheme props,v5 不再支持。主题应在 <Admin> 组件上设置。另外,只要在 <Admin> 中设置了主题,react-admin 会自动把 ToggleThemeButton 放进应用栏,通常无需再手动添加该按钮:
-import { Admin, Layout, AppBar, ToggleThemeButton } from 'react-admin';
+import { Admin } from 'react-admin';
import { dataProvider } from './dataProvider';
import { lightTheme, darkTheme } from './themes';
-const MyAppBar = () => <AppBar toolbar={<ToggleThemeButton lightTheme={lightTheme} darkTheme={darkTheme} />} />
-const MyLayout = (props) => <Layout {...props} appBar={<MyAppBar />} />;
const App = () => (
- <Admin dataProvider={dataProvider} layout={MyLayout}>
+ <Admin dataProvider={dataProvider} lightTheme={lightTheme} darkTheme={darkTheme}>
...
</Admin>
);
<ThemeProvider theme> 不再受支持
已废弃的 <ThemeProvider theme> prop 被移除,改用 ThemesContext.Provider:
-import { ThemeProvider } from 'react-admin';
+import { ThemeProvider, ThemesContext } from 'react-admin';
export const ThemeWrapper = ({ children }) => {
return (
- <ThemeProvider
- theme={{
- palette: { mode: 'dark' },
+ <ThemesContext.Provider
+ value={{
+ darkTheme: { palette: { mode: 'dark' } },
+ lightTheme: { palette: { mode: 'light' } },
}}
>
- {children}
- </ThemeProvider>
+ <ThemeProvider>{children}</ThemeProvider>
+ </ThemesContext.Provider>
);
};
其他变更
data-generator-retail 的 commands 更名为 orders
data-generator-retail 包现已为所有记录提供类型。为此,commands 资源更名为 orders;相应地,customers 资源的 nb_commands 属性更名为 nb_orders,invoices 与 reviews 资源的 command_id 属性更名为 order_id。若你在示例数据或业务代码中引用了这些字段名,需要同步更新。
移除对 PropTypes 的支持
react-admin 不再支持 React PropTypes(React 官方早已废弃 PropTypes)。官方建议切换到 TypeScript 来标注组件 props 类型——这也与 v5 全面启用 strictNullChecks 的方向一致。
升级路径小结
从 v3 升级的用户需要先完成 Upgrading to v4 指南中描述的步骤,再按本文升级到 v5。建议按以下顺序执行升级:
- 升级依赖:React 18(修改入口文件用
createRoot)、@tanstack/react-queryv5(配合官方 codemod)、date-fns / inflection / react-dropzone / react-error-boundary / react-i18next 等次要依赖。 - 处理编译错误:安装 v5 后先跑一遍 TypeScript 编译,依据
strictNullChecks提示修复useRecordContext、useAuthProvider、页面 context 相关的判空问题,并按需调整FieldProps/EditProps等类型标注。 - 改造布局与应用根:移除
<Admin menu>、<Admin history>,用自定义 Layout +useHasDashboard/useDefaultTitle/useSidebarState等 hooks 替代注入式 props;测试中改用TestMemoryRouter(可配合replace-Admin-historycodemod)。 - 检查列表与表单组件:迁移
bulkActionButtons到<Datagrid>、独立使用列表组件时加ListContextProvider、处理setFilters防抖参数、SimpleFormIterator/FormDataConsumer的新写法。 - 验证 UI 与主题:确认输入全宽、链接下划线、深色主题默认启用是否符合预期,必要时通过主题或
sx回退旧样式。 - 回归测试:重点覆盖表单校验显示时机、
warnWhenUnsavedChanges(确保使用 data router)、服务端校验错误消息(root.serverError)、GraphQL data provider 初始化等行为变化。
以上所有变更点都可在当前仓库中通过阅读 packages/react-admin/package.json(依赖版本)、packages/ra-core/src/routing/TestMemoryRouter.tsx(测试路由封装)、packages/ra-core/src/core/HasDashboardContext.ts 与 packages/ra-core/src/core/DefaultTitleContext.ts(context hooks)、packages/ra-core/src/controller/list/useRecordSelection.ts(选择状态 hook 新签名)、packages/ra-data-graphql-simple/src/index.ts(非 Promise 构建器)以及 packages/ra-core/codemods(官方迁移脚本)进一步印证。