前端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点击查看免费下载ReferenceOneField是 react-admin 中用于渲染一对一one-to-one关系的专用字段组件它以当前记录的某字段通常是外键为线索从远端资源中拉取关联记录并渲染其内容。本文基于仓库文档 docs/ReferenceOneField.md 并结合 ra-ui-materialui 与 ra-core 的源码实现系统讲解它的数据获取原理、全部 Props 参数、常见场景与源码级验证帮助你在一对一、甚至从一对多集合中挑一条记录的场景下写出高质量代码。组件定位它解决什么问题在一对一关系中当前记录例如books资源中的一本书并不直接携带关联对象的全部字段而是通过远端资源上的外键字段例如book_details.book_id指向对方。ReferenceOneField正是为这种关系设计它根据当前record的值用外键book_id构建查询条件目标字段由targetprop 指定它调用dataProvider.getManyReference(book_details, { target: book_id, id: book.id })获取关联记录若匹配到多条记录则取第一条展示。关系示意如下来自原文档┌──────────────┐ ┌──────────────┐ │ books │ │ book_details │ │--------------│ │--------------│ │ id │───┐ │ id │ │ title │ └──╼│ book_id │ │ published_at │ │ genre │ └──────────────┘ │ ISBN │ └──────────────┘行为上它与ReferenceManyField相似底层都走getManyReference区别在于它只展示第一条关联记录因此非常适合一对一关系。默认情况下它会渲染关联记录的recordRepresentation见 Resource.md#recordrepresentation同时会为关联记录创建RecordContext所以TextField、SimpleShowLayout等任何依赖该上下文的组件都能直接作为子元素使用。**反向关系book_detail 反查它所关联的 book**请使用ReferenceField编辑一对一关系中的记录则使用ReferenceOneInput。基本用法在books资源的 Show 视图中渲染book_details资源的字段是它的典型应用const BookShow () ( Show SimpleShowLayout TextField sourcetitle / DateField sourcepublished_at / ReferenceField sourceauthorId referenceauthors / ReferenceOneField labelGenre referencebook_details targetbook_id TextField sourcegenre / /ReferenceOneField ReferenceOneField labelISBN referencebook_details targetbook_id TextField sourceISBN / /ReferenceOneField /SimpleShowLayout /Show );提示与ReferenceField一样你可以在同一个组件中多次调用ReferenceOneField例如上面分别渲染Genre和ISBN两个字段react-admin 会针对同一个 reference只发起一次dataProvider.getManyReference()调用无需担心重复请求。Props 一览Prop必填类型默认值说明reference是string-关联记录所在资源的名称例如book_detailstarget是string-关联资源上承载关系的外键字段名例如book_idchildren否ReactNode-用于渲染关联记录的 Field 元素render否(ReferenceFieldContext) ReactNode-接收ReferenceFieldContext并返回 React 元素的函数empty否ReactNode-关联记录为空时显示的文本或元素filter否Object{}用于过滤关联记录link否string \| Functionedit包裹渲染内容的链接目标设为false可禁用链接offline否ReactNode-无网络连接时显示的文本或元素queryOptions否UseQueryOptions{}react-query 客户端选项sort否{ field: String, order: ASC or DESC }{ field: id, order: ASC }关联记录的排序规则此外ReferenceOneField还接受 Fields.md 中的公共字段 Props如label、source等。源码视角数据是怎么取回来的理解ReferenceOneField的底层链路能帮你更精准地使用其 Props。从源码结构看它分为三层UI 层packages/ra-ui-materialui/src/field/ReferenceOneField.tsx负责将empty/emptyText统一处理后交给基础组件并透传offline默认节点默认渲染Offline variantinline /。基础组件层packages/ra-core/src/controller/field/ReferenceOneFieldBase.tsx组合控制器结果并按优先级渲染loading/offline/error/empty/children或render的结果同时依次包裹ResourceContextProvider值为 reference、ReferenceFieldContextProvider与RecordContextProvider值为关联记录。控制器层packages/ra-core/src/controller/field/useReferenceOneFieldController.tsx真正发起数据请求的 hook。控制器的关键逻辑如下useReferenceOneFieldController.tsxconst { reference, target, source id, sort { field: id, order: ASC }, filter {}, queryOptions {}, } props; const record useRecordContextRecordType(props); const { data, error, ... } useGetManyReference(reference, { target, id: get(record, source), pagination: { page: 1, perPage: 1 }, sort, filter, meta, }, { enabled: !!record, onError: error notify(...), ...otherQueryOptions, }); return { referenceRecord: data ? data[0] : undefined, ... };由此可以确认几个实现细节source默认是id即用当前记录的id作为关联查询的外键值sort默认{ field: id, order: ASC }filter默认{}分页被硬编码为{ page: 1, perPage: 1 }配合data[0]实现只取第一条关联记录请求仅在存在record时才启用enabled: !!record请求出错会自动通过useNotify弹出错误通知返回的referenceRecord会被放入RecordContext因此子组件可以像使用普通记录字段一样直接读取关联记录。另外ReferenceOneField在 Datagrid 表头中默认不可排序源码中显式设置ReferenceOneField.sortable false原因见 ReferenceOneField.tsx其默认sourceid会与默认排序{ field: id, order: DESC }匹配导致表头出现错误的排序指示符。children自定义关联记录的渲染默认情况下ReferenceOneField渲染关联记录的recordRepresentation。如果传入子组件则改用子组件在关联记录的RecordContext中渲染给你完全的自由度。例如同时展示一本书的genre和ISBNReferenceOneField labelDetails referencebook_details targetbook_id TextField sourcegenre / (TextField sourceISBN /) /ReferenceOneField注意ReferenceOneField期望单个 Field 作为子元素如需展示多个字段可将它们组合在一个 Fragment 或布局组件中。render内联渲染逻辑除了children还可以用renderprop 接收ReferenceFieldContext并返回 React 节点适合把渲染逻辑内联在组件调用处。上下文中可解构出isPending、error、referenceRecord等状态ReferenceOneField referencebook_details targetbook_id render{({ isPending, error, referenceRecord }) { if (isPending) { return pLoading.../p; } if (error) { return p classNameerror {error.toString()}/p; } if (!referenceRecord) { return p classNameerrorNo details found/p; } return ( dl dtGenre/dt dd{referenceRecord.genre}/dd dtISBN/dt dd{referenceRecord.ISBN}/dd /dl ); }} /当render与children都未提供时基础组件会抛出ReferenceOneFieldBase requires either a render prop or children prop错误见 ReferenceOneFieldBase.tsx。empty关联记录为空时的展示关联记录不存在时可用empty自定义提示内容它接受三种形式。字符串文本ReferenceOneField labelDetails referencebook_details targetbook_id emptyno detail TextField sourcegenre / (TextField sourceISBN /) /ReferenceOneField翻译键empty会自动被 i18n 翻译ReferenceOneField labelDetails referencebook_details targetbook_id emptyresources.books.not_found TextField sourcegenre / (TextField sourceISBN /) /ReferenceOneField任意 ReactNode例如一个引导创建关联记录的按钮ReferenceOneField labelDetails referencebook_details targetbook_id empty{CreateButton to/book_details/create /} TextField sourcegenre / (TextField sourceISBN /) /ReferenceOneField从 UI 层源码看empty在传入字符串时会被包装为Typography并调用translate()翻译键缺失时回退显示原文见 ReferenceOneField.tsx。另外旧版 propemptyText已被标记为deprecated建议统一使用empty。filter在一对多关系中挑选记录ReferenceOneField也可用于一对多关系此时显示第一条记录。filter在此场景下特别有用——它可以帮你筛选出要展示的那一条。例如某产品有多个币种的价格只想展示欧元价格ReferenceOneField labelPrice (€) referenceproduct_prices targetproduct_id filter{{ currency: EUR }} NumberField sourceprice / /ReferenceOneField控制器会将filter原样透传给getManyReference见 useReferenceOneFieldController.tsx因此它支持 data provider 定义的一切过滤语义。sort排序并取第一条在一对多关系中sort决定哪一条记录排在最前从而决定展示哪一条。例如在讨论discussion中展示最新一条消息ReferenceOneField referencemessages targetdiscussion_id sort{{ field: createdAt, order: DESC }} TextField sourcebody / /ReferenceOneFieldsort默认值为{ field: id, order: ASC }可通过order指定ASC或DESC。link链接到关联记录默认情况下ReferenceOneField会把渲染内容链接到关联记录的编辑页。设置为false可禁用链接ReferenceOneField labelGenre referencebook_details targetbook_id link{false} TextField sourcegenre / /ReferenceOneFieldlink也可以是一个字符串取值可以是edit、show、某个路由路径或一个基于记录返回路由路径的函数ReferenceOneField labelGenre referencebook_details targetbook_id link{record /custom/${record.id}} TextField sourcegenre / /ReferenceOneField基础组件通过useGetPathForRecord({ record, resource: reference, link })计算链接路径并把结果合并进ReferenceFieldContext见 ReferenceOneFieldBase.tsx。offline离线状态的处理当用户处于离线状态时ReferenceOneField足够聪明若关联记录此前已被获取过在 react-query 缓存中会继续展示该记录若关联记录从未获取过则展示一条提示应用已失去网络连接的错误消息。默认离线提示节点由 UI 层提供Offline variantinline /你也可以通过offlineprop 传入自定义元素或字符串覆盖ReferenceOneField referencebook_details targetbook_id offline{pNo network, could not fetch data/p} ... /ReferenceOneField ReferenceOneField referencebook_details targetbook_id offlineNo network, could not fetch data ... /ReferenceOneField该行为在测试中得到了验证在 ReferenceOneFieldBase.spec.tsx 中测试先模拟离线再切换子组件断言离线提示出现随后模拟恢复在线数据得以加载再次模拟离线时已加载的数据仍能继续显示并出现数据可能已过期的提示。queryOptions精细控制请求行为ReferenceOneField底层基于 react-query 发起请求因此可以透传useQuery的任意选项refetchInterval、staleTime、select等。例如关闭窗口聚焦时的自动重新请求ReferenceOneField labelGenre referencebook_details targetbook_id queryOptions{{ refetchOnWindowFocus: false }} TextField sourcegenre / /ReferenceOneField从控制器源码看queryOptions中还可以传递meta给 data provider请求的enabled已被内部固定为!!record错误处理也会自动调用notify这些行为通常不需要你覆盖。reference与target两个必填参数reference要获取关联记录的资源名。例如要展示某本书的详情reference应为book_detailsReferenceOneField labelGenre referencebook_details targetbook_id TextField sourcegenre / /ReferenceOneFieldtarget关联资源上承载关系的外键字段名。以下面的表结构为例关系由book_id承载因此target设为book_id┌──────────────┐ ┌──────────────┐ │ books │ │ book_details │ │--------------│ │--------------│ │ id │───┐ │ id │ │ title │ └──╼│ book_id │ │ published_at │ │ genre │ └──────────────┘ │ ISBN │ └──────────────┘ReferenceOneField labelGenre referencebook_details targetbook_id TextField sourcegenre / /ReferenceOneField综合实战在一对多集合中展示一条记录把sort和filter组合起来就能实现从多条关联记录中挑出特定一条的效果例如展示某本书最新的一条五星评价const BookShow () ( Show SimpleShowLayout TextField sourcetitle / DateField sourcepublished_at / ReferenceOneField labelLatest cool review referencebook_reviews targetbook_id sort{{ field: createdAt, order: DESC }} filter{{ rating: 5 }} TextField sourcetitle / /ReferenceOneField /SimpleShowLayout /Show );在这个例子中filter{{ rating: 5 }}先把关联记录缩小到五星评价sort{{ field: createdAt, order: DESC }}再把最新的排在首位最终展示第一条——即最新的五星评价。移除默认链接再次强调默认链接指向关联记录的编辑页。若不需要跳转设置link{false}即可ReferenceOneField labelGenre referencebook_details targetbook_id link{false} TextField sourcegenre / /ReferenceOneField测试与验证组件的可靠性仓库为ReferenceOneField提供了完整的行为测试覆盖了核心渲染路径ReferenceOneFieldBase.spec.tsx加载状态Loadingstory 渲染后断言Loading...文本出现数据渲染Basicstory 渲染后断言关联记录的9780393966473ISBN被展示renderprop分别验证加载状态与数据状态离线行为模拟离线/上线切换验证离线提示、缓存数据展示与过期提示的完整流程。配合 ReferenceOneField.stories.tsx 中的Basic、Loading、Offline、WithRenderProp等 Storybook 故事其默认 data provider 返回[{ id: 1, ISBN: 9780393966473, genre: novel }]你可以直观地在本地 Storybook 中看到组件的各种状态与真实交互效果。小结ReferenceOneField是 react-admin 处理一对一关系的开箱即用方案底层复用getManyReference并按取第一条的语义封装对外提供children/render两种渲染方式、empty/offline两类状态兜底、filter/sort的记录挑选能力以及link/queryOptions等精细化控制。无论是标准的books → book_details一对一展示还是从一堆评价里挑最新一条五星评价这类一对多挑一场景它都能以极少的样板代码完成任务。若要深入了解反向关系或编辑场景可继续阅读 docs/ReferenceField.md 与 docs/ReferenceOneInput.md。赞分享前端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点击查看免费下载相关推荐ReferenceField 完整指南react-admin 多对一关系字段的渲染、链接、性能与源码解析ReferenceField 完整指南react admin 多对一关系字段的渲染、链接、性能与源码解析 output_article react adm前端UI组件react-admin 数据获取进阶useGetManyReference Hook 完全指南react admin 数据获取进阶 useGetManyReference Hook 完全指南 useGetManyReference 是 react ad前端UI组件react-admin ChipField 组件完全指南用 Material UI Chip 优雅展示标签字段与一对多关系react admin ChipField 组件完全指南用 Material UI Chip 优雅展示标签字段与一对多关系 本篇技术指南以 react adm前端UI组件上一篇炉石传说HsMod插件55项功能让你重新定义游戏体验下一篇证件照DPI设置完全指南用HivisionIDPhotos制作高清证件照创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考