企业官网建设流程全解析

• UI组件
• 前端

在 Angular 应用中，"标签页与 URL 深度绑定"是导航型页面的常见诉求：用户点击 tab 时地址栏同步变化，刷新或分享链接时又能自动恢复正确的 tab。ng-zorro-antd 的 Tabs 组件通过nzLinkRouter与*nzTabLink指令提供了这一开箱即用的能力。本文以官方示例 link-router.md 为骨架，结合源码与测试用例，讲解如何实现"点击 tab 改路由、路由变化自动切 tab"的双向联动，并带你理解其底层匹配原理与边界行为。

路由联动要解决什么问题

Tabs 组件本身只维护"当前选中第几个面板"这一组件内状态。一旦页面刷新，nzSelectedIndex会回到默认值，用户之前所处的 tab 上下文就会丢失。路由联动（Link with Router）的目标是：

• 点击 tab 时同步更新路由：把当前 tab 的身份信息（路径或 query 参数）写入 URL；
• 路由变化时自动切换 tab：通过浏览器前进/后退、地址栏输入或代码router.navigate改变 URL 后，Tabs 自动选中与当前 URL 匹配的那一项。

示例文档对此的描述非常精炼："与路由联动，点击 tab 更改路由，并且在路由改变时自动切换 tab。"（见 link-router.md）。下面从 API 用法到源码实现逐层展开。

三个核心 API：nzLinkRouter、*nzTabLink、a[nz-tab-link]

路由联动由三个要素组合而成，它们在 Tabs 官方 API 文档 中均有明确定义：

其中ng-template[nzTabLink]与a[nz-tab-link]是两条独立指令，定义在 tab-link.directive.ts：

• NzTabLinkTemplateDirective（选择器ng-template[nzTabLink]）：仅用于捕获模板引用，其注释明确写到这是为了修复 angular/angular#8563 这类渲染顺序问题；
• NzTabLinkDirective（选择器a[nz-tab-link]）：真正用来"截获"宿主元素上的routerLink指令实例，源码中以inject(RouterLink, { self: true, optional: true })方式注入，并暴露elementRef供组件判断点击是否落在链接上。

nz-tab组件内部通过@ContentChild(NzTabLinkDirective)拿到linkDirective（见 tab.component.ts），Tabs 容器再收集所有子级NzTabLinkDirective形成tabLinks查询列表（见 tabs.component.ts），从而将"每个 tab"与"该 tab 的 routerLink"一一对应。

完整示例：静态 + 动态 tab 的路由联动

官方演示 link-router.ts 同时覆盖了静态 tab 与动态新增 tab 两种场景，是所有路由联动用法的标准模板。要点是：通过 query 参数（而非路径段）区分 tab，并配合queryParamsHandling="merge"保留其它已有参数。

import { Component, signal } from '@angular/core'; import { Params, RouterLink } from '@angular/router'; import { NzButtonModule } from 'ng-zorro-antd/button'; import { NzTabsModule } from 'ng-zorro-antd/tabs'; @Component({ selector: 'nz-demo-tabs-link-router', imports: [RouterLink, NzTabsModule, NzButtonModule], template: ` <div style="margin-block-end: 16px;"> <button nz-button (click)="newTab()">ADD</button> </div> <nz-tabs nzLinkRouter> <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="['.']" [queryParams]="{ tab: 'one' }" queryParamsHandling="merge"> Default </a> Default. </nz-tab> <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="['.']" [queryParams]="{ tab: 'two' }" queryParamsHandling="merge"> Two </a> Two. </nz-tab> <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="['.']" [queryParams]="{ tab: 'three' }" queryParamsHandling="merge"> Three </a> Three. </nz-tab> <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="['.']" [queryParams]="{ tab: 'four' }" queryParamsHandling="merge"> Four </a> Four. </nz-tab> @for (tab of dynamicTabs(); track tab.title) { <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="tab.routerLink" [queryParams]="tab.queryParams ?? {}" queryParamsHandling="merge" > {{ tab.title }} </a> {{ tab.content }} </nz-tab> } </nz-tabs> ` }) export class NzDemoTabsLinkRouterComponent { readonly dynamicTabs = signal<Array<{ title: string; content: string; queryParams?: Params; routerLink: string[] }>>( [] ); newTab(): void { const { length } = this.dynamicTabs(); const newTabId = length + 1; const title = `NewTab${newTabId}`; this.dynamicTabs.update(dynamicTabs => [ ...dynamicTabs, { title, content: title, routerLink: ['.'], queryParams: { tab: newTabId } } ]); } }

逐项拆解这个示例的实操要点：

• nz-tabs nzLinkRouter：只此一个属性即可激活全部联动逻辑，无需手动订阅路由事件；
• [routerLink]="['.']"：所有 tab 都指向当前路由本身，靠[queryParams]="{ tab: 'one' }"等不同参数区分身份，页面刷新后 URL 中的?tab=one能精确还原选中状态；
• queryParamsHandling="merge"：切换 tab 时把新的tab参数合并进现有 query 参数，而不是整体覆盖，避免丢失其它业务参数；
• 动态 tab：通过@for渲染的 tab 同样可以绑定routerLink与queryParams，演示了"新增一个 tab → 自动获得一个可路由、可直达的 URL"的能力；
• track tab.title：动态列表以 title 为 key 追踪，配合signal驱动更新，这是 ng-zorro-antd 当前版本（基于 Angular 新控制流与 signal API）的推荐写法。

如果不需要动态能力，最小可用模板（同样出自 Tabs API 文档）只有下面几行：

