react-admin 从零入门教程:基于现有 REST API 构建完整的 CRUD 管理后台

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

react-admin 从零入门教程:基于现有 REST API 构建完整的 CRUD 管理后台

本教程面向想用 react-admin 在 45 分钟内从一个真实 REST API(JSONPlaceholder)起步、构建出具备增删改查、筛选、详情、编辑、创建、乐观更新与认证能力的管理后台的开发者。读完本文,你将掌握 create-react-admin 脚手架、Data Provider 适配原理、<Resource> 路由映射、列表/详情/编辑/创建四大视图组件、自定义 Field、sx 样式定制、关系字段、筛选器以及手写自定义 Data Provider 对接任意 API 的完整实战方案。全文代码均可在仓库的 examples/tutorial 中找到完整可运行实现,文档原文位于 docs/Tutorial.md。

react-admin 教程最终应用的运行效果预览

教程目标与前置准备

本教程基于 docs/Tutorial.md,全程约 45 分钟。我们将从一个空白项目开始,逐步构建一个可以对 users(用户) 和 posts(文章) 两个资源进行“列表、创建、编辑、删除”的管理应用,最终理解 react-admin 的核心特性与开发者体验。如果你更习惯看视频,可参考 Traversy Media 制作的同内容视频;以下我们走完整文字路线,从绝对基础一直做到一个功能完整的后台。

最终得到的应用具有如下能力:

  • 基于已有 REST API 展示数据列表(支持排序、分页、搜索筛选);
  • 查看单条记录的详情页;
  • 编辑与新建记录(含关系字段下拉选择);
  • 保存时的乐观渲染(Optimistic Rendering)与撤销(Undo)能力;
  • 带登录表单的认证流程;
  • 自定义首页(Dashboard)与菜单图标。

仓库中与本教程配套的完整示例代码位于 examples/tutorial,其运行说明见 examples/tutorial/README.md(在克隆仓库后依次执行 make install、make build、make run-tutorial,登录时可使用任意用户名/密码组合)。

环境搭建:用 create-react-admin 引导项目

react-admin 构建在 React 之上。教程推荐使用 create-react-admin 脚手架引导一个新应用:

npm create react-admin@latest test-admin -- --interactive
# 或
yarn create react-admin test-admin --interactive

交互式提示时请按以下方式选择:

  1. Data provider 选择 JSON Server;
  2. Auth provider 选择 None(本教程稍后手动实现认证);
  3. 暂时不要添加任何资源,直接回车;
  4. 选择包管理器 npm 或 yarn,回车。

安装完成后启动开发服务器:

cd test-admin
npm run dev
# 或
yarn dev

此时浏览器打开 5173 端口,会看到一个空白的 react-admin 应用:

初始化后的空 react-admin 应用界面

Tip:create-react-admin 生成的是由 Vite 与 TypeScript 驱动的单页应用(也可以选择 JavaScript)。react-admin 是框架无关的,同样可以运行在 Next.js、Remix 或其他任何 React 框架中。

解析生成的项目结构

create-react-admin 脚本使用 Vite 与 TypeScript 创建了一个单页应用。项目的主入口是 index.tsx,它将 App 组件渲染进 DOM:

// in src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { App } from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
        <App />
    </React.StrictMode>
);

<App> 组件渲染了 <Admin> 组件,它是整个 react-admin 应用的根组件:

// in src/App.tsx
import { Admin, Resource, ListGuesser, EditGuesser, ShowGuesser } from 'react-admin';
import { dataProvider } from './dataProvider';

export const App = () => (
    <Admin dataProvider={dataProvider}>

    </Admin>
);

目前这个组件只定义了一个 dataProvider prop。那么,到底什么是 data provider?

数据源抽象:什么是 Data Provider

react-admin 应用是运行在浏览器中的单页应用(SPA),它从一个 API 拉取数据。由于系统之间没有统一的数据交换标准,react-admin 通过一个名为 Data Provider 的适配器与你的 API 通信。

本教程使用 JSONPlaceholder——一个专门用于原型与测试的假 REST API。例如查询用户 2:

curl https://jsonplaceholder.typicode.com/users/2

返回:

{
  "id": 2,
  "name": "Ervin Howell",
  "username": "Antonette",
  "email": "Shanna@melissa.tv",
  "address": {
    "street": "Victor Plains",
    "suite": "Suite 879",
    "city": "Wisokyburgh",
    "zipcode": "90566-7771",
    "geo": {
      "lat": "-43.9509",
      "lng": "-34.4618"
    }
  },
  "phone": "010-692-6593 x09125",
  "website": "anastasia.net",
  "company": {
    "name": "Deckow-Crist",
    "catchPhrase": "Proactive didactic contingency",
    "bs": "synergize scalable supply-chains"
  }
}

JSONPlaceholder 提供了 users、posts、comments 三类端点。我们将要构建的管理后台会对这些资源执行 CRUD(Create、Retrieve、Update、Delete)操作。

test-admin 项目已经预置了一个面向 JSONPlaceholder 的 data provider:

// in src/dataProvider.ts
import jsonServerProvider from 'ra-data-json-server';

export const dataProvider = jsonServerProvider(
    import.meta.env.VITE_JSON_SERVER_URL
);

这里使用的是第三方包 ra-data-json-server,它把 JSONPlaceholder 风格的 REST API 映射到 react-admin 的 CRUD API。在 DataProviderList 中可以找到适配各种 API 和数据库的几十种 data provider 包,必要时你也可以编写自己的实现(下文会专门讲解)。

Tip:import.meta.env.VITE_JSON_SERVER_URL 是 Vite 环境变量,项目根目录的 .env 文件将其设为 https://jsonplaceholder.typicode.com。

