企业官网建设流程全解析

• 前端
• UI组件

本指南讲解如何让 Claude Code、GitHub Copilot、Cursor、Gemini CLI、Codex 等 AI 编码助手写出符合 react-admin 最佳实践的代码。这些助手已经在大规模开源语料上训练过 react-admin 的知识，但要让它们稳定地产出惯用法（idiomatic）、可维护且与官方推荐一致的应用代码，仍需通过接入官方文档（Context7）与安装官方 Skill（Agent Skills）来主动引导。读完本文，你将掌握两套可立即落地的方案，并理解仓库内.agents/skills/react-admin/SKILL.md中沉淀的 150+ 组件、几十个 hooks 的使用纪律。

为什么 AI 编码助手写不好 react-admin 代码

react-admin 是一个构建在 REST/GraphQL API 之上的前端框架，基于 React Query、react-hook-form、react-router 与 Material UI 组合而成，本身提供了大量高阶抽象。AI 编码助手虽然"见过"react-admin，但它们训练数据里的示例鱼龙混杂：既有老版本 API，也有绕过框架直接用fetch/axios反模式，还有把Datagrid误用于新版本等过时写法。

因此，引导（guiding）比提示（prompting）更重要。官方文档在 docs/CodingAgents.md 中给出的核心观点是：要让 coding agent 显著提升生成质量，需要给它两条路径：

1. 精确 API 查询——通过 Context7 让 agent 直接读取官方文档，而不是凭记忆猜测某个 hook 或组件的参数；
2. 行为约束——通过官方 Skill（SKILL.md）让 agent 在生成代码时自动套用最佳实践。

这两条路径分别解决"记不准"与"写得差"两个问题，可以叠加使用。

方案一：通过 Context7 让 Agent 直接查阅官方文档

Context7 是什么

Context7 是一个把文档库暴露给 LLM 的 MCP（Model Context Protocol）服务器。对 react-admin 而言，项目根目录的 context7.json 就是它的文档索引配置，其中声明了：

• 项目标题与描述：React-admin，用于构建运行在浏览器中、对接 REST/GraphQL API 的单页应用；
• 索引范围："folders": ["docs"]，即整个docs/目录（同时排除*.html、*.js、*.css等非 Markdown 文件）；
• 历史版本锚点：v4.16.0、v3.19.0、v2.9.0，方便 agent 区分新旧 API。

安装与使用

在支持 MCP 的编码助手（Claude Code、Cursor、Codex 等）中安装 Context7 服务器后，即可在提示词中显式引用：

Add a form field to edit the author of the post. use context7 with /marmelab/react-admin

关键点在于第二行use context7 with /marmelab/react-admin——它让 agent 放弃"猜测式编码"，转而依据官方文档中该组件的 Props 表、示例与迁移说明来写代码。例如当 agent 需要确认<ReferenceManyField>的target/reference语义时，会直接检索 docs/ReferenceManyField.md 中"通过反向查找当前record.id在目标资源target字段中的值来获取关联记录列表"的权威描述，而非自行推断。

适用场景

Context7 最适合需要精确 API 细节的任务：某个 hook 的返回值结构、某个组件的可选 Props 与默认值、新旧版本的行为差异。当 agent 说"我不确定这个 API"时，第一反应应该是给它文档访问权，而不是让它继续猜。

方案二：安装官方 react-admin Skill（Agent Skills）

Skill 是什么

Skill 是一种以SKILL.md文件形式打包的、可复用的 Agent 行为指南。react-admin 仓库在.agents/skills/react-admin/SKILL.md中维护了官方 Skill，它既服务于 Marmelab 团队自身的编码流程，也可被外部用户复制到自己的项目中。

按各自 agent 的安装规范把 Skill 放进仓库即可，例如 Claude Code 对应路径：

.claude/skills/react-admin/SKILL.md

安装完成后，agent 会在生成代码时自动应用 react-admin 最佳实践，无需在每条提示词里反复强调。

安装前后对比：一个可验证的例子

原文档给出了一个非常直观的"装前 vs 装后"对照。假设需求是：

In the company detail view, show the list of the contacts of the company. （在公司详情视图中，展示该公司的联系人列表。）

• 未安装 Skill：agent 很可能手写一个自定义卡片列表组件，用useEffect+fetch或useGetList手工拉取数据，再自行处理加载态与空态。
• 安装 Skill 后：Skill 的"实体关系（Relationships Between Entities）"章节会引导 agent 选择<ReferenceManyField>（反向一对多关系、由被引用资源持有外键时使用）作为外层数据容器，配合<DataTable>渲染列，例如仓库 examples/simple/src/posts/PostShow.tsx 中TabbedShowLayout下展示帖子评论的写法：