<nz-tabs nzLinkRouter> <nz-tab> <a *nzTabLink nz-tab-link [routerLink]="['.']">Link</a> Default. </nz-tab> </nz-tabs>

源码级原理：点击与回跳的双向闭环

路由联动并非魔法，其完整实现集中在 tabs.component.ts 的几段代码里，可以拆成"点击方向"与"路由方向"两个闭环。

点击 tab → 更新路由

在clickNavItem中，组件先判断点击事件的目标元素是否位于该 tab 的a[nz-tab-link]内部：

private isRouterLinkClickEvent(index: number, event: MouseEvent): boolean { const target = event.target as HTMLElement; if (this.nzLinkRouter) { return !!this.tabs.toArray()[index]?.linkDirective?.elementRef.nativeElement.contains(target); } else { return false; } }

若命中链接区域，则不再调用setSelectedIndex手动切 tab，而是把控制权完全交给<a>上的 AngularrouterLink：由路由器完成导航，URL 更新后组件再根据新 URL 反向选中 tab（见下一节）。这保证了"URL 是唯一事实来源"，不会出现 tab 选中态与地址栏不一致的窗口期。

路由变化 → 自动切换 tab

初始化时ngAfterContentInit会调用setUpRouter：

private setUpRouter(): void { if (this.nzLinkRouter) { if (!this.router) { throw new Error(`${PREFIX} you should import 'RouterModule' if you want to use 'nzLinkRouter'!`); } merge(this.router.events.pipe(filter(e => e instanceof NavigationEnd)), this.tabLinks.changes) .pipe(startWith(true), delay(0), takeUntilDestroyed(this.destroyRef)) .subscribe(() => this.updateRouterActive()); } }

这里有两个关键细节：

1. 前置条件：nzLinkRouter依赖Router，源码以inject(Router, { optional: true })注入（见 tabs.component.ts），若未导入RouterModule会直接抛出"you should import 'RouterModule' if you want to use 'nzLinkRouter'!"的错误提示；
2. 触发源：同时订阅NavigationEnd（导航完成事件）与tabLinks.changes（tab 链接增删），并配合startWith(true)在首次变更检测后立即执行一次匹配，保证初始化时 URL 已存在也能正确选中。

导航结束后updateRouterActive会找出与当前 URL 匹配的 tab 索引：

private findShouldActiveTabIndex(): number { const tabs = this.tabs.toArray(); const isActive = this.isLinkActive(this.router); return tabs.findIndex(tab => { const c = tab.linkDirective; return c ? isActive(c.routerLink) : false; }); }

匹配规则由isLinkActive定义，也是nzLinkExact发挥作用的地方：

return router.isActive(link.urlTree || '', { paths: this.nzLinkExact ? 'exact' : 'subset', queryParams: this.nzLinkExact ? 'exact' : 'subset', fragment: 'ignored', matrixParams: 'ignored' });

• nzLinkExact = true（默认）时，路径与 query 参数都按exact精确匹配，适合"每个 tab 独占一组参数"的用法；
• nzLinkExact = false时降级为subset子集匹配，适合"URL 中有多个参数、只要 tab 相关参数匹配即算命中"的场景。

此外，若没有任何 tab 与当前 URL 匹配，updateRouterActive会把索引置为-1并同步nzHideAll，表现为"路由不匹配时隐藏所有 tab 内容"，避免出现无意义的空白选中态。

测试用例佐证：两种典型联动形态

仓库的 tabs.component.spec.ts 用两个测试组件直接验证了上述行为：

• RouterTabsTestComponent（见 tabs.component.spec.ts）：静态写法，nz-tabs nzLinkRouter搭配(nzSelectedIndexChange)回调，tab 链接使用['.']与['.', 'two']这样的路径路由，配合<router-outlet />验证点击链接后选中态与路由同步；
• DynamicRouterTabsTestComponent（见 tabs.component.spec.ts）：动态写法，@for渲染 tab，并显式设置[nzLinkExact]="false"验证子集匹配模式下的路由切换，同时验证"新增路由后自动参与匹配"的能力。

这些测试还体现了路由联动与常规 tab 切换的兼容性：测试组件同时保留(nzSelectedIndexChange)事件绑定与[(nzSelectedIndex)]双向绑定，说明路由模式下你仍然可以监听选中变化或受控管理选中索引。

使用建议与注意事项

1. 务必先导入RouterModule：nzLinkRouter需要注入Router，缺少时组件会抛出明确错误，见 tabs.component.ts；
2. 选择 query 参数还是路径段：示例采用 query 参数 +queryParamsHandling="merge"，适合"同一页面内多 tab"的典型场景；若 tab 对应独立路由页面，可直接像测试用例那样使用[routerLink]="['.', 'two']"路径路由；
3. 匹配模式按需调整：默认nzLinkExact为严格匹配；当 URL 存在多个与 tab 无关的参数时，设置为false（子集匹配）可避免因多余参数变化导致 tab 切换失效；
4. 动态 tab 同样支持：@for新增的 tab 只要绑定*nzTabLink+nz-tab-link+routerLink即可自动纳入路由匹配，tabLinks.changes订阅保证了新增/删除后的重新匹配；
5. 与nzCanDeactivate的关系：若同时配置了守卫函数，点击路由链接触发导航时仍会经过路由守卫流程，可以在导航前拦截切换（详见 Tabs API 文档 中的nzCanDeactivate参数）。

掌握这套"URL 驱动 tab"的写法后，你的标签页就能天然获得可收藏、可分享、可前进后退的地址栏体验，这也是路由联动示例存在的根本价值——把组件内部状态提升为应用级导航状态。

• UI组件
• 前端