从源码看 jsonServerProvider 的映射规则

ra-data-json-server 的实现位于 packages/ra-data-json-server/src/index.ts。从源码注释可以看到它把每个 react-admin 查询动作映射为具体的 HTTP 请求:

  • getList → GET http://my.api.url/posts?_sort=title&_order=ASC&_start=0&_end=24
  • getOne → GET http://my.api.url/posts/123
  • getMany → GET http://my.api.url/posts?id=123&id=456&id=789
  • getManyReference → GET http://my.api.url/posts?author_id=345
  • create → POST http://my.api.url/posts
  • update → PUT http://my.api.url/posts/123
  • updateMany → 对每个 id 依次执行 PUT
  • delete → DELETE http://my.api.url/posts/123
  • deleteMany → 对每个 id 依次执行 DELETE

注意其中的实现细节:getList 依赖响应头 X-Total-Count 来构建分页(源码中在缺少该响应头时会抛出明确错误提示,提醒你在使用 CORS 时于 Access-Control-Expose-Headers 中声明 X-Total-Count);updateMany 与 deleteMany 由于 json-server 不支持带 filter 的批量路由,退化为逐条多次请求(见 packages/ra-data-json-server/src/index.ts)。

用 Resource 映射 API 端点

接下来给应用添加一个用户列表。<Admin> 组件期望一个或多个 <Resource> 子组件,每个 Resource 把「资源名」映射到一个 API 端点。要添加名为 users 的资源,编辑 App.tsx:

// in src/App.tsx
import { Admin, Resource, ListGuesser, EditGuesser, ShowGuesser } from 'react-admin';
import { dataProvider } from './dataProvider';

export const App = () => (
  <Admin dataProvider={dataProvider}>
+   <Resource name="users" list={ListGuesser} />
  </Admin>
);

<Resource name="users" /> 这行指示 react-admin 从 https://jsonplaceholder.typicode.com/users 抓取数据。<Resource> 组件同时定义了每个 CRUD 操作(list、create、edit、show)分别使用哪个 React 组件。

list={ListGuesser} 告诉 react-admin 用 <ListGuesser> 显示用户列表。该组件会根据 API 抓取到的数据猜测列表的配置——包括列名与列类型。

现在应用已经可以显示用户列表了:

react-admin 用户列表页

这个列表已经是可用的:点击列头可以排序,通过分页控件可以翻页。打开浏览器开发者工具的 Network 面板,你会看到列表上的每个用户操作都会触发一次带更新参数的 https://jsonplaceholder.typicode.com/users 请求——data provider 负责把这些用户操作翻译成后端能理解的 API 调用。

编写页面组件:从 ListGuesser 到自定义 List

<ListGuesser> 并不适合生产环境,它只是用来帮你快速搭建管理界面。最终你需要用一个自定义 React 组件替换 users 资源上的 ListGuesser。好在 ListGuesser 会把猜测出的列表代码直接打印到浏览器控制台:

ListGuesser 在控制台输出的猜测代码

复制这段代码,新建一个 users.tsx 文件并创建 UserList 组件:

// in src/users.tsx
import { List, DataTable, EmailField } from "react-admin";

export const UserList = () => (
    <List>
        <DataTable>
            <DataTable.Col source="id" />
            <DataTable.Col source="name" />
            <DataTable.Col source="username" />
            <DataTable.Col source="email">
                <EmailField source="email" />
            </DataTable.Col>
            <DataTable.Col source="address.street" />
            <DataTable.Col source="phone" />
            <DataTable.Col source="website" />
            <DataTable.Col source="company.name" />
        </DataTable>
    </List>
);

然后更新 App.tsx,用新组件替换 ListGuesser:

// in src/App.tsx
-import { Admin, Resource, ListGuesser, EditGuesser, ShowGuesser } from 'react-admin';
+import { Admin, Resource } from "react-admin";
import { dataProvider } from './dataProvider';
+import { UserList } from "./users";

export const App = () => (
  <Admin dataProvider={dataProvider}>
-   <Resource name="users" list={ListGuesser} />
+   <Resource name="users" list={UserList} />
  </Admin>
);

用户列表

浏览器里视觉上没有任何变化,但现在应用使用的组件已经完全由你掌控了。

关于 DataTable 与 Datagrid:教程文档中使用的列表表格组件是较新的 <DataTable>(以 DataTable.Col 子组件声明列)。仓库配套示例 examples/tutorial/src/users.tsx 使用的是经典写法 <Datagrid> + <TextField source="..."/>,二者表达的是同一套「<List> 负责取数、子组件负责渲染」的组合模式。

组件组合:React-admin 的核心设计

我们来仔细看一下 <UserList> 组件:

export const UserList = () => (
    <List>
        <DataTable>
            <DataTable.Col source="id" />
            <DataTable.Col source="name" />
            <DataTable.Col source="username" />
            <DataTable.Col source="email">
                <EmailField source="email" />
            </DataTable.Col>
            <DataTable.Col source="address.street" />
            <DataTable.Col source="phone" />
            <DataTable.Col source="website" />
            <DataTable.Col source="company.name" />
        </DataTable>
    </List>
);

根组件 <List> 负责读取查询参数、从 API 抓取数据,并把数据放进 React Context。它还提供过滤、分页、排序的回调,子组件可以读取并修改这些列表参数。<List> 做了很多事,但它的语法依然直白:

<List>
   {/* children */}
</List>

这体现了 react-admin 的目标:用简单的语法帮助开发者构建复杂的应用。