<ReferenceManyField reference="comments" target="post_id" sort={{ field: 'created_at', order: 'DESC' }} > <DataTable> <DataTable.Col source="created_at" field={DateField} /> <DataTable.Col source="author.name" /> <DataTable.Col source="body" /> <DataTable.Col> <EditButton /> </DataTable.Col> </DataTable> </ReferenceManyField>

同样地，<DataTable>的选用也与 Skill 中"弃用说明"一致——新代码优先使用DataTable而非Datagrid。

深入 Skill 内容：Agent 被约束了哪些编码纪律

官方 Skill 全文约 230 行，是团队把多年 react-admin 开发经验固化成规则的结果。理解这些规则，能让你判断 agent 的输出是否符合预期，也能在提示词中更有针对性地补充约束。其核心纪律可归纳为八个方面。

1. Provider 抽象：禁止在组件里直接发 HTTP 请求

react-admin 从不直接调用 API，所有通信都经过三个可替换的适配器：

• dataProvider：承担全部 CRUD（getList、getOne、create、update、delete、getMany、getManyReference、updateMany、deleteMany）；
• authProvider：负责登录态与权限（login、logout、checkAuth、checkError、getIdentity、getPermissions、canAccess）；
• i18nProvider：负责国际化（translate、changeLocale、getLocale）。

Skill 把以下行为列为关键违规："永远不要在组件里使用fetch、axios或直接 HTTP 调用，一律使用 data provider hooks"。原因是只有经由 provider 的请求才能获得框架自带的缓存、加载态、错误处理、鉴权与乐观更新。数据层适配器生态见 docs/DataProviderList.md（Appwrite、Firebase、Hasura、JSON Server、GraphQL 等 50+ 后端适配器）。

2. 组合优于配置：用子组件覆盖行为

react-admin 主张"组合优于配置"——通过传入子组件来覆盖行为，而不是堆砌几十个 props：

<Edit actions={<MyCustomActions />}> <SimpleForm> <TextInput source="title" /> </SimpleForm> </Edit>

自定义布局传给<Admin layout={MyLayout}>，自定义菜单传给<Layout menu={MyMenu}>，层层向下传递。这与 docs/Architecture.md 描述的架构理念一致。

3. Context：Pull，Don't Push

组件通过 React Context 向下级暴露数据，下级用 hooks 取数而非逐层透传 props。Skill 明确了几个高频 hook：

• useRecordContext()——Show/Edit/Create 视图中当前记录；
• useListContext()——列表数据、筛选、分页、排序；
• useShowContext()/useEditContext()/useCreateContext()——详情页页面级状态；
• useTranslate()——i18n 翻译函数；
• useGetIdentity()——当前用户。

对应官方文档可查 docs/useRecordContext.md、docs/useListContext.md 等。

4. Hooks 优先：UI 不合适时降级到 Controller Hooks

当某个 react-admin 组件自带 UI 不满足需求时，不要从零手写，而是使用其底层的 controller hooks（命名规则use*Controller），它们提供了全部逻辑而不含任何 UI：

• useListController()——列表拉取、筛选、分页逻辑；
• useEditController()——编辑表单取数与提交逻辑；
• useShowController()——详情页取数逻辑。

这与仓库架构中"controller-view 分离"（controller 在ra-core，视图在ra-ui-materialui）的设计一脉相承，参见 Agents.md。

5. 数据获取：Query Hooks 与 Mutation Hooks

读取用 Query Hooks：

const { data, total, isPending, error } = useGetList('posts', { pagination: { page: 1, perPage: 25 }, sort: { field: 'created_at', order: 'DESC' }, filter: { status: 'published' }, }); const { data: record, isPending } = useGetOne('posts', { id: 123 }); const { data: records } = useGetMany('posts', { ids: [1, 2, 3] }); const { data, total } = useGetManyReference('comments', { target: 'post_id', id: 123, pagination: { page: 1, perPage: 25 }, });

写入用 Mutation Hooks，所有 mutation 返回[mutate, state]元组，并支持三种 mutation mode：

• pessimistic（默认）：等服务端响应后再更新 UI；
• optimistic：立即更新 UI，出错时回滚；
• undoable：立即更新 UI，弹出撤销提示，延迟提交。

const [create, { isPending }] = useCreate(); const [update] = useUpdate(); const [deleteOne] = useDelete(); create('posts', { data: { title: 'Hello' } }); update('posts', { id: 1, data: { title: 'Updated' }, previousData: record }); deleteOne('posts', { id: 1, previousData: record });

需要即时反馈时传mutationMode: 'optimistic'或'undoable'。在仓库示例 examples/simple/src/posts/PostCreate.tsx、examples/simple/src/comments/CommentEdit.tsx 中可以看到useCreate、useNotify、useRedirect的配合用法。

6. 实体关系：按需拉取，杜绝一次性全量加载

"为单个页面把包括关联数据在内的所有数据一次性拉齐"是被明确点名的反模式。Skill 要求按需取关联记录，并给出三类字段型组件：

