ng-zorro-antd 面包屑（Breadcrumb）组件完整指南：静态导航、路由自动生成与自定义配置

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本文是一篇围绕 ng-zorro-antd 中nz-breadcrumb面包屑组件的实战技术指南以官方文档 components/breadcrumb/doc/index.zh-CN.md 为骨架结合组件源码与示例代码深入展开。阅读本文后你将掌握面包屑的基本用法、基于 Angular Router 的自动生成机制nzAutoGenerate、以及nzSeparator、nzRouteLabel、nzRouteLabelFn、nzRouteFn等核心 API 的完整配置技巧并能直接将其落地到自己的 Angular 项目中。何时使用面包屑面包屑Breadcrumb用于显示当前页面在系统层级结构中的位置并提供向上返回的导航能力。根据官方文档在以下场景中应当使用当系统拥有超过两级以上的层级结构时当需要告知用户『你在哪里』时当需要向上导航的功能时。在 ng-zorro-antd 中面包屑的入口为NzBreadCrumbModule通过 public-api.ts 对外导出。引入模块后即可在模板中使用nz-breadcrumb及其子组件nz-breadcrumb-item。基础用法静态面包屑最简单的场景是直接在模板中声明面包屑的层级无需任何路由配置。参考示例 demo/basic.tsimport { Component } from angular/core; import { NzBreadCrumbModule } from ng-zorro-antd/breadcrumb; Component({ selector: nz-demo-breadcrumb-basic, imports: [NzBreadCrumbModule], template: nz-breadcrumb nz-breadcrumb-itemHome/nz-breadcrumb-item nz-breadcrumb-item aApplication List/a /nz-breadcrumb-item nz-breadcrumb-itemAn Application/nz-breadcrumb-item /nz-breadcrumb }) export class NzDemoBreadcrumbBasicComponent {}每个nz-breadcrumb-item对应一级导航内容可以是纯文本也可以是链接a。若需要配合路由跳转可直接在a上使用 Angular 原生的RouterLink见 demo/router.tsimport { RouterLink } from angular/router; Component({ selector: nz-demo-breadcrumb-router, imports: [RouterLink, NzBreadCrumbModule], template: nz-breadcrumb nz-breadcrumb-item a [routerLink][../../]Home/a /nz-breadcrumb-item nz-breadcrumb-itemBreadcrumb/nz-breadcrumb-item /nz-breadcrumb }) export class NzDemoBreadcrumbRouterComponent {}分隔符自定义nzSeparator默认情况下相邻的两个面包屑项之间以/分隔。[nzSeparator]允许你自定义分隔符它支持三种取值类型说明string任意字符串例如、-TemplateRefvoid自定义模板例如图标或 SVGnull不显示分隔符默认值为/。参考示例 demo/separator.ts!-- 使用字符串分隔符 -- nz-breadcrumb nzSeparator nz-breadcrumb-itemHome/nz-breadcrumb-item nz-breadcrumb-item aApplication List/a /nz-breadcrumb-item nz-breadcrumb-itemAn Application/nz-breadcrumb-item /nz-breadcrumb !-- 使用 TemplateRef 分隔符图标 -- nz-breadcrumb [nzSeparator]iconTemplate nz-breadcrumb-itemHome/nz-breadcrumb-item nz-breadcrumb-item aApplication List/a /nz-breadcrumb-item nz-breadcrumb-itemAn Application/nz-breadcrumb-item /nz-breadcrumb ng-template #iconTemplatenz-icon nzTypearrow-right //ng-template从源码看分隔符的渲染由nz-breadcrumb-separator组件承担breadcrumb-separator.component.ts其宿主 class 为ant-breadcrumb-separator。而在 breadcrumb-item.component.ts 中nzSeparator通过nzStringTemplateOutlet指令统一处理字符串与模板两种形态——这意味着你也可以在nzSeparator里放一个模板变量实现任意复杂的图形化分隔符例如箭头图标、冒号等。路由自动生成nzAutoGenerate当你的系统层级与路由结构一一对应时手动逐级书写nz-breadcrumb-item会显得冗长且容易遗漏。此时可以将[nzAutoGenerate]置为true让面包屑依据当前路由的嵌套层级自动生成。工作原理源码级解读自动生成的核心逻辑在 breadcrumb.component.ts 中ngOnInit中检测到nzAutoGenerate true时调用registerRouterChange()该方法订阅Router.events过滤出NavigationEnd事件并配合startWith(true)触发首次渲染每次路由切换后调用递归函数getBreadcrumbs(activatedRoute.root)从路由树根节点开始逐层向下解析在每一层只解析child.outlet PRIMARY_OUTLET的子路由即默认的router-outlet具名 outlet 会被忽略将child.snapshot.url的各段路径拼接为url从child.snapshot.data中取出标签最终生成BreadcrumbOption[]数组label面包屑显示文本params该路由快照中的参数url经nzRouteFn处理后的跳转地址。模板中遍历breadcrumbs为每一项渲染nz-breadcrumb-itema [attr.href]breadcrumb.url (click)navigate(...){{ breadcrumb.label }}/a/nz-breadcrumb-itemnavigate方法会preventDefault()后调用注入的Router.navigateByUrl(url)完成 SPA 内跳转避免整页刷新。需要特别注意的是若在未引入RouterModule的环境下使用nzAutoGenerate源码会抛出明确的错误提示You should import RouterModule if you want to use NzAutoGenerate.在路由中声明 data使用[nzAutoGenerate]时需要在路由配置中为对应路由定义databreadcrumb字段即该层级在面包屑上显示的名称{ path: path, component: SomeComponent, data: { breadcrumb: Display Name } }在模板中只需一行nz-breadcrumb [nzAutoGenerate]true/nz-breadcrumb最小可运行示例见 demo/auto.ts。懒加载路由的 data 放置位置对于懒加载路由loadChildren由于子路由模块在加载完成前其自身配置尚未注册应该在父层路由上写data否则自动生成时无法取到标签{ path: first, loadChildren: () import(./first/first.module).then(m m.FirstModule), data: { breadcrumb: First } }这与源码的递归逻辑相呼应当某层routeUrl为空懒加载占位路由通常无路径段时源码会保持nextUrl不变继续向下递归标签则从该层快照的data中读取。自定义路由属性名称nzRouteLabel默认情况下自动生成从路由data.breadcrumb取值。如果你的项目约定使用其他字段名例如与后端接口、其他文档工具统一的命名可以通过[nzRouteLabel]指定nz-breadcrumb [nzAutoGenerate]true [nzRouteLabel]customBreadcrumb/nz-breadcrumb{ path: path, component: SomeComponent, data: { customBreadcrumb: Display Name } }nzRouteLabel的类型为string默认值为breadcrumb。注意该参数仅在nzAutoGenerate为true时生效。国际化标签格式化nzRouteLabelFn在面向多语言的国际化应用中路由data中存的往往不是最终文案而是一个 i18n 翻译键。[nzRouteLabelFn]允许你传入一个格式化函数把取出的原始值翻译成用户看到的文字nz-breadcrumb [nzAutoGenerate]true [nzRouteLabel]breadcrumbI18nKey [nzRouteLabelFn]translateFn /nz-breadcrumb// In Route { path: path, component: SomeComponent, data: { breadcrumbI18nKey: i18n.aaa.bbbb } } // In component translateFn (key: string) this.yourI18nService.translate(key);其类型签名为(label: string) string默认值为恒等函数label label仅在nzAutoGenerate为true时生效。从源码看该函数作用于child.snapshot.data[this.nzRouteLabel]的取值结果并会在值为空时跳过该层级不生成面包屑项因此翻译键缺失不会产生空白导航项。URL 与 query params 定制nzRouteFn面包屑自动生成时每个导航项的跳转地址由路由路径拼接而来。如果需要在跳转 URL 上附加当前页面的 query params例如多页签系统中的筛选条件可以使用[nzRouteFn]对地址做二次加工nz-breadcrumb [nzAutoGenerate]true [nzRouteLabel]breadcrumbI18nKey [nzRouteLabelFn]translateFn [nzRouteFn]customRoute /nz-breadcrumb// In component bindCurrentParams(params, route) { let newRoute route; for (const key in params) { if (params.hasOwnProperty(key)) { newRoute ;${key}${params[key]}; } } return newRoute; } const params this.activatedRoute.snapshot.params; customRoute (route: string) this.bindCurrentParams(params, route);nzRouteFn的类型签名为(route: string) string默认值为route route仅在nzAutoGenerate为true时生效。源码中它作用于nextUrl即拼接后的完整路径返回值会被写入BreadcrumbOption.url并最终用于生成a href与Router.navigateByUrl的跳转目标。面包屑项下拉菜单nzOverlay当某一层级下存在多个分支时可以让该面包屑项挂接一个下拉菜单展示其子级入口。nz-breadcrumb-item提供[nzOverlay]输入接收一个NzDropdownMenuComponent类型的下拉模板参考示例 demo/dropdown.tsnz-breadcrumb nz-breadcrumb-itemAnt Design/nz-breadcrumb-item nz-breadcrumb-item aComponent/a /nz-breadcrumb-item nz-breadcrumb-item [nzOverlay]menu a hrefAn Application/a /nz-breadcrumb-item nz-breadcrumb-itemButton/nz-breadcrumb-item /nz-breadcrumb nz-dropdown-menu #menunzDropdownMenu ul nz-menu nzSelectable li nz-menu-itemGeneral/li li nz-menu-itemLayout/li li nz-menu-itemNavigation/li /ul /nz-dropdown-menu从 breadcrumb-item.component.ts 的实现看当nzOverlay存在时该项会被包裹在带ant-breadcrumb-overlay-linkclass 的nz-dropdown容器中并追加一个down方向图标nz-icon nzTypedown /点击即可展开下拉菜单。该能力同样可以叠加图标使用完整示例可参考 demo/with-icon.ts 与 demo/separator-independent.ts。API 参数速查表以下为nz-breadcrumb组件全部输入参数的官方定义同 index.zh-CN.md参数说明类型默认值[nzSeparator]分隔符自定义string \| TemplateRefvoid \| null/[nzAutoGenerate]自动生成 Breadcrumbbooleanfalse[nzRouteLabel]自定义 route data 属性名称nzAutoGenerate为true时才生效stringbreadcrumb[nzRouteLabelFn]格式化面包屑导航项的显示文字通常用于在国际化应用中翻译键值nzAutoGenerate为true时才生效(label: string) stringlabel label[nzRouteFn]格式化面包屑路由格式可用于为 URL 添加 query paramsnzAutoGenerate为true时才生效(route: string) routeroute route子组件nz-breadcrumb-item还提供[nzOverlay]类型NzDropdownMenuComponent | undefined用于在导航项上挂接下拉菜单。风格与细节根组件宿主 class 为ant-breadcrumb在 RTL 环境下会自动追加ant-breadcrumb-rtl源码中通过 CDK 的Directionality信号检测见 breadcrumb.component.ts因此面包屑可无缝适配阿拉伯语等从右到左排版的界面每项内容被包裹在ant-breadcrumb-link中分隔符渲染为ant-breadcrumb-separator样式定义见 style/index.less组件的自动化测试覆盖了基础渲染、下拉菜单、分隔符、RTL 方向等场景见 breadcrumb.spec.ts可作为接入与回归验证的参考。小结面包屑是导航体系中成本最低、收益最直观的组件之一。ng-zorro-antd 的nz-breadcrumb既支持纯模板静态声明也支持基于 Angular Router 的零手工自动生成当自动生成不足以覆盖你的业务规则时nzRouteLabel、nzRouteLabelFn、nzRouteFn三个钩子分别提供了字段名定制、国际化翻译和 URL 加工能力配合nzSeparator与nzOverlay即可覆盖绝大多数中后台系统的导航需求。赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd Breadcrumb 面包屑组件实战指南从基础用法到路由自动生成与国际化ng zorro antd Breadcrumb 面包屑组件实战指南从基础用法到路由自动生成与国际化 导读 Breadcrumb面包屑是 ng zorroUI组件前端ng-zorro-antd Breadcrumb 组件基本用法实战从静态列表到自动生成导航ng zorro antd Breadcrumb 组件基本用法实战从静态列表到自动生成导航 导读 本文围绕 ng zorro antdAngular 官方UI组件前端React Router路由面包屑动态生成和自定义面包屑的完整指南React Router路由面包屑动态生成和自定义面包屑的完整指南 React Router是现代React应用中最流行的路由解决方案而 面包屑导航 是提升前端路由上一篇PhotoDemon开发者指南如何基于VB6源码进行二次开发下一篇探索Akira一个高效、灵活的React UI框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考