在多数框架里,"simple" 往往意味着能力有限,难以扩展。react-admin 用 组合(composition) 来解决这个问题:<List> 负责数据抓取,渲染工作则委托给它的子组件——这里是 <DataTable>。本质上,这段代码组合了 <List> 与 <DataTable> 两个组件的功能。

这意味着我们可以把 <List> 与另一个组件组合——比如 <SimpleList>:

// in src/users.tsx
import { List, SimpleList } from "react-admin";

export const UserList = () => (
    <List>
        <SimpleList
          primaryText={(record) => record.name}
          secondaryText={(record) => record.username}
          tertiaryText={(record) => record.email}
        />
    </List>
);

<SimpleList> 基于 Material UI 的 <List> 与 <ListItem> 组件,通过 primaryText、secondaryText、tertiaryText 三个函数 prop 决定每一行如何渲染。

刷新页面,你会看到列表以另一种形式呈现:

使用 SimpleList 渲染的用户列表(移动端友好)

react-admin 提供了大量组件帮助你搭建 UI,你也可以在需要时创建自己的组件。

编写响应式自定义列表

react-admin 的布局默认就是响应式的:试着缩放浏览器窗口,侧边栏在小屏幕上会变成抽屉。<SimpleList> 组件非常适合移动设备,但它在桌面端的信息密度很低。

让我们把 <UserList> 改成大屏用 <DataTable>、小屏用 <SimpleList>,借助 Material UI 的 useMediaQuery hook 实现:

// in src/users.tsx
import { useMediaQuery, Theme } from "@mui/material";
import { List, SimpleList, DataTable, EmailField } from "react-admin";

export const UserList = () => {
    const isSmall = useMediaQuery<Theme>((theme) => theme.breakpoints.down("sm"));
    return (
        <List>
            {isSmall ? (
                <SimpleList
                    primaryText={(record) => record.name}
                    secondaryText={(record) => record.username}
                    tertiaryText={(record) => record.email}
                />
            ) : (
                <DataTable>
                    <DataTable.Col source="id" />
                    <DataTable.Col source="name" />
                    <DataTable.Col source="username" />
                    <DataTable.Col source="email">
                        <EmailField source="email" />
                    </DataTable.Col>
                    <DataTable.Col source="address.street" />
                    <DataTable.Col source="phone" />
                    <DataTable.Col source="website" />
                    <DataTable.Col source="company.name" />
                </DataTable>
            )}
        </List>
    );
};

运行效果正如你预期的那样(见示例视频 docs/img/tutorial_user_list_responsive.mp4)。<List> 的子组件可以是任何东西——甚至是一个带有自己业务逻辑的自定义组件。这种灵活性使 react-admin 非常适合构建响应式应用。

仓库中配套的完整实现见 examples/tutorial/src/users.tsx,其写法与上述一致(小屏 SimpleList、大屏 Datagrid rowClick="show",并将 MyUrlField 用于 website 列)。

选择要展示的列

回到 <DataTable>。它读取 <List> 抓取的数据,为每条记录渲染一行,并利用其子组件(一组 <DataTable.Col>)渲染各列。每个 <DataTable.Col> 通过 source prop 渲染当前记录的一个字段。

<ListGuesser> 曾为 API 响应中的每个字段都创建了一列——对于一个可用的表格来说太多了。让我们删掉几个 <DataTable.Col> 看看效果:

// in src/users.tsx
  <DataTable>
    <DataTable.Col source="id" />
    <DataTable.Col source="name" />
-   <DataTable.Col source="username" />
    <DataTable.Col source="email">
      <EmailField source="email" />
    </DataTable.Col>
-   <DataTable.Col source="address.street" />
    <DataTable.Col source="phone" />
    <DataTable.Col source="website" />
    <DataTable.Col source="company.name" />
  </DataTable>

精简列之后的用户列表

在 react-admin 中,大部分配置都通过组件完成。<DataTable> 不使用 columns prop,而是利用 children prop 提供灵活性,让你可以随时加入自定义逻辑或更换列类型。

使用字段类型(Field Components)

到目前为止,你直接使用了 <DataTable.Col> 并把 EmailField 作为 <DataTable.Col> 的子组件。react-admin 还提供了大量 Field 组件 来处理不同类型的数据——数字、日期、图片、数组等等。你还可以用 field prop 直接在 DataTable.Col 上指定字段组件,当该字段无需自定义 prop 时非常有用。

例如,与其把 website 字段显示为纯文本,不如用 <UrlField> 把它变成可点击的链接:

// in src/users.tsx
-import { List, SimpleList, DataTable, EmailField } from "react-admin";
+import { List, SimpleList, DataTable, EmailField, UrlField } from "react-admin";
// ...
  <DataTable>
    <DataTable.Col source="id" />
    <DataTable.Col source="name" />
    <DataTable.Col source="email">
      <EmailField source="email" />
    </DataTable.Col>
    <DataTable.Col source="phone" />
-   <DataTable.Col source="website" />
+   <DataTable.Col source="website" field={UrlField} />
    <DataTable.Col source="company.name" />
  </DataTable>

使用 UrlField 后的用户列表

这就是 react-admin 开发初期的典型节奏:先用 guesser 组件搭建基础页面,再逐步调整代码以贴合业务需求。

编写自定义 Field

在 react-admin 中,Field 本质就是 React 组件。渲染时,它们通过自定义 hook 拿到从 API 抓取的 record(例如 { "id": 2, "name": "Ervin Howell", "website": "anastasia.net", ... }),再通过 source prop(例如 website)取得要显示的值(例如 "anastasia.net")。

因此你也可以用同样的方式编写自定义字段。比如,下面是一个简化版的 <UrlField>:

// in src/MyUrlField.tsx
import { useRecordContext } from "react-admin";

