前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载output_articlereact-adminReferenceField完全指南关联记录渲染、链接定制、聚合查询与性能优化ReferenceField是 react-admin 中用于展示多对一many-to-one与一对一one-to-one关联关系的核心字段组件——例如在渲染一篇由某位用户撰写的文章时展示该用户的详细信息。本指南基于官方文档 docs/ReferenceField.md 并结合仓库源码系统讲解其使用方式、全部 props 参数、数据获取原理、链接与访问控制机制以及 DataTable 场景下的聚合查询与预取优化帮助你写出更高效、更专业的关联字段代码。基础用法在 Show / Edit 视图中展示关联记录考虑这样一个数据模型posts文章通过user_id字段引用users用户资源即一篇文章有一个作者┌──────────────┐ ┌────────────────┐ │ posts │ │ users │ │--------------│ │----------------│ │ id │ ┌───│ id │ │ user_id │╾──┘ │ name │ │ title │ │ date_of_birth │ │ published_at │ └────────────────┘ └──────────────┘此时可以用ReferenceField在文章详情页展示作者信息import { Show, SimpleShowLayout, ReferenceField, TextField, DateField } from react-admin; export const PostShow () ( Show SimpleShowLayout TextField sourceid / TextField sourcetitle / DateField sourcepublished_at / ReferenceField sourceuser_id referenceusers labelAuthor / /SimpleShowLayout /Show );ReferenceField会获取关联数据将其放入RecordContext并渲染recordRepresentation默认是记录的id字段同时包裹一个指向关联用户Edit页的链接。因此建议为Resource配置recordRepresentation让关联记录以更有意义的方式呈现。例如若希望ReferenceField显示作者的完整姓名Resource nameusers list{UserList} recordRepresentation{(record) ${record.first_name} ${record.last_name}} /或者也可以给ReferenceField传入子组件它会渲染子组件而非recordRepresentation。ReferenceField常用的子组件是其他Field组件如TextFieldReferenceField sourceuser_id referenceusers TextField sourcename / /ReferenceField数据获取原理为什么用getMany而不是getOne该组件使用dataProvider.getMany()方法获取被引用的记录此例中的users并将其传递给子组件。从源码看ReferenceField的分层架构非常清晰UI 层packages/ra-ui-materialui/src/field/ReferenceField.tsx 负责渲染、错误/加载/空态展示、链接包裹与样式逻辑层packages/ra-core/src/controller/field/ReferenceFieldBase.tsx 负责搭建ResourceContext、RecordContext与ReferenceFieldContext并决定渲染 loading / offline / error / empty 中的哪一个分支控制器层packages/ra-core/src/controller/field/useReferenceFieldController.ts 读取字段值、发起查询并计算链接路径数据层packages/ra-core/src/controller/useReference.ts 最终调用useGetManyAggregate完成请求。数据层的关键实现见 packages/ra-core/src/controller/useReference.tsexport const useReference RecordType extends RaRecord RaRecord({ reference, id, options {}, }: UseReferencePropsRecordType): UseReferenceResultRecordType { const { meta, ...otherQueryOptions } options; const { data, error, isLoading, isFetching, isPaused, isPending, isPlaceholderData, refetch, } useGetManyAggregateRecordType, ErrorType( reference, { ids: [id], meta }, otherQueryOptions ); return { referenceRecord: data ? data[0] : undefined, refetch, error, isLoading, isFetching, isPaused, isPending, isPlaceholderData, }; };可以看到即使只引用一条记录底层也是以ids: [id]形式走useGetManyAggregate的getMany()聚合调用而不是getOne()。出于性能考虑当同一页面中有多个ReferenceField例如在DataTable中这样可以让dataProvider只被调用一次而不是每行调用一次。react-admin 会对多个getMany()调用进行合并与去重。Props 参数总览ReferenceField支持的 props 如下表格整理自 docs/ReferenceField.mdProp必填类型默认值说明source必填string-要显示的属性名当前记录中引用外键的字段名reference必填string-被引用记录所属的资源名如postschildren可选 *ReactNode-用于渲染被引用记录的一个或多个 Field 元素render可选 *(referenceFieldContext) ReactNode-用于渲染被引用记录的函数接收 reference field context 作为参数empty可选ReactNode-字段无值或引用缺失时渲染的内容label可选string \| Functionresources.[resource].fields.[source]在布局组件中渲染时用于字段的标签link可选string \| Functionedit包裹渲染子内容的链接目标。设为false可禁用链接。offline可选ReactNode-加载记录时无网络连接时渲染的内容queryOptions可选React QueryuseQuery的选项UseQueryOptions{}react-query客户端选项sortBy可选string \| Functionsource在 Datagrid 中用于排序的字段名*必须提供children或render其中之一。另外ReferenceField还接受 通用字段 props。从源码 packages/ra-ui-materialui/src/field/ReferenceField.tsx 中的ReferenceFieldProps接口可以看到它还额外支持emptyText已被empty取代的废弃 prop、translateChoice、offline与sx等属性。值得留意的是逻辑层 ReferenceFieldBase.tsx 会强制校验若同时未提供render与children会直接抛出错误if (!render !children) { throw new Error( ReferenceFieldBase requires either a render prop or children prop ); }children自定义关联记录的渲染内容默认情况下ReferenceField渲染被引用记录的recordRepresentation默认是id字段。可以通过传入一个或多个子组件来定制。由于ReferenceField为被引用记录创建了RecordContext任何字段组件都可以作为子组件使用例如TextField、DateField、FunctionField等ReferenceField sourceuser_id referenceusers TextField sourcefirst_name / TextField sourcelast_name / /ReferenceField或者使用renderprop 以自定义方式渲染被引用记录。empty引用缺失时的占位内容当被引用记录缺失时ReferenceField可以通过emptyprop 显示自定义消息ReferenceField sourceuser_id referenceusers emptyMissing user /ReferenceField在以下两种情况渲染empty元素被引用记录缺失users表中没有对应的user_id或字段为空当前记录没有user_id。当empty是字符串时ReferenceField会将其渲染为Typography并让文本经过 i18n 系统因此可以使用翻译键实现每个语言一条消息ReferenceField sourceuser_id referenceusers emptyresources.users.missing /也可以向emptyprop 传入 React 元素ReferenceField sourceuser_id referenceusers empty{spanMissing user/span} /从源码 ReferenceField.tsx 可见其实现细节当empty是字符串时会包一层Typography componentspan variantbody2并通过translate(empty, { _: empty })处理翻译同时保留了旧 propemptyText的向后兼容。而在逻辑层 ReferenceFieldBase.tsx 中shouldRenderEmpty的判断条件是非暂停状态且id为 null或记录缺失、无错误、非 pending 且empty不为false/undefined。label设置有意义的列头/字段标签默认情况下SimpleShowLayout、Datagrid等布局组件会根据字段的source推断标签。对于ReferenceField这可能并非你期望的效果{/* 默认标签是 User Id或 resources.posts.fields.user_id 的翻译如果存在 */} ReferenceField sourceuser_id referenceusers /因此经常需要为ReferenceField显式设置labelReferenceField labelAuthor name sourceuser_id referenceusers /提示使用DataTableDatagrid的继任组件时不再需要在字段上设置label才能让 Datagrid 使用它。DataTable通过DataTable.Col组件将列头 props 与字段本身的 props 正确分离。react-admin 使用 i18n 系统 翻译标签因此可以使用翻译键实现每种语言一个标签ReferenceField labelresources.posts.fields.author sourceuser_id referenceusers /link定制关联链接的目标要将链接从Edit页改为Show页将linkprop 设为showReferenceField sourceuser_id referenceusers linkshow /也可以通过设置link{false}阻止ReferenceField为子内容添加链接// 无链接 ReferenceField sourceuser_id referenceusers link{false} /还可以使用自定义link函数获取子内容的自定义路径。该函数必须接受record和reference两个参数// 自定义路径 ReferenceField sourceuser_id referenceusers link{(record, reference) /my/path/to/${reference}/${record.id}} /从源码看链接路径的计算发生在控制器层 useReferenceFieldController.ts它通过useGetPathForRecord根据record、reference资源与link配置计算路径而 UI 层 ReferenceField.tsx 中当link存在时用Link to{link}包裹子内容并附带onClick{stopPropagation}来阻止 DatagridrowClick的点击冒泡以及state{{ _scrollToTop: true }}实现跳转后滚动回顶部。在旧版本 react-admin 中该 prop 名为linkType现已废弃并被link取代但源码中保留了向后兼容见 ReferenceField.tsx 的注释。offline离线场景的降级渲染当用户离线时ReferenceField会智能地展示之前已获取过的被引用记录。但如果被引用记录从未被获取过ReferenceField会显示一条错误消息说明应用已失去网络连接。可以通过向offlineprop 传入 React 元素或字符串来自定义这条错误消息ReferenceField sourceuser_id referenceusers offline{spanNo network, could not fetch data/span} ... /ReferenceField ReferenceField sourceuser_id referenceusers offlineNo network, could not fetch data ... /ReferenceField从源码看默认离线 UI 是Offline variantinline /见 ReferenceField.tsx而 ReferenceFieldBase.tsx 中离线分支的触发条件是isPaused isPendingReact Query 检测到断网时将查询置于暂停状态。queryOptions透传 React Query 选项使用queryOptionsprop 将选项传递给获取被引用记录的dataProvider.getMany()查询可参考 useGetOne 文档中的聚合调用说明。例如传递自定义metaReferenceField sourceuser_id referenceusers queryOptions{{ meta: { foo: bar } }} TextField sourcename / /ReferenceField在数据层 useReference.ts 中queryOptions.meta会被解构出来与ids一起传入useGetManyAggregate而enabled选项在控制器层 useReferenceFieldController.ts 中被覆盖仅当id ! null且未显式设为false时查询才会启用。这解释了为什么empty判断中会把id null视为空态而非加载态。reference指定关联资源即要获取的关联记录所属资源。例如若posts资源有user_id字段将reference设为users即可获取每篇文章关联的用户ReferenceField sourceuser_id referenceusers /控制器 useReferenceFieldController.ts 会对缺失reference的情况抛出明确错误if (!reference) { throw new Error( useReferenceFieldController: missing reference prop. You must provide a reference, e.g. referenceposts. ); }render用渲染函数替代子组件作为children的替代方案可以给ReferenceField传入renderprop。它会接收ReferenceFieldContext作为参数并应返回一个 React 节点。这便于内联关联记录列表的渲染逻辑ReferenceField sourceuser_id referenceusers render{({ error, isPending, referenceRecord }) { if (isPending) { return pLoading.../p; } if (error) { return p classNameerror{error.message}/p; } return p{referenceRecord.name}/p; }} /render接收的 context 来自 ReferenceFieldContext.tsx 提供的UseReferenceFieldControllerResult包含referenceRecord、isLoading、isPending、isFetching、isPaused、error、refetch以及计算好的link等字段见 useReferenceFieldController.ts。sortByDatagrid 中的自定义排序列默认情况下在Datagrid中使用时用户点击ReferenceField的列头react-admin 会按字段source排序。要指定其他排名字段设置sortByReferenceField sourceuser_id referenceusers sortByuser.name /提示使用DataTableDatagrid的继任组件时不再需要为 Datagrid 指定sortByDataTable.Col组件会正确分离列头与字段的 props。sxCSS API 样式覆盖ReferenceField接受常规的classNameprop。也可以通过sx属性覆盖内部组件的许多样式语法与示例见 sx 文档。该属性支持以下子类规则名说明 .RaReferenceField-link应用于每个子元素从源码 ReferenceField.tsx 可见组件通过styled(span)定义Root容器并注册了RaReferenceField-root、RaReferenceField-link两个 class链接内所有元素的文字颜色默认使用主题palette.primary.main。若要使用 应用级样式覆盖 覆盖所有ReferenceField实例的样式请使用RaReferenceField键。性能DataTable 中的聚合查询与去重当在DataTable中使用时ReferenceField会为整张表格只获取一次被引用记录。例如使用如下代码import { List, DataTable, ReferenceField, EditButton } from react-admin; export const PostList () ( List DataTable DataTable.Col sourceid / DataTable.Col labelUser sourceuser_id ReferenceField sourceuser_id referenceusers / /DataTable.Col DataTable.Col sourcetitle / DataTable.Col EditButton / /DataTable.Col /DataTable /List );react-admin 会累积并去重被引用记录的 id为整个列表发起一次dataProvider.getMany()调用而不是 n 次dataProvider.getOne()调用。例如若 API 返回以下文章列表[ { id: 123, title: Totally agree, user_id: 789, }, { id: 124, title: You are right my friend, user_id: 789 }, { id: 125, title: Not sure about this one, user_id: 735 } ]那么 react-admin 会先以加载器渲染PostList中的ReferenceField然后用一次调用获取相关用户dataProvider.getMany(users, { ids: [789,735] })数据到达后重新渲染列表。这加速了渲染并最小化网络负载——注意user_id: 789被去重只请求一次。这与useGetManyAggregate在数据层 useReference.ts 的实现相印证。预取Prefetching消除关联数据闪烁当你知道某个页面会包含ReferenceField时可以配置主页面查询预取被引用记录以避免数据到达时的闪烁。为此给页面查询传递meta.prefetch参数。例如以下代码预取了文章引用的作者const PostList () ( List queryOptions{{ meta: { prefetch: [author] } }} DataTable DataTable.Col sourcetitle / DataTable.Col sourceauthor_id {/** 无需额外请求即可渲染 */} ReferenceField sourceauthor_id referenceauthors / /DataTable.Col /DataTable /List );注意预取功能要正常工作你的 data provider 必须支持 预取关联关系Prefetching Relationships。请查阅你的 data provider 文档确认是否支持该特性。注意预取是前端性能特性旨在避免闪烁和重绘它并不总能阻止ReferenceField获取数据。例如从列表视图进入 Show 视图时主记录已在缓存中页面立即渲染此时页面控制器和ReferenceField控制器会并行获取数据。页面控制器的预取数据在ReferenceField首次渲染之后才到达因此 data provider 仍会获取关联数据。但从用户体验看页面包括ReferenceField会立即显示。如果想避免ReferenceField获取数据可以使用 React Query Client 的staleTime选项。渲染多个字段多子组件、多字段与 FunctionField常常需要渲染引用表的多个字段例如users表有first_name和last_name两个字段。由于ReferenceField可以接受多个子组件你可以按需使用任意数量的Fieldimport { Show, SimpleShowLayout, ReferenceField, TextField, DateField, FunctionField } from react-admin; export const PostShow () ( Show SimpleShowLayout TextField sourceid / TextField sourcetitle / DateField sourcepublished_at / ReferenceField labelAuthor sourceuser_id referenceusers TextField sourcefirst_name /{ } TextField sourcelast_name / /ReferenceField /SimpleShowLayout /Show );还可以在同一个视图中为同一资源使用多个ReferenceField——react-admin 会去重只向远端表发一次请求。这在需要每个字段一个标签时很有用import { Show, SimpleShowLayout, ReferenceField, TextField, DateField } from react-admin; export const PostShow () ( Show SimpleShowLayout TextField sourceid / TextField sourcetitle / DateField sourcepublished_at / ReferenceField labelFirst name sourceuser_id referenceusers TextField sourcefirst_name / /ReferenceField ReferenceField labelLast name sourceuser_id referenceusers TextField sourcelast_name / /ReferenceField /SimpleShowLayout /Show );也可以使用FunctionField渲染由多个字段拼接而成的字符串import { Show, SimpleShowLayout, ReferenceField, TextField, DateField, FunctionField } from react-admin; export const PostShow () ( Show SimpleShowLayout TextField sourceid / TextField sourcetitle / DateField sourcepublished_at / ReferenceField labelName sourceuser_id referenceusers FunctionField render{record ${record.first_name} ${record.last_name}} / /ReferenceField /SimpleShowLayout /Show );移除链接可以通过将link设为false阻止ReferenceField为子内容添加链接// 无链接 ReferenceField sourceuser_id referenceusers link{false} /访问控制Access Control如果 authProvider 实现了canAccess方法且你没有提供linkpropreact-admin 会校验用户是否有权访问 Show 与 Edit 视图。例如给定以下ReferenceFieldReferenceField sourceuser_id referenceusers /react-admin 将以以下参数调用canAccess若users资源有 Show 视图{ action: show, resource: posts, record: Object }若users资源有 Edit 视图{ action: edit, resource: posts, record: Object }对应的单元测试可在 packages/ra-ui-materialui/src/field/ReferenceField.spec.tsx 中找到例如SlowAccessControl、LinkDefaultEditView、LinkDefaultShowView、LinkMissingView、LinkFalse等用例分别覆盖了访问控制下链接的生成、默认 Edit/Show 链接、缺失视图与禁用链接等场景Offline、MissingReferenceEmptyText、MissingReferenceIdEmptyTranslation等用例则验证了离线渲染与空态分支。小结ReferenceField是 react-admin 中处理外键关联展示的瑞士军刀通过sourcereference声明关联关系通过children/render控制呈现形式通过link/empty/offline处理链接、缺失与离线场景并通过底层useGetManyAggregate的聚合与去重机制在 DataTable 等场景中实现整表一次请求的高效数据获取。配合recordRepresentation、meta.prefetch预取以及canAccess访问控制可以构建出既美观又高性能、且安全可控的关联数据展示方案。 /output_article赞分享前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载相关推荐PDF补丁丁专业级PDF批量处理解决方案的深度解析PDF补丁丁专业级PDF批量处理解决方案的深度解析 在日常文档处理工作中PDF文件因其格式稳定、跨平台兼容性强而成为办公场景中的主流文档格式。然而当你面对前端UI组件react-admin ChipField 组件完全指南用 Material UI Chip 优雅展示标签字段与一对多关系react admin ChipField 组件完全指南用 Material UI Chip 优雅展示标签字段与一对多关系 本篇技术指南以 react adm前端UI组件react-admin 一对一关系编辑组件 ReferenceOneInput 完整使用指南react admin 一对一关系编辑组件 ReferenceOneInput 完整使用指南 ReferenceOneInput 是 react admin前端UI组件上一篇Pika内存管理机制如何平衡性能与资源消耗的终极指南下一篇yadm 版本控制策略管理 dotfiles 变更的最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考