{/* 展示当前记录基于 company_id 的公司 */} <ReferenceField source="company_id" reference="companies" /> {/* 展示关联记录列表（反向外键） */} <ReferenceManyField reference="comments" target="post_id"> <DataTable> <TextField source="body" /> <DateField source="created_at" /> </DataTable> </ReferenceManyField> {/* 展示多个被引用记录（ID 数组） */} <ReferenceArrayField source="tag_ids" reference="tags"> <SingleFieldList> <ChipField source="name" /> </SingleFieldList> </ReferenceArrayField>

以及输入型组件：

{/* 从另一资源中选择（外键） */} <ReferenceInput source="company_id" reference="companies" /> {/* 多选（ID 数组） */} <ReferenceArrayInput source="tag_ids" reference="tags" />

7. 表单：基于 react-hook-form 的声明式写法

react-admin 表单构建在 react-hook-form 之上，单列布局用<SimpleForm>，多标签页布局用<TabbedForm>。校验器直接挂在输入组件上：required()、minLength(min)、maxLength(max)、minValue(min)、maxValue(max)、number()、email()、regex(pattern, message)，或返回错误字符串的自定义函数：

<TextInput source="title" validate={[required(), minLength(3)]} />

动态表单（字段值影响其他字段）使用 RHF 的useWatch()。

8. 资源封装、Store 与常用副作用

• 资源定义：把资源的list/create/edit/icon/recordRepresentation封装进posts/index.ts统一导出，保持导入整洁；
• 持久化客户端状态：主题、列显隐、已保存筛选等用户偏好用useStore()持久化：

const [theme, setTheme] = useStore('theme', 'light');

• 通知 / 重定向 / 刷新：

const notify = useNotify(); const redirect = useRedirect(); const refresh = useRefresh(); notify('Record saved', { type: 'success' }); redirect('list', 'posts'); // 导航到 /posts redirect('edit', 'posts', 123); // 导航到 /posts/123 refresh(); // 使所有查询失效

• 自定义 dataProvider 方法：扩展 provider 添加领域方法，再用useDataProvider()+useQuery调用；
• 弃用项：新代码用DataTable替代Datagrid；权限检查优先<CanAccess>/useCanAccess。

仓库自带的第二份 Skill：i18n 国际化

除了 react-admin 主 Skill，仓库还在.agents/skills/i18n/SKILL.md维护了一份专门处理国际化的 Skill（react-admin-i18n），覆盖从"纯英文应用"到"多语言应用"的完整工作流：安装ra-i18n-polyglot+ra-language-*语言包、创建 i18nProvider、按命名空间（ra.*/resources.*/app.*）组织翻译目录、把 JSX 硬编码字符串转换为翻译键等。

若你的任务涉及国际化、翻译或语言切换，可在提示词中主动点名该 Skill。这与 docs/TranslationSetup.md、docs/Translation.md 等文档体系互相印证。

让 Agent 产出更高质量的补充建议

结合仓库内的 Agent Context 文件

仓库根目录的 Agents.md 是一份面向 agent 的"项目上下文"（CLAUDE.md通过@Agents.md引用它）。它记录了 react-admin 的设计原则（SPA 架构、向后兼容优先、Provider 模式、headless 核心、controller-view 分离、Context pull-don't-push）与反模式清单（禁止React.cloneElement()、禁止 children 内省、禁止死代码等）。把这部分上下文喂给 agent，可以让它在"用 react-admin 写代码"之外，还能"按照 react-admin 的工程规范写代码"——例如提交信息遵循 conventional commits、改动必须附带*.spec.tsx测试与*.stories.tsxStory。

组合使用三种资源

检查生成结果的提示

即使安装了 Skill，也建议在 Code Review 时对照 Skill 的纪律清单逐项核查：

• 组件里有没有出现fetch/axios直接调用？
• 关联数据是否用了 Reference 系列组件按需加载？
• 有没有在组件里逐层透传本应通过 context hooks 获取的数据？
• 用的是DataTable还是已弃用的Datagrid？
• 权限判断是否收敛到了authProvider.canAccess()/useCanAccess()，而非散落在各组件里？

结语

让 AI 编码助手写出高质量 react-admin 代码的关键，不是写更长的提示词，而是把官方知识显式地接入 agent 的工作流：用 Context7 提供权威 API 参考，用官方 Skill 约束生成行为，用 Agents.md 传递工程规范。三者叠加后，agent 处理"在详情页展示关联列表"这类任务时，会自动选择<ReferenceManyField>+<DataTable>这样的惯用组合，而不是重新发明一套与框架理念相悖的实现。这套方法论同样适用于 react-admin 生态之外——任何文档完善、约定明确的开源项目，都可以用相同方式让 coding agents 成为真正懂行的协作者。

• 前端
• UI组件