const MyUrlField = ({ source }: { source: string }) => {
    const record = useRecordContext();
    if (!record) return null;
    return <a href={`https://${record[source]}`}>{record[source]}</a>;
};

export default MyUrlField;

<DataTable> 在渲染每一行时都会创建一个 RecordContext 并把当前记录放进去,useRecordContext 让你能够读取这条记录。它是 react-admin 暴露的 50 多个 headless hooks 之一,用于在不绑定特定 UI 的前提下构建自己的组件。

接下来在 <UserList> 中用 <MyUrlField> 替换 react-admin 的 <UrlField>,效果完全一样:

// in src/users.tsx
-import { List, SimpleList, DataTable, EmailField, UrlField } from "react-admin";
+import { List, SimpleList, DataTable, EmailField } from "react-admin";
+import MyUrlField from './MyUrlField';
// ...
  <DataTable>
    <DataTable.Col source="id" />
    <DataTable.Col source="name" />
    <DataTable.Col source="email">
      <EmailField source="email" />
    </DataTable.Col>
    <DataTable.Col source="phone" />
-   <DataTable.Col source="website" field={UrlField} />
+   <DataTable.Col source="website" field={MyUrlField} />
    <DataTable.Col source="company.name" />
  </DataTable>

这意味着 react-admin 永远不会阻碍你:如果某个 react-admin 组件不完全适合你的需求,直接换成你自己的实现即可。仓库示例 examples/tutorial/src/MyUrlField.tsx 给出了一个更完整的版本(额外使用了 onClick={e => e.stopPropagation()} 避免点击链接时触发行选中)。

用 sx prop 定制样式

<MyUrlField> 是演示样式定制的好例子。react-admin 依赖 Material UI 的 prop,用于内联样式定制。我们利用 sx 去掉链接的下划线并加上一个图标:

// in src/MyUrlField.tsx
import { useRecordContext } from "react-admin";
import { Link } from "@mui/material";
import LaunchIcon from "@mui/icons-material/Launch";

const MyUrlField = ({ source }: { source: string }) => {
    const record = useRecordContext();
    return record ? (
        <Link href={record[source]} sx={{ textDecoration: "none" }}>
            {record[source]}
            <LaunchIcon sx={{ fontSize: 15, ml: 1 }} />
        </Link>
    ) : null;
};

export default MyUrlField;

自定义样式后的 UrlField

<sx> prop 类似于 React 的 style prop,但它还支持主题(theming)、媒体查询(media queries)、简写属性等等。它是一套 CSS-in-JS 方案,因此需要使用 CSS 属性的 JS 变体(例如 textDecoration 而不是 text-decoration)。

Tip:Material UI 的样式体系远不止本教程覆盖的内容,可阅读 Theming 文档 了解更多关于主题、厂商前缀、响应式工具等知识;Material UI 也支持其他 CSS-in-JS 方案(如 Styled components)。

处理关系:ReferenceField 与引用字段

在 JSONPlaceholder 中,每条 post 记录都包含一个指向 user 的 userId 字段:

{
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto",
    "userId": 1
}

react-admin 很擅长利用这些外键抓取关联数据。让我们为 /posts 端点新建一个 <Resource>,看看 ListGuesser 如何处理它们:

// in src/App.tsx
-import { Admin, Resource } from "react-admin";
+import { Admin, Resource, ListGuesser } from "react-admin";
import { dataProvider } from './dataProvider';
import { UserList } from "./users";

export const App = () => (
  <Admin dataProvider={dataProvider}>
+   <Resource name="posts" list={ListGuesser} />
    <Resource name="users" list={UserList} />
  </Admin>
);

ListGuesser 猜测的文章列表

ListGuesser 会建议在 userId 字段上使用 <ReferenceField>。我们基于 guesser 输出的代码创建 PostList 组件:

// in src/posts.tsx
import { List, DataTable, ReferenceField } from "react-admin";

export const PostList = () => (
    <List>
        <DataTable>
            <DataTable.Col source="userId">
                <ReferenceField source="userId" reference="users" />
            </DataTable.Col>
            <DataTable.Col source="id" />
            <DataTable.Col source="title" />
            <DataTable.Col source="body" />
        </DataTable>
    </List>
);
// in src/App.tsx
-import { Admin, Resource, ListGuesser } from "react-admin";
+import { Admin, Resource } from "react-admin";
import { dataProvider } from './dataProvider';
+import { PostList } from "./posts";
import { UserList } from "./users";

export const App = () => (
    <Admin dataProvider={dataProvider}>
-       <Resource name="posts" list={ListGuesser} />
+       <Resource name="posts" list={PostList} />
        <Resource name="users" list={UserList} />
    </Admin>
);

显示文章列表时,react-admin 会智能地展示文章作者的名字:

文章列表显示作者姓名

Tip:要自定义一条记录的展示方式,可以在 <Resource> 上设置 recordRepresentation prop。仓库示例 examples/tutorial/src/App.tsx 中为 users 资源设置了 recordRepresentation="name",这就是编辑文章时能显示作者姓名的原因。

<ReferenceField> 组件会抓取引用数据,用结果创建 RecordContext,然后渲染记录的展示形式(或其子组件)。

Tip:再次打开浏览器 Network 面板观察:react-admin 会对 users 的请求做去重与聚合,整个 DataTable 只向 /users 端点发出一次 HTTP 请求。这是众多让 UI 保持快速响应的优化之一。

最后完善文章列表:把 id 放到第一列,移除 body 字段(从 UX 角度看,大段文本字段不应出现在表格中,只应出现在详情视图)。同时为了突出编辑操作,把默认的 rowClick 行为替换为显式的操作按钮:

// in src/posts.tsx
-import { List, DataTable, ReferenceField } from "react-admin";
+import { List, DataTable, ReferenceField, EditButton } from "react-admin";

export const PostList = () => (
  <List>
-   <DataTable>
+   <DataTable rowClick={false}>
+     <DataTable.Col source="id" />
      <DataTable.Col source="userId">
        <ReferenceField source="userId" reference="users" />
      </DataTable.Col>
-     <DataTable.Col source="id" />
      <DataTable.Col source="title" />
-     <DataTable.Col source="body" />
+     <DataTable.Col>
+       <EditButton />
+     </DataTable.Col>
    </DataTable>
  </List>
);

精简列并加入编辑按钮后的文章列表

添加详情视图(Show)

到目前为止,后台只有列表页;而且用户列表并未渲染全部列,因此需要详情视图来查看所有用户字段。<Resource> 组件接受 show prop 定义详情视图,我们用 <ShowGuesser> 帮助引导它:

// in src/App.tsx
-import { Admin, Resource } from "react-admin";
+import { Admin, Resource, ShowGuesser } from "react-admin";
import { dataProvider } from './dataProvider';
import { PostList } from "./posts";
import { UserList } from "./users";

export const App = () => (
    <Admin dataProvider={dataProvider}>
        <Resource name="posts" list={PostList} />
-       <Resource name="users" list={UserList}  />
+       <Resource name="users" list={UserList} show={ShowGuesser}  />
    </Admin>
);

现在点击列表中的某个用户即可查看详情(演示视频见 docs/img/tutorial_show_user.mp4)。与其他 guesser 组件一样,你可以把 <ShowGuesser> 在控制台输出的代码复制下来按需修改——这超出了本教程范围,我们保持现状。

既然 users 资源有了 show 视图,就可以从文章列表链接到它。给 <ReferenceField> 加上 link="show":

// in src/posts.tsx
export const PostList = () => (
    <List>
        <DataTable>
            <DataTable.Col>
-             <ReferenceField source="userId" reference="users" />
+             <ReferenceField source="userId" reference="users" link="show" />
            </DataTable.Col>
            <DataTable.Col source="id" />
            <DataTable.Col source="title" />
            <DataTable.Col source="body" />
        </DataTable>
    </List>
);

作者姓名带 show 视图链接的文章列表

引用组件(Reference 组件)让用户能在不同资源之间自然导航,它们是 react-admin 的关键特性之一。

添加编辑能力(Edit)

管理后台不仅展示远端数据,还应允许编辑记录。react-admin 为此提供了 <Edit> 组件,先用 <EditGuesser> 引导:

// in src/App.tsx
-import { Admin, Resource, ShowGuesser } from "react-admin";
+import { Admin, Resource, ShowGuesser, EditGuesser } from "react-admin";
import { dataProvider } from './dataProvider';
import { PostList } from "./posts";
import { UserList } from "./users";

export const App = () => (
    <Admin dataProvider={dataProvider}>
-       <Resource name="posts" list={PostList} />
+       <Resource name="posts" list={PostList} edit={EditGuesser} />
        <Resource name="users" list={UserList} show={ShowGuesser}  />
    </Admin>
);

用户点击 Edit 按钮即可进入编辑页(演示视频见 docs/img/tutorial_edit_guesser.mp4)。表单开箱即用,提交时会向 REST API 发出 PUT 请求;得益于 users 资源的 recordRepresentation,文章作者显示的是用户名。

把 guesser 在控制台输出的 <PostEdit> 代码复制到 posts.tsx,以便自定义视图:

// in src/posts.tsx
import {
    List,
    DataTable,
    ReferenceField,
    EditButton,
    Edit,
    SimpleForm,
    ReferenceInput,
    TextInput,
} from "react-admin";

export const PostList = () => {
    /* ... */
};

export const PostEdit = () => (
    <Edit>
        <SimpleForm>
            <ReferenceInput source="userId" reference="users" />
            <TextInput source="id" />
            <TextInput source="title" />
            <TextInput source="body" />
        </SimpleForm>
    </Edit>
);

在 "posts" 资源的 edit prop 中使用该组件替换 guesser:

// in src/App.tsx
-import { Admin, Resource, ShowGuesser, EditGuesser } from "react-admin";
+import { Admin, Resource, ShowGuesser } from "react-admin";
import { dataProvider } from './dataProvider';
-import { PostList } from "./posts";
+import { PostList, PostEdit } from "./posts";
import { UserList } from "./users";

export const App = () => (
  <Admin dataProvider={dataProvider}>
-   <Resource name="posts" list={PostList} edit={EditGuesser} />
+   <Resource name="posts" list={PostList} edit={PostEdit} />
    <Resource name="users" list={UserList} show={ShowGuesser}  />
  </Admin>
);

接着调整 <PostEdit>:禁用主键 id 的编辑、把它放到第一位、并用 textarea 展示 body 字段:

// in src/posts.tsx
export const PostEdit = () => (
  <Edit>
    <SimpleForm>
+     <TextInput source="id" InputProps={{ disabled: true }} />
      <ReferenceInput source="userId" reference="users" link="show" />
-     <TextInput source="id" />
      <TextInput source="title" />
-     <TextInput source="body" />
+     <TextInput source="body" multiline rows={5} />
    </SimpleForm>
  </Edit>
);

如果你理解了 <List> 组件,那么 <Edit> 组件也不会让你意外:它负责抓取记录并显示页面标题,把记录传给 <SimpleForm> 组件——后者负责表单布局、默认值与校验。与 <DataTable> 一样,<SimpleForm> 通过 children 决定显示哪些输入控件,它期望的是输入组件(input components),<TextInput> 和 <ReferenceInput> 都属于这类组件。

