react-admin v5 升级完全指南:从 v4 到 v5 的破坏性变更、依赖迁移与代码改造手册

原创2026-09-20 18:52:261,685 阅读
文章标签:前端Web框架UI组件低代码企业应用认证鉴权国际化

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 —— 转换查询 key
  • v5/remove-overloads/remove-overloads.cjs —— 移除旧的重载签名
  • v5/is-loading/is-loading.cjs —— 迁移 isLoading 语义(v5 中 isLoading 表示「无数据 + 加载中」,原 isFetching 的语义由 isPending 承担)
  • v5/keep-previous-data/keep-previous-data.cjs
  • v5/rename-properties/rename-properties.cjs
  • v5/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 继承过以下类型之一:

  • ListControllerResult
  • InfiniteListControllerResult
  • EditControllerResult
  • ShowControllerResult
  • CreateControllerResult

需要改为 type 扩展:

import { ListControllerResult } from 'react-admin';

-interface MyListControllerResult extends ListControllerResult {
+type MyListControllerResult = ListControllerResult & {
    customProp: string;
};

页面 Context 类型更严格

以下 hooks 的返回类型更加智能:

  • useListContext
  • useEditContext
  • useShowContext
  • useCreateContext

根据数据获取状态,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。建议按以下顺序执行升级:

  1. 升级依赖:React 18(修改入口文件用 createRoot)、@tanstack/react-query v5(配合官方 codemod)、date-fns / inflection / react-dropzone / react-error-boundary / react-i18next 等次要依赖。
  2. 处理编译错误:安装 v5 后先跑一遍 TypeScript 编译,依据 strictNullChecks 提示修复 useRecordContext、useAuthProvider、页面 context 相关的判空问题,并按需调整 FieldProps/EditProps 等类型标注。
  3. 改造布局与应用根:移除 <Admin menu>、<Admin history>,用自定义 Layout + useHasDashboard/useDefaultTitle/useSidebarState 等 hooks 替代注入式 props;测试中改用 TestMemoryRouter(可配合 replace-Admin-history codemod)。
  4. 检查列表与表单组件:迁移 bulkActionButtons 到 <Datagrid>、独立使用列表组件时加 ListContextProvider、处理 setFilters 防抖参数、SimpleFormIterator/FormDataConsumer 的新写法。
  5. 验证 UI 与主题:确认输入全宽、链接下划线、深色主题默认启用是否符合预期,必要时通过主题或 sx 回退旧样式。
  6. 回归测试:重点覆盖表单校验显示时机、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(官方迁移脚本)进一步印证。

登录后查看全文
react-admin