Refine Chakra UI Breadcrumb 组件使用指南基于 useBreadcrumb 的层级导航面包屑【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine面包屑Breadcrumb用于展示当前页面在应用层级结构中的位置并允许用户快速返回上层页面。本文以 Refinev3.xx.xx的 Chakra UI 集成包中的Breadcrumb组件为核心讲解它的数据来源、全部配置属性breadcrumbProps、showHome、hideIcons等、嵌套资源与 i18n 行为并结合仓库源码剖析其底层实现帮助你在管理后台、仪表盘等内部工具中快速落地可用的面包屑导航。组件定位基于 Chakra UI 与 useBreadcrumb 的封装Refine 的 Chakra UI 包中提供了开箱即用的Breadcrumb组件。根据版本 3.xx.xx 的官方文档该组件构建在 Chakra UI 的 Breadcrumb 组件之上底层数据则来自 Refine Core 的useBreadcrumbHook。也就是说它完成了两件事数据层通过useBreadcrumb根据当前路由解析出的 resource 与 action自动生成面包屑条目数组展示层把生成的条目渲染为 Chakra UI 的Breadcrumb/BreadcrumbItem/BreadcrumbLink结构。在 Breadcrumb 组件实现 中可以看到核心逻辑export const Breadcrumb: React.FCBreadcrumbProps ({ breadcrumbProps, showHome true, hideIcons false, meta, minItems 2, }) { const { breadcrumbs } useBreadcrumb({ meta }); const Link useLink(); if (breadcrumbs.length minItems) return null; const { resources } useResourceParams(); const rootRouteResource matchResourceFromRoute(/, resources); return ( ChakraBreadcrumb mb3 {...breadcrumbProps} {showHome rootRouteResource?.found ( BreadcrumbItem Link to/ {rootRouteResource?.resource?.meta?.icon ?? IconHome size{20} /} /Link /BreadcrumbItem )} {breadcrumbs.map(({ label, icon, href }) { return ( BreadcrumbItem key{label} {!hideIcons icon} {href ? ( BreadcrumbLink ml{2} as{Link as any} to{href} {label} /BreadcrumbLink ) : ( BreadcrumbLink ml{2}{label}/BreadcrumbLink )} /BreadcrumbItem ); })} /ChakraBreadcrumb ); };从源码结构可以提炼出几个关键事实默认渲染阈值minItems 2当面包屑条目少于 2 个时组件直接返回null不渲染默认showHome true当存在匹配/根路由的 resource 时在最前面渲染“首页”入口每个条目由{ label, icon, href }三部分驱动href存在时渲染为链接否则渲染为纯文本图标通过!hideIcons icon控制可通过hideIcons关闭。数据来源useBreadcrumb 如何生成条目面包屑的内容完全由资源定义resources与当前路由推断而来。useBreadcrumb返回的breadcrumbs是一个对象数组每个对象包含属性说明label资源的显示名称href资源 list 页面的路由可选icon资源的图标可选其类型定义在useBreadcrumb实现 中export type BreadcrumbsType { label: string; href?: string; icon?: React.ReactNode; };生成流程可以概括为见 packages/core/src/hooks/breadcrumb/index.ts通过useResourceParams()获取当前路由对应的action、resource与全部resources若当前没有匹配的 resource!resource?.name直接返回空数组addBreadcrumb递归处理资源层级若资源的meta.parent存在会先递归添加父级条目通过getActionRoutesFromResource找到该资源的list路由并用composeRoute组合出完整href若当前action不是list如create、edit、show再追加一个动作条目其文本通过translate(actions.${action})获取。以一个简单的posts资源为例[ { name: posts, icon: divicon/div, list: () divList Page/div, create: () divCreate Page/div, }, ];在posts的list页面面包屑为[{ label: Posts, href: /posts, icon }]在posts的create页面面包屑为[{ label: Posts, href: /posts, icon }, { label: Create }]。注意两个边界情况如果资源没有定义icon条目的icon为undefined如果资源没有定义list页面条目的href为undefined此时Breadcrumb会将其渲染为纯文本而非链接与useBreadcrumb文档中的说明一致见 useBreadcrumb 文档。嵌套资源Nested resource当资源存在父子层级时useBreadcrumb会根据meta.parent或parentName递归展开父级条目。例如[ { name: cms }, { name: users, parentName: cms, list: () divList Page/div, create: () divCreate Page/div, }, ];users的list页面会得到[{ label: Cms }, { label: Users, href: /users }]users的create页面会得到[{ label: Cms }, { label: Users, href: /users }, { label: Create }]。这在多层级后台如“系统管理 → 用户管理 → 新建用户”中非常实用用户始终能沿面包屑返回任意上层。在 CRUD 页面中使用BreadcrumbBreadcrumb最常见的用法是通过 CRUD 组件的breadcrumb属性注入例如在Show、List、Create、Edit中import { Show, Breadcrumb } from pankod/refine-chakra-ui; const PostShow: React.FC () { return ( Show breadcrumb{Breadcrumb /} pRest of your page here/p /Show ); };从 Show 组件实现 可以看到CRUD 组件对breadcrumb的处理遵循“就近优先”原则const breadcrumb typeof breadcrumbFromProps undefined ? globalBreadcrumb : breadcrumbFromProps;即组件级breadcrumb属性优先未设置时回退到全局配置options.breadcrumb来自useRefineContext若两者都未定义则渲染默认的Breadcrumb /。List、Create、Edit组件的处理方式一致见 crud/list/index.tsx 与 crud/show/index.tsx。如果需要为整个应用统一配置面包屑可以在Refine的options中设置全局值相关说明见 refine-config 文档Refine options{{ breadcrumb: Breadcrumb /, // 或 breadcrumb: false 以全局禁用 }} /注意单个 CRUD 组件中设置的breadcrumb会覆盖全局options.breadcrumb的值。属性详解breadcrumbPropsBreadcrumb内部最终渲染的是 Chakra UI 的Breadcrumb组件因此所有 Chakra UI 的面包屑 props 都可以通过breadcrumbProps透传。例如自定义分隔符import { Show, Breadcrumb } from pankod/refine-chakra-ui; const PostShow: React.FC () { return ( Show breadcrumb{Breadcrumb breadcrumbProps{{ separator: - }} /} pRest of your page here/p /Show ); };在 组件源码 中breadcrumbProps被展开到 Chakra UI 的Breadcrumb上ChakraBreadcrumb mb3 {...breadcrumbProps}同时组件自身固定设置了mb3下边距。这意味着你可以通过breadcrumbProps传入 Chakra UIBreadcrumb支持的任何属性如separator、spacing、fontSize等。showHome如果应用中配置了DashboardPage根路由/对应一个 resource那么默认情况下Breadcrumb会在层级最顶部渲染一个“首页”按钮。若你不想展示首页按钮可将其设为falseShow breadcrumb{Breadcrumb showHome{false} /} pRest of your page here/p /Show其底层逻辑在 组件源码通过matchResourceFromRoute(/, resources)判断是否存在根路由资源存在且showHome为true时才渲染首页条目首页链接的图标优先取该资源的meta.icon否则回退为IconHome。hideIcons默认情况下面包屑会在每个条目旁显示资源的icon。若不需要显示资源图标设置hideIcons为trueShow breadcrumb{Breadcrumb hideIcons /} pRest of your page here/p /Show在 源码 中对应{!hideIcons icon}仅影响条目图标不会影响首页入口。minItems这是一个在文档的 PropsTable 之外、但已存在于源码与共享类型中的属性见 ui-types 类型定义。它表示渲染面包屑所需的最小条目数// 只有条目数 2 时才渲染默认值 Breadcrumb minItems{2} / // 即使只有一个条目也渲染 Breadcrumb minItems{1} /当breadcrumbs.length minItems时组件返回null实现位置。该行为也被共享测试覆盖见下文“测试验证”。metameta用于在路由生成过程中附加额外参数最终会传给useBreadcrumb({ meta })并参与composeRoute的 URL 组合见 useBreadcrumb 实现。典型场景是为带动态参数的嵌套路由补全参数值。i18n 支持面包屑的文本展示遵循以下优先级详见 useBreadcrumb 实现若资源定义了meta.label直接使用否则通过translate(${resourceName}.${resourceName}, humanize(name))进行翻译回退值为资源名的人性化形式如posts→PostsCRUD 动作create/edit/show等的标签通过translate(actions.${action})获取例如actions.create若翻译文件中缺少actions.${action}键代码会通过warnOnce输出一条警告并回退到translate(buttons.${action})或动作名的人性化形式源码位置。因此要为面包屑提供中文等多语言支持只需要在你的 i18n 翻译文件中添加形如actions.create: 创建、actions.edit: 编辑的键值即可。自定义与 Swizzle官方文档明确提示该组件支持swizzle组件定制化你可以使用refine CLI将组件源码“弹出”到你的项目中然后按需修改。例如npm run refine swizzle选择 Chakra UI 的Breadcrumb组件后即可在项目内获得一份可编辑的组件副本自由调整结构、样式或扩展逻辑而无需改动包源码。测试验证行为有据可查仓库中为面包屑提供了两层测试可用于验证上述行为共享测试packages/ui-tests/src/tests/breadcrumb.tsx覆盖了“条目数小于minItems时不渲染”“条目数达到minItems时渲染”“渲染资源名”“渲染链接href指向 list 路由”“渲染资源图标”“hideIcons隐藏图标”等用例这套测试被 Ant Design、MUI、Mantine 等所有 UI 包共用Chakra 专属测试packages/chakra-ui/src/components/breadcrumb/index.spec.tsx额外验证了“默认渲染首页图标”“showHome{false}时不渲染首页图标”“渲染资源名与动作名”。这些测试直接证明了资源条目链接指向其list路由expect(link).toHaveAttribute(href, /posts)、hideIcons与showHome的开关行为以及minItems的渲染阈值。完整属性速查属性类型默认值说明breadcrumbPropsChakraBreadcrumbProps—透传给 Chakra UIBreadcrumb的 props如separatorshowHomebooleantrue存在根路由资源时是否显示首页按钮hideIconsbooleanfalse是否隐藏资源图标metaRecordstring, string \| number—路由生成过程中的附加参数minItemsnumber2渲染所需的最小条目数少于该值则不渲染完整类型定义可参考 RefineBreadcrumbProps。小结Refine 的 Chakra UIBreadcrumb组件将“路由 → 资源 → 层级 → 文案”的推断逻辑封装在useBreadcrumb中配合 Chakra UI 的成熟样式体系让你无需手写任何导航逻辑即可获得与资源定义、i18n、全局配置保持一致的层级导航。无论是单层资源、嵌套资源还是需要关闭首页入口、隐藏图标、自定义分隔符都可以通过组件属性在数行代码内完成当默认行为无法满足需求时还可以通过 refine CLI 进行 swizzle 定制。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Refine Chakra UI Breadcrumb 组件使用指南：基于 useBreadcrumb 的层级导航面包屑
Refine Chakra UI Breadcrumb 组件使用指南基于 useBreadcrumb 的层级导航面包屑【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine面包屑Breadcrumb用于展示当前页面在应用层级结构中的位置并允许用户快速返回上层页面。本文以 Refinev3.xx.xx的 Chakra UI 集成包中的Breadcrumb组件为核心讲解它的数据来源、全部配置属性breadcrumbProps、showHome、hideIcons等、嵌套资源与 i18n 行为并结合仓库源码剖析其底层实现帮助你在管理后台、仪表盘等内部工具中快速落地可用的面包屑导航。组件定位基于 Chakra UI 与 useBreadcrumb 的封装Refine 的 Chakra UI 包中提供了开箱即用的Breadcrumb组件。根据版本 3.xx.xx 的官方文档该组件构建在 Chakra UI 的 Breadcrumb 组件之上底层数据则来自 Refine Core 的useBreadcrumbHook。也就是说它完成了两件事数据层通过useBreadcrumb根据当前路由解析出的 resource 与 action自动生成面包屑条目数组展示层把生成的条目渲染为 Chakra UI 的Breadcrumb/BreadcrumbItem/BreadcrumbLink结构。在 Breadcrumb 组件实现 中可以看到核心逻辑export const Breadcrumb: React.FCBreadcrumbProps ({ breadcrumbProps, showHome true, hideIcons false, meta, minItems 2, }) { const { breadcrumbs } useBreadcrumb({ meta }); const Link useLink(); if (breadcrumbs.length minItems) return null; const { resources } useResourceParams(); const rootRouteResource matchResourceFromRoute(/, resources); return ( ChakraBreadcrumb mb3 {...breadcrumbProps} {showHome rootRouteResource?.found ( BreadcrumbItem Link to/ {rootRouteResource?.resource?.meta?.icon ?? IconHome size{20} /} /Link /BreadcrumbItem )} {breadcrumbs.map(({ label, icon, href }) { return ( BreadcrumbItem key{label} {!hideIcons icon} {href ? ( BreadcrumbLink ml{2} as{Link as any} to{href} {label} /BreadcrumbLink ) : ( BreadcrumbLink ml{2}{label}/BreadcrumbLink )} /BreadcrumbItem ); })} /ChakraBreadcrumb ); };从源码结构可以提炼出几个关键事实默认渲染阈值minItems 2当面包屑条目少于 2 个时组件直接返回null不渲染默认showHome true当存在匹配/根路由的 resource 时在最前面渲染“首页”入口每个条目由{ label, icon, href }三部分驱动href存在时渲染为链接否则渲染为纯文本图标通过!hideIcons icon控制可通过hideIcons关闭。数据来源useBreadcrumb 如何生成条目面包屑的内容完全由资源定义resources与当前路由推断而来。useBreadcrumb返回的breadcrumbs是一个对象数组每个对象包含属性说明label资源的显示名称href资源 list 页面的路由可选icon资源的图标可选其类型定义在useBreadcrumb实现 中export type BreadcrumbsType { label: string; href?: string; icon?: React.ReactNode; };生成流程可以概括为见 packages/core/src/hooks/breadcrumb/index.ts通过useResourceParams()获取当前路由对应的action、resource与全部resources若当前没有匹配的 resource!resource?.name直接返回空数组addBreadcrumb递归处理资源层级若资源的meta.parent存在会先递归添加父级条目通过getActionRoutesFromResource找到该资源的list路由并用composeRoute组合出完整href若当前action不是list如create、edit、show再追加一个动作条目其文本通过translate(actions.${action})获取。以一个简单的posts资源为例[ { name: posts, icon: divicon/div, list: () divList Page/div, create: () divCreate Page/div, }, ];在posts的list页面面包屑为[{ label: Posts, href: /posts, icon }]在posts的create页面面包屑为[{ label: Posts, href: /posts, icon }, { label: Create }]。注意两个边界情况如果资源没有定义icon条目的icon为undefined如果资源没有定义list页面条目的href为undefined此时Breadcrumb会将其渲染为纯文本而非链接与useBreadcrumb文档中的说明一致见 useBreadcrumb 文档。嵌套资源Nested resource当资源存在父子层级时useBreadcrumb会根据meta.parent或parentName递归展开父级条目。例如[ { name: cms }, { name: users, parentName: cms, list: () divList Page/div, create: () divCreate Page/div, }, ];users的list页面会得到[{ label: Cms }, { label: Users, href: /users }]users的create页面会得到[{ label: Cms }, { label: Users, href: /users }, { label: Create }]。这在多层级后台如“系统管理 → 用户管理 → 新建用户”中非常实用用户始终能沿面包屑返回任意上层。在 CRUD 页面中使用BreadcrumbBreadcrumb最常见的用法是通过 CRUD 组件的breadcrumb属性注入例如在Show、List、Create、Edit中import { Show, Breadcrumb } from pankod/refine-chakra-ui; const PostShow: React.FC () { return ( Show breadcrumb{Breadcrumb /} pRest of your page here/p /Show ); };从 Show 组件实现 可以看到CRUD 组件对breadcrumb的处理遵循“就近优先”原则const breadcrumb typeof breadcrumbFromProps undefined ? globalBreadcrumb : breadcrumbFromProps;即组件级breadcrumb属性优先未设置时回退到全局配置options.breadcrumb来自useRefineContext若两者都未定义则渲染默认的Breadcrumb /。List、Create、Edit组件的处理方式一致见 crud/list/index.tsx 与 crud/show/index.tsx。如果需要为整个应用统一配置面包屑可以在Refine的options中设置全局值相关说明见 refine-config 文档Refine options{{ breadcrumb: Breadcrumb /, // 或 breadcrumb: false 以全局禁用 }} /注意单个 CRUD 组件中设置的breadcrumb会覆盖全局options.breadcrumb的值。属性详解breadcrumbPropsBreadcrumb内部最终渲染的是 Chakra UI 的Breadcrumb组件因此所有 Chakra UI 的面包屑 props 都可以通过breadcrumbProps透传。例如自定义分隔符import { Show, Breadcrumb } from pankod/refine-chakra-ui; const PostShow: React.FC () { return ( Show breadcrumb{Breadcrumb breadcrumbProps{{ separator: - }} /} pRest of your page here/p /Show ); };在 组件源码 中breadcrumbProps被展开到 Chakra UI 的Breadcrumb上ChakraBreadcrumb mb3 {...breadcrumbProps}同时组件自身固定设置了mb3下边距。这意味着你可以通过breadcrumbProps传入 Chakra UIBreadcrumb支持的任何属性如separator、spacing、fontSize等。showHome如果应用中配置了DashboardPage根路由/对应一个 resource那么默认情况下Breadcrumb会在层级最顶部渲染一个“首页”按钮。若你不想展示首页按钮可将其设为falseShow breadcrumb{Breadcrumb showHome{false} /} pRest of your page here/p /Show其底层逻辑在 组件源码通过matchResourceFromRoute(/, resources)判断是否存在根路由资源存在且showHome为true时才渲染首页条目首页链接的图标优先取该资源的meta.icon否则回退为IconHome。hideIcons默认情况下面包屑会在每个条目旁显示资源的icon。若不需要显示资源图标设置hideIcons为trueShow breadcrumb{Breadcrumb hideIcons /} pRest of your page here/p /Show在 源码 中对应{!hideIcons icon}仅影响条目图标不会影响首页入口。minItems这是一个在文档的 PropsTable 之外、但已存在于源码与共享类型中的属性见 ui-types 类型定义。它表示渲染面包屑所需的最小条目数// 只有条目数 2 时才渲染默认值 Breadcrumb minItems{2} / // 即使只有一个条目也渲染 Breadcrumb minItems{1} /当breadcrumbs.length minItems时组件返回null实现位置。该行为也被共享测试覆盖见下文“测试验证”。metameta用于在路由生成过程中附加额外参数最终会传给useBreadcrumb({ meta })并参与composeRoute的 URL 组合见 useBreadcrumb 实现。典型场景是为带动态参数的嵌套路由补全参数值。i18n 支持面包屑的文本展示遵循以下优先级详见 useBreadcrumb 实现若资源定义了meta.label直接使用否则通过translate(${resourceName}.${resourceName}, humanize(name))进行翻译回退值为资源名的人性化形式如posts→PostsCRUD 动作create/edit/show等的标签通过translate(actions.${action})获取例如actions.create若翻译文件中缺少actions.${action}键代码会通过warnOnce输出一条警告并回退到translate(buttons.${action})或动作名的人性化形式源码位置。因此要为面包屑提供中文等多语言支持只需要在你的 i18n 翻译文件中添加形如actions.create: 创建、actions.edit: 编辑的键值即可。自定义与 Swizzle官方文档明确提示该组件支持swizzle组件定制化你可以使用refine CLI将组件源码“弹出”到你的项目中然后按需修改。例如npm run refine swizzle选择 Chakra UI 的Breadcrumb组件后即可在项目内获得一份可编辑的组件副本自由调整结构、样式或扩展逻辑而无需改动包源码。测试验证行为有据可查仓库中为面包屑提供了两层测试可用于验证上述行为共享测试packages/ui-tests/src/tests/breadcrumb.tsx覆盖了“条目数小于minItems时不渲染”“条目数达到minItems时渲染”“渲染资源名”“渲染链接href指向 list 路由”“渲染资源图标”“hideIcons隐藏图标”等用例这套测试被 Ant Design、MUI、Mantine 等所有 UI 包共用Chakra 专属测试packages/chakra-ui/src/components/breadcrumb/index.spec.tsx额外验证了“默认渲染首页图标”“showHome{false}时不渲染首页图标”“渲染资源名与动作名”。这些测试直接证明了资源条目链接指向其list路由expect(link).toHaveAttribute(href, /posts)、hideIcons与showHome的开关行为以及minItems的渲染阈值。完整属性速查属性类型默认值说明breadcrumbPropsChakraBreadcrumbProps—透传给 Chakra UIBreadcrumb的 props如separatorshowHomebooleantrue存在根路由资源时是否显示首页按钮hideIconsbooleanfalse是否隐藏资源图标metaRecordstring, string \| number—路由生成过程中的附加参数minItemsnumber2渲染所需的最小条目数少于该值则不渲染完整类型定义可参考 RefineBreadcrumbProps。小结Refine 的 Chakra UIBreadcrumb组件将“路由 → 资源 → 层级 → 文案”的推断逻辑封装在useBreadcrumb中配合 Chakra UI 的成熟样式体系让你无需手写任何导航逻辑即可获得与资源定义、i18n、全局配置保持一致的层级导航。无论是单层资源、嵌套资源还是需要关闭首页入口、隐藏图标、自定义分隔符都可以通过组件属性在数行代码内完成当默认行为无法满足需求时还可以通过 refine CLI 进行 swizzle 定制。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