<ReferenceInput> 接收与 <ReferenceField>(此前在 <PostList> 中用过)相同的 props。它利用这些 props 从 API 抓取与当前记录相关的候选引用(这里是为当前 post 抓取可能的 users),然后创建一个包含候选选项的 context,并渲染一个 <AutocompleteInput>——该组件负责展示候选并让用户选择其一。

仓库示例 examples/tutorial/src/posts.tsx 中还额外使用 useRecordContext 实现了一个动态的编辑页标题(PostTitle,显示 Post "xxx"),并通过 title={<PostTitle />} 传入 <Edit>,这是 guesser 之外自定义页面标题的常用手法。

添加创建能力(Create)

接下来允许用户创建文章。把 <PostEdit> 复制为 <PostCreate>,并把 <Edit> 替换为 <Create>:

// in src/posts.tsx
import {
    List,
    DataTable,
    ReferenceField,
    EditButton,
    Edit,
+   Create,
    SimpleForm,
    ReferenceInput,
    TextInput,
} from "react-admin";

export const PostList = () => (
  { /* ... */ }
);

export const PostEdit = () => (
  { /* ... */ }
);

+export const PostCreate = () => (
+  <Create>
+    <SimpleForm>
+      <ReferenceInput source="userId" reference="users" />
+      <TextInput source="title" />
+      <TextInput source="body" multiline rows={5} />
+    </SimpleForm>
+  </Create>
+);

Tip:<PostEdit> 与 <PostCreate> 几乎共用同一个表单子组件,区别只在 <PostEdit> 多了一个 id 输入。大多数情况下创建与编辑表单略有不同,因为多数 API 由服务端生成主键;但如果表单完全一致,也可以在两个组件中共享同一个表单组件。

把 <PostCreate> 作为 "posts" 资源的 create 属性:

// in src/App.tsx
import { Admin, Resource, ShowGuesser } from "react-admin";
import { dataProvider } from './dataProvider';
-import { PostList, PostEdit } from "./posts";
+import { PostList, PostEdit, PostCreate } from "./posts";
import { UserList } from "./users";

export const App = () => (
  <Admin dataProvider={dataProvider}>
-   <Resource name="posts" list={PostList} edit={PostEdit} />
+   <Resource name="posts" list={PostList} edit={PostEdit} create={PostCreate} />
    <Resource name="users" list={UserList} show={ShowGuesser}  />
  </Admin>
);

react-admin 会自动在文章列表顶部添加 "create" 按钮以进入 create 组件;创建表单同样开箱即用,提交时向 REST API 发出 POST 请求(演示视频见 docs/img/tutorial_post_create.mp4)。

乐观渲染与撤销(Optimistic Rendering and Undo)

遗憾的是 JSONPlaceholder 是一个只读 API:虽然它看起来接受了 POST 和 PUT 请求,但并不会真的保存新建与编辑的数据——所以这个特定场景下你会看到创建后报错、保存后看不到编辑结果。这只是 JSONPlaceholder 本身的限制。

那么,为什么上面录屏里新建的文章在创建后立刻出现在列表中?

因为 react-admin 使用了乐观更新(optimistic updates)。当用户编辑记录并点击 "Save" 按钮时,UI 会显示确认信息并在向服务器发送更新请求之前就展示更新后的数据。主要好处是 UI 变化即时生效,无需等待服务器响应,这对用户是极好的体验。

它还有一个额外好处:支持 "Undo"(撤销) 功能。此刻后台里的撤销已经可用:试着编辑一条记录,然后在黑色确认框滑出前点击 "Undo" 链接,你会发现应用不会向 API 发送 UPDATE 请求,并显示未修改的数据(演示视频见 docs/img/tutorial_post_edit_undo.mp4)。

尽管乐观渲染让更新看起来立即生效,react-admin 只在短暂延迟(约 5 秒)之后才真正把更新发给服务器。在这个延迟窗口内,用户随时可以撤销操作,react-admin 将完全不发送这次更新。

乐观更新与撤销不需要 API 侧的任何代码——react-admin 完全在客户端处理,意味着你自己的 API 也能免费获得这些能力!

Note:当你添加了编辑能力,也就顺带拥有了删除能力。编辑视图中的 "Delete" 按钮开箱即用,而且它同样是可撤销的(undoable)。

给列表添加搜索与筛选

回到文章列表。它已经支持排序与分页,但还缺少内容搜索能力。

react-admin 可以用输入组件在列表视图中构建多条件搜索引擎。把一组输入组件通过 filters prop 传给 <List> 即可启用过滤:

// in src/posts.tsx
const postFilters = [
    <TextInput source="q" label="Search" alwaysOn />,
    <ReferenceInput source="userId" label="User" reference="users" />,
];

export const PostList = () => (
    <List filters={postFilters}>
        // ...
    </List>
);

第一个过滤器 q 利用了 JSONPlaceholder 提供的全文搜索能力。它带有 alwaysOn,因此始终显示在屏幕上。用户可以通过列表顶部的 "add filter" 按钮添加第二个过滤器 userId。由于它是 <ReferenceInput>,已经自动填充了候选用户(演示视频见 docs/img/filters.mp4)。

过滤器是**边输入边搜索(search-as-you-type)**的:当用户在过滤表单中输入新值时,列表会立即(通过 API 请求)刷新。

Tip:label 属性可以用于任何输入组件来定制它的标签。

自定义菜单图标

侧边栏菜单里 posts 和 users 显示着同一个图标。自定义菜单图标只需给每个 <Resource> 传一个 icon 属性:

