企业官网建设流程全解析

• UI组件
• 前端

本文是一篇围绕 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.ts：

import { Component } from '@angular/core'; import { NzBreadCrumbModule } from 'ng-zorro-antd/breadcrumb'; @Component({ selector: 'nz-demo-breadcrumb-basic', imports: [NzBreadCrumbModule], template: ` <nz-breadcrumb> <nz-breadcrumb-item>Home</nz-breadcrumb-item> <nz-breadcrumb-item> <a>Application List</a> </nz-breadcrumb-item> <nz-breadcrumb-item>An Application</nz-breadcrumb-item> </nz-breadcrumb> ` }) export class NzDemoBreadcrumbBasicComponent {}

每个nz-breadcrumb-item对应一级导航；内容可以是纯文本，也可以是链接（<a>）。若需要配合路由跳转，可直接在<a>上使用 Angular 原生的RouterLink，见 demo/router.ts：

import { 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-item>Breadcrumb</nz-breadcrumb-item> </nz-breadcrumb> ` }) export class NzDemoBreadcrumbRouterComponent {}

分隔符自定义：nzSeparator

默认情况下，相邻的两个面包屑项之间以/分隔。[nzSeparator]允许你自定义分隔符，它支持三种取值：

默认值为'/'。参考示例 demo/separator.ts：

<!-- 使用字符串分隔符 --> <nz-breadcrumb nzSeparator=">"> <nz-breadcrumb-item>Home</nz-breadcrumb-item> <nz-breadcrumb-item> <a>Application List</a> </nz-breadcrumb-item> <nz-breadcrumb-item>An Application</nz-breadcrumb-item> </nz-breadcrumb> <!-- 使用 TemplateRef 分隔符（图标） --> <nz-breadcrumb [nzSeparator]="iconTemplate"> <nz-breadcrumb-item>Home</nz-breadcrumb-item> <nz-breadcrumb-item> <a>Application List</a> </nz-breadcrumb-item> <nz-breadcrumb-item>An Application</nz-breadcrumb-item> </nz-breadcrumb> <ng-template #iconTemplate><nz-icon nzType="arrow-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 中：

1. ngOnInit中检测到nzAutoGenerate === true时调用registerRouterChange()；
2. 该方法订阅Router.events，过滤出NavigationEnd事件，并配合startWith(true)触发首次渲染；
3. 每次路由切换后调用递归函数getBreadcrumbs(activatedRoute.root)，从路由树根节点开始逐层向下解析；
4. 在每一层只解析child.outlet === PRIMARY_OUTLET的子路由（即默认的<router-outlet>，具名 outlet 会被忽略），将child.snapshot.url的各段路径拼接为url，从child.snapshot.data中取出标签，最终生成BreadcrumbOption[]数组：
   • label：面包屑显示文本；
   • params：该路由快照中的参数；
   • url：经nzRouteFn处理后的跳转地址。
5. 模板中遍历breadcrumbs，为每一项渲染<nz-breadcrumb-item><a [attr.href]="breadcrumb.url" (click)="navigate(...)">{{ breadcrumb.label }}</a></nz-breadcrumb-item>；
6. navigate方法会preventDefault()后调用注入的Router.navigateByUrl(url)完成 SPA 内跳转，避免整页刷新。

需要特别注意的是：若在未引入RouterModule的环境下使用nzAutoGenerate，源码会抛出明确的错误提示：You should import RouterModule if you want to use 'NzAutoGenerate'.

在路由中声明 data

使用[nzAutoGenerate]时，需要在路由配置中为对应路由定义data，breadcrumb字段即该层级在面包屑上显示的名称：

{ 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.ts：

<nz-breadcrumb> <nz-breadcrumb-item>Ant Design</nz-breadcrumb-item> <nz-breadcrumb-item> <a>Component</a> </nz-breadcrumb-item> <nz-breadcrumb-item [nzOverlay]="menu"> <a href>An Application</a> </nz-breadcrumb-item> <nz-breadcrumb-item>Button</nz-breadcrumb-item> </nz-breadcrumb> <nz-dropdown-menu #menu="nzDropdownMenu"> <ul nz-menu nzSelectable> <li nz-menu-item>General</li> <li nz-menu-item>Layout</li> <li nz-menu-item>Navigation</li> </ul> </nz-dropdown-menu>

从 breadcrumb-item.component.ts 的实现看，当nzOverlay存在时，该项会被包裹在带ant-breadcrumb-overlay-linkclass 的nz-dropdown容器中，并追加一个down方向图标（<nz-icon nzType="down" />），点击即可展开下拉菜单。该能力同样可以叠加图标使用，完整示例可参考 demo/with-icon.ts 与 demo/separator-independent.ts。

API 参数速查表

以下为nz-breadcrumb组件全部输入参数的官方定义（同 index.zh-CN.md）：

子组件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组件
• 前端