// in src/App.tsx
import PostIcon from "@mui/icons-material/Book";
import UserIcon from "@mui/icons-material/Group";

export const App = () => (
    <Admin dataProvider={dataProvider}>
        <Resource
            name="posts"
            list={PostList}
            edit={PostEdit}
            create={PostCreate}
            icon={PostIcon}
        />
        <Resource
            name="users"
            list={UserList}
            show={ShowGuesser}
            icon={UserIcon}
        />
    </Admin>
);

演示效果见 docs/img/custom-menu.mp4。仓库示例 examples/tutorial/src/App.tsx 中正是这样配置的(@mui/icons-material/Book 与 @mui/icons-material/Group)。

使用自定义首页(Dashboard)

默认情况下,react-admin 把第一个 <Resource> 的列表页作为首页。如果想显示自定义组件,把它传给 <Admin> 的 dashboard prop:

// in src/Dashboard.tsx
import { Card, CardContent, CardHeader } from "@mui/material";

export const Dashboard = () => (
    <Card>
        <CardHeader title="Welcome to the administration" />
        <CardContent>Lorem ipsum sic dolor amet...</CardContent>
    </Card>
);
// in src/App.tsx
import { Dashboard } from './Dashboard';

export const App = () => (
    <Admin dataProvider={dataProvider} dashboard={Dashboard} >
          // ...
    </Admin>
);

自定义首页 Dashboard

仓库中的示例 examples/tutorial/src/Dashboard.tsx 与 examples/tutorial/src/App.tsx 保持了一致的写法。

添加认证(Authentication)

大多数管理后台都需要认证。react-admin 可以在展示页面前校验用户凭据,并在 REST API 返回 403 时重定向到登录页。

react-admin 不对你的认证策略做任何假设(basic auth、OAuth、自定义路由等都可以),而是让你在正确的位置加入认证逻辑——通过 authProvider 对象。

由于本教程没有公开的认证 API,我们用一个假的认证提供者:接受一切登录请求,并把 username 存进 localStorage。每次页面跳转都会要求 localStorage 中存在 username 项。

authProvider 必须暴露 4 个 async 方法:

// in src/authProvider.ts
import { AuthProvider } from "react-admin";

export const authProvider: AuthProvider = {
    // called when the user attempts to log in
    async login({ username, password }) {
        // accept all username/password combinations
        if (false) {
            throw new Error("Invalid credentials, please try again");
        }
        localStorage.setItem("username", username);
    },
    // called when the user clicks on the logout button
    async logout() {
        localStorage.removeItem("username");
    },
    // called when the API returns an error
    async checkError({ status }: { status: number }) {
        if (status === 401 || status === 403) {
            localStorage.removeItem("username");
            throw new Error("Session expired");
        }
    },
    // called when the user navigates to a new location, to check for authentication
    async checkAuth() {
        if (!localStorage.getItem("username")) {
            throw new Error("Authentication required");
        }
    },
};

把这 4 个方法逐一拆解:

  • login:用户提交登录表单时调用。示例实现接受所有用户名/密码组合,将 username 写入 localStorage(真正的实现应在此调用你的登录 API 并校验凭据);
  • logout:用户点击退出按钮时调用,负责清理本地登录态;
  • checkError:API 返回错误时调用。当状态码为 401 或 403 时清除本地登录态并抛出错误,react-admin 会据此重定向到登录页;
  • checkAuth:用户导航到新位置时调用,用于校验是否已登录,未登录则抛出错误。

仓库示例 examples/tutorial/src/authProvider.ts 用 Promise 风格实现了同样逻辑,并额外补上了 getPermissions 方法(用于后续基于角色的权限控制)。

启用这套认证策略,只需把 authProvider 传给 <Admin>:

// in src/App.tsx
import { Dashboard } from './Dashboard';
import { authProvider } from './authProvider';

export const App = () => (
    <Admin authProvider={authProvider} dataProvider={dataProvider} dashboard={Dashboard} >
        // ...
    </Admin>
);

应用重新加载后,它会进入一个接受任何凭据的登录表单(演示视频见 docs/img/login.mp4)。

对接真实 API:手写自定义 Data Provider

这是本教程一直回避不了的“房间里的大象”。在真实项目中,你的 API 方言(REST?GraphQL?还是别的什么?)不会恰好匹配 JSONPlaceholder 的方言。编写 Data Provider 很可能是让 react-admin 跑起来要做的第一件事——除非你的后端已经有现成支持(可查看现有 provider 列表)。视 API 而定,这可能需要几个小时的工作量。

react-admin 把每个数据查询都委托给 Data Provider 对象,它充当与你的 API 之间的适配器。这让 react-admin 能够适配任何 API 方言、使用来自多个域名的端点等等。

例如,假设你需要对接 my.api.url 这个 REST API,它期望如下参数:

动作 期望的 API 请求
Get list GET http://my.api.url/posts?sort=["title","ASC"]&range=[0, 24]&filter={"title":"bar"}
Get one record GET http://my.api.url/posts/123
Get several records GET http://my.api.url/posts?filter={"id":[123,456,789]}
Get related records GET http://my.api.url/posts?filter={"author_id":345}
Create a record POST http://my.api.url/posts
Update a record PUT http://my.api.url/posts/123
Update records PUT http://my.api.url/posts?filter={"id":[123,124,125]}
Delete a record DELETE http://my.api.url/posts/123
Delete records DELETE http://my.api.url/posts?filter={"id":[123,124,125]}

react-admin 会针对表中每个动作调用 Data Provider 的一个方法,并期望返回一个 Promise。这些方法分别是:getList、getOne、getMany、getManyReference、create、update、updateMany、delete、deleteMany。发送 HTTP 请求并把响应转换为 react-admin 期望的格式,是 Data Provider 的职责。

针对 my.api.url 的 Data Provider 代码如下:

// in src/dataProvider.ts
import { DataProvider, fetchUtils } from "react-admin";
import { stringify } from "query-string";

const apiUrl = 'https://my.api.com/';
const httpClient = fetchUtils.fetchJson;

export const dataProvider: DataProvider = {
    getList: (resource, params) => {
        const { page, perPage } = params.pagination;
        const { field, order } = params.sort;
        const query = {
            sort: JSON.stringify([field, order]),
            range: JSON.stringify([(page - 1) * perPage, page * perPage - 1]),
            filter: JSON.stringify(params.filter),
        };
        const url = `${apiUrl}/${resource}?${stringify(query)}`;

        return httpClient(url).then(({ headers, json }) => ({
            data: json,
            total: parseInt((headers.get('content-range') || "0").split('/').pop() || '0', 10),
        }));
    },

    getOne: (resource, params) =>
        httpClient(`${apiUrl}/${resource}/${params.id}`).then(({ json }) => ({
            data: json,
        })),

    getMany: (resource, params) => {
        const query = {
            filter: JSON.stringify({ id: params.ids }),
        };
        const url = `${apiUrl}/${resource}?${stringify(query)}`;
        return httpClient(url).then(({ json }) => ({ data: json }));
    },

    getManyReference: (resource, params) => {
        const { page, perPage } = params.pagination;
        const { field, order } = params.sort;
        const query = {
            sort: JSON.stringify([field, order]),
            range: JSON.stringify([(page - 1) * perPage, page * perPage - 1]),
            filter: JSON.stringify({
                ...params.filter,
                [params.target]: params.id,
            }),
        };
        const url = `${apiUrl}/${resource}?${stringify(query)}`;

        return httpClient(url).then(({ headers, json }) => ({
            data: json,
            total: parseInt((headers.get('content-range') || "0").split('/').pop() || '0', 10),
        }));
    },

    update: (resource, params) =>
        httpClient(`${apiUrl}/${resource}/${params.id}`, {
            method: 'PUT',
            body: JSON.stringify(params.data),
        }).then(({ json }) => ({ data: json })),

    updateMany: (resource, params) => {
        const query = {
            filter: JSON.stringify({ id: params.ids}),
        };
        return httpClient(`${apiUrl}/${resource}?${stringify(query)}`, {
            method: 'PUT',
            body: JSON.stringify(params.data),
        }).then(({ json }) => ({ data: json }));
    },

    create: (resource, params) =>
        httpClient(`${apiUrl}/${resource}`, {
            method: 'POST',
            body: JSON.stringify(params.data),
        }).then(({ json }) => ({
            data: { ...params.data, id: json.id } as any,
        })),

    delete: (resource, params) =>
        httpClient(`${apiUrl}/${resource}/${params.id}`, {
            method: 'DELETE',
        }).then(({ json }) => ({ data: json })),

    deleteMany: (resource, params) => {
        const query = {
            filter: JSON.stringify({ id: params.ids}),
        };
        return httpClient(`${apiUrl}/${resource}?${stringify(query)}`, {
            method: 'DELETE',
        }).then(({ json }) => ({ data: json }));
    }
};

Tip:fetchUtils.fetchJson() 本质上是 fetch().then(r => r.json()) 的快捷方式,外加对 HTTP 响应码的控制——遇到 4xx 或 5xx 响应会抛出 HTTPError。如果不适合你的需求,完全可以放心直接使用 fetch()。

关于本示例中几个值得注意的实现要点:

  • getList 与 getManyReference 的总数来源:从响应头 content-range 中解析记录总数(.../总条数 格式),这与 jsonServerProvider 依赖 X-Total-Count 响应头类似——不同后端约定不同,你的 provider 必须匹配后端实际返回的格式;
  • 分页映射:react-admin 传入 params.pagination(page/perPage),这里换算成 range 参数(起始下标与结束下标),(page - 1) * perPage 到 page * perPage - 1;
  • create 的返回值:必须包含新记录 id,这里把服务端返回的 json.id 合并进 params.data 返回;
  • delete 的返回值:react-admin 期望拿到被删除记录,以便从本地状态中移除。

使用这个 provider 替换之前的 jsonServerProvider,只需换一个函数:

// in src/app.tsx
import { dataProvider } from './dataProvider';

const App = () => (
  <Admin dataProvider={dataProvider}>
    // ...
  </Admin>
);

结语与下一步

react-admin 从设计之初就强调可定制性。你可以把任意 react-admin 组件替换成自己的组件——比如为某个资源展示自定义列表布局或不同的编辑表单。

完成本教程后,你可以继续阅读 Guides and Concepts(架构与概念指南) 章节深入进阶。作为补充参考,也可以对照仓库中的配套示例 examples/tutorial(其依赖配置见 examples/tutorial/package.json,基于 react-admin 5、React 19、Vite 8 与 Material UI 6)。

Tip:react-admin 是一个大型框架,因此它的文档相当庞大,不要被吓到!它对任何规模的项目都适用。建议点击导航侧边栏顶部的 beginner mode(初学者模式) 按钮,它会从侧边栏隐藏高级特性(演示见 docs/img/beginner_mode.mp4),等你准备好进阶时再关闭它。

另外,为了弥合理论知识与实践经验之间的差距,可以充分利用 react-admin 的 Demos(示例项目) 合集——它们是 react-admin 在真实世界应用中如何使用的绝佳范例,也展示了超越简单 CRUD 应用的最佳实践。仓库中的 examples/crm 与 examples/demo 都是可运行的真实业务示例。

登录后查看全文
react-admin