ng-zorro-antd PageHeader 组件完全指南：API 配置、区块用法与源码实现解析

• UI组件
• 前端

本指南以 ng-zorro-antd 官方文档（components/page-header/doc/index.en-US.md）为骨架，围绕nz-page-header组件的设计用途、完整 API 参数、七大内容区块（sections）的用法展开，并结合仓库内组件源码（page-header.component.ts）、指令定义（page-header-cells.ts）、示例代码（demo）与单元测试（page-header.spec.ts），讲清每个参数的底层行为与实战写法。读完本文，你将能够：独立搭建从简单标题到含面包屑、头像、标签、操作区、内容区与页脚的完整页头；掌握返回按钮的三种触发机制与幽灵（ghost）背景模式；并理解组件在窄屏下的自动紧凑化原理。

一、什么时候使用 PageHeader（When To Use）

PageHeader 组件的定位是「页面的头等舱」：它用于突出当前页面的主题、展示与页面相关的重要信息，并承载与当前页面相关的操作项——包括页面级操作（如刷新、导出、编辑）以及页面间的导航。

在 ng-zorro-antd 中，nz-page-header是典型的内容型容器组件：它本身不产生数据逻辑，而是通过内置的区块插槽（projection）将标题、副标题、面包屑、头像、标签、操作区、内容区、页脚按固定布局组织起来，让开发者在不关心视觉排版细节的前提下快速产出符合 Ant Design 规范的页面头部。

典型应用场景包括：

• 列表页 / 详情页顶部，展示实体名称与状态标签；
• 页面级操作按钮的收纳（如「新建」「导出」「更多」下拉菜单）；
• 与面包屑组合，表达页面在站点层级中的位置；
• 与nz-tabs组合，在页头下方直接承载详情/规则等子视图切换。

二、最小可用示例与模块引入

nz-page-header由NzPageHeaderModule提供，组件 selector 为nz-page-header，实例名（exportAs）为nzPageHeader，官方文档给出的最小用法如下：

<nz-page-header nzTitle="Page Title"></nz-page-header>

对应到仓库中的标准样式示例（demo/basic.ts），一个带返回按钮、标题和副标题的完整写法是：

import { Component } from '@angular/core'; import { NzPageHeaderModule } from 'ng-zorro-antd/page-header'; @Component({ selector: 'nz-demo-page-header-basic', imports: [NzPageHeaderModule], template: ` <nz-page-header (nzBack)="onBack()" nzBackIcon nzTitle="Title" nzSubtitle="This is a subtitle" /> ` }) export class NzDemoPageHeaderBasicComponent { onBack(): void { console.log('onBack'); } }

组件底层渲染出的 DOM 结构（参见 page-header.component.ts 的模板）大致为：

<nz-page-header class="ant-page-header"> <!-- 面包屑 --> <nz-breadcrumb nz-page-header-breadcrumb>...</nz-breadcrumb> <div class="ant-page-header-heading"> <div class="ant-page-header-heading-left"> <div class="ant-page-header-back">...</div> <!-- 返回按钮 --> <nz-avatar nz-page-header-avatar>...</nz-avatar> <!-- 头像 --> <span class="ant-page-header-heading-title">...</span> <!-- 标题 --> <span class="ant-page-header-heading-sub-title">...</span> <!-- 副标题 --> <nz-page-header-tags>...</nz-page-header-tags> <!-- 标签 --> </div> <nz-page-header-extra>...</nz-page-header-extra> <!-- 操作区 --> </div> <nz-page-header-content>...</nz-page-header-content> <!-- 内容区 --> <nz-page-header-footer>...</nz-page-header-footer> <!-- 页脚 --> </nz-page-header>

组件宿主（host）上会自动根据内容附加语义化 class（page-header.component.ts）：

• has-footer：存在页脚区块时；
• has-breadcrumb：存在面包屑区块时；
• ant-page-header-ghost：启用幽灵模式时；
• ant-page-header-compact：窄屏（宽度 < 768px）紧凑模式时；
• ant-page-header-rtl：当前应用为 RTL 方向时。

这些 class 被 style/index.less 等样式文件消费，无需手工维护。

三、nz-page-header 完整 API 参数详解

官方文档（index.en-US.md）给出的 API 表格是理解组件行为的核心，下面逐条展开并结合源码说明其底层实现。

3.1nzGhost：幽灵模式（支持全局配置）

nzGhost控制页头背景是否透明，默认值为true（幽灵模式，即不渲染背景色，适合页面本身有背景的场景）。设为false时组件会获得ant-page-header-ghostclass 之外的常规背景样式。

源码中使用@WithConfig()装饰器声明（page-header.component.ts），并通过_nzModuleName = 'pageHeader'（page-header.component.ts）接入 ng-zorro-antd 的全局配置体系。因此你可以在应用全局配置中统一覆盖其默认值：

import { provideNzConfig, NZ_CONFIG } from 'ng-zorro-antd/core/config'; export const appConfig = { providers: [ provideNzConfig({ pageHeader: { nzGhost: false } // 全局关闭幽灵模式 }) ] };

示例 demo/ghost.ts 展示了[nzGhost]="false"的写法，对应的测试用例 page-header.spec.ts 验证了nzGhost=false时宿主 class 中不再包含ant-page-header-ghost。

3.2nzTitle/nzSubtitle：标题与副标题

两者的类型均为string | TemplateRef<void>，即既可以传纯字符串，也可以传入模板引用实现富内容标题。实现上通过nzStringTemplateOutlet结构指令统一渲染（page-header.component.ts）：

@if (nzTitle) { <span class="ant-page-header-heading-title"> <ng-container *nzStringTemplateOutlet="nzTitle">{{ nzTitle }}</ng-container> </span> } @else { <ng-content select="nz-page-header-title, [nz-page-header-title]" /> }

一个关键的设计取舍是优先级：当nzTitle/nzSubtitle作为输入属性提供时，它们优先于同名的内容区块（nz-page-header-title/nz-page-header-subtitle）。只有输入属性未赋值时，投影区块才会生效。这与官方文档「nz-page-header-subtitle区块中[nzTitle]优先级更高」的说明一致——标题区块同理。

3.3nzBackIcon：自定义返回图标

类型为string | TemplateRef<void>，默认null。它决定返回按钮中图标的渲染方式：

• 传入字符串：作为nz-icon的nzType使用；
• 传入模板：整体替换图标区域内容。

<!-- 字符串图标 --> <nz-page-header nzBackIcon nzBackIcon="menu-fold" nzTitle="Title" /> <!-- 模板图标 --> <ng-template #customBack> <span>← 返回</span> </ng-template> <nz-page-header nzBackIcon [nzBackIcon]="customBack" nzTitle="Title" />

源码在渲染时使用了backIcon || getBackIcon()的回退逻辑（page-header.component.ts）：若未提供nzBackIcon，则调用getBackIcon()（page-header.component.ts）返回默认图标——LTR 方向为arrow-left，RTL 方向为arrow-right，由Directionality服务驱动。测试用例也验证了默认渲染的是.anticon-arrow-left（page-header.spec.ts）。

另外需要注意：nzBackIcon置为null时（默认值），若当前没有返回需求（如nzBack未被订阅且浏览器无导航历史），整个返回按钮区域都不会渲染（nzBackIcon !== null && enableBackButton双重条件，见 page-header.component.ts）。

3.4(nzBack)：返回事件与默认行为

(nzBack)是返回按钮的点击事件，类型为EventEmitter<void>。它的行为非常智能：当事件未被订阅时，组件会调用 Angular 的Location#back()执行浏览器历史回退；一旦你订阅了该事件，点击就只触发你的回调，不再执行默认回退。

官方文档补充了前提：使用默认回退行为时，你需要导入RouterModule或注册Location（Location来自@angular/common，在应用配置的providers中提供），否则Location无法注入。

源码中完整实现了三种状态下的返回按钮逻辑（page-header.component.ts）：

1. nzBack已被订阅：始终显示返回按钮，点击后this.nzBack.emit()；
2. nzBack未订阅、但有导航历史（location.getState().navigationId > 1）：显示返回按钮，点击后this.location.back()；
3. nzBack未订阅、且没有导航历史（首次进入页面，navigationId <= 1）：不显示返回按钮，避免出现「无处可退」的死按钮。

这里最值得注意的底层细节是：enableBackButton的初始值取决于navigationId，并且在ngAfterViewInit中订阅了location.subscribe()——一旦发生任何 URL 变化，enableBackButton会被置为true（说明此后浏览器一定存在可回退的历史）。这些行为均有测试覆盖（page-header.spec.ts）：无导航历史时不渲染.ant-page-header-back-button，有历史时渲染，点击后触发location.back()。

// 订阅 nzBack，接管返回行为（来自 demo/basic.ts） onBack(): void { console.log('onBack'); }

四、Page Header 七大内容区块（Sections）

除了输入属性，nz-page-header的灵活性更多体现在投影区块上。官方文档将其归纳为下表，全部由 page-header-cells.ts 中的指令定义（每个指令同时支持元素标签与属性两种写法）：

每条指令（除面包屑外）都在宿主上挂载对应 class，样式由 style/index.less 统一实现。下面逐个给出实战组合。

4.1 面包屑：nz-breadcrumb[nz-page-header-breadcrumb]

面包屑必须是nz-breadcrumb元素并带有nz-page-header-breadcrumb属性。示例（demo/breadcrumb.ts）：

<nz-page-header nzTitle="Title" nzSubtitle="This is a subtitle"> <nz-breadcrumb nz-page-header-breadcrumb> <nz-breadcrumb-item>First-level Menu</nz-breadcrumb-item> <nz-breadcrumb-item> <a>Second-level Menu</a> </nz-breadcrumb-item> <nz-breadcrumb-item>Third-level Menu</nz-breadcrumb-item> </nz-breadcrumb> </nz-page-header>

面包屑由NzPageHeaderBreadcrumbDirective标记，通过@ContentChild查询到后，组件会为宿主追加has-breadcrumbclass（page-header.component.ts），样式层据此调整标题区的内边距。测试断言has-breadcrumb与nz-breadcrumb[nz-page-header-breadcrumb]的存在（page-header.spec.ts）。

4.2 头像：nz-avatar[nz-page-header-avatar]

头像区渲染在返回按钮之后、标题之前，直接复用nz-avatar组件，只需附加nz-page-header-avatar属性：

<nz-avatar nz-page-header-avatar nzSrc="https://avatars0.githubusercontent.com/u/22736418?s=88&v=4" />

4.3 标题 / 副标题区块

当不使用输入属性nzTitle/nzSubtitle时，可以用区块元素承载更复杂的结构（例如带图标或徽标的标题）：

<nz-page-header> <nz-page-header-title>Title</nz-page-header-title> <nz-page-header-subtitle>This is a subtitle</nz-page-header-subtitle> </nz-page-header>

再次强调：输入属性与区块同时存在时，输入属性优先（@if (nzTitle)分支优先渲染输入值）。

4.4 标签：nz-page-header-tags

标签容器紧跟副标题之后，通常与nz-tag搭配展示状态信息：

<nz-page-header-tags> <nz-tag nzColor="blue">Running</nz-tag> </nz-page-header-tags>

4.5 操作区：nz-page-header-extra

操作区位于标题行（heading）的最右端，是收纳页面级操作按钮的标准位置。结合nz-space可以轻松实现按钮间距与对齐（见 demo/actions.ts）：

<nz-page-header-extra> <nz-space> <button *nzSpaceItem nz-button>Operation</button> <button *nzSpaceItem nz-button nzType="primary">Primary</button> </nz-space> </nz-page-header-extra>

4.6 内容区：nz-page-header-content

内容区位于标题行之下、页脚之上，适合放置描述列表（nz-descriptions）、统计指标（nz-statistic）等「帮助用户快速了解页面信息」的内容。官方示例（demo/actions.ts）中将其与nz-statistic组合展示订单信息：

<nz-page-header-content> <nz-row> <nz-statistic nzTitle="Status" nzValue="Pending" /> <nz-statistic nzTitle="Price" [nzValue]="568.08" nzPrefix="$" style="margin: 0 32px" /> <nz-statistic nzTitle="Balance" [nzValue]="3345.08" nzPrefix="$" /> </nz-row> </nz-page-header-content>

更复杂的形态可参考 demo/content.ts：内容区左侧放说明文字（nz-paragraph）、右侧放插图，并通过@media (max-width: 768px)让图片在窄屏下自动换行到下方。

4.7 页脚：nz-page-header-footer

页脚是最后一个区块，常用于承载nz-tabs，实现「页头 + 标签页」的一体化布局（见 demo/responsive.ts）：

<nz-page-header-footer> <nz-tabs [nzSelectedIndex]="1"> <nz-tab nzTitle="Details" /> <nz-tab nzTitle="Rule" /> </nz-tabs> </nz-page-header-footer>

页脚区块存在时组件自动获得has-footerclass，测试用例对此有专门断言（page-header.spec.ts）。

五、完整综合示例：信息密集型页头

将上述区块全部组合，可得到官方 demo/content.ts 呈现的「全要素」页头，结构如下：

<nz-page-header> <!--breadcrumb--> <nz-breadcrumb nz-page-header-breadcrumb>...</nz-breadcrumb> <!--avatar--> <nz-avatar nz-page-header-avatar nzSrc="..." /> <!--title / subtitle--> <nz-page-header-title>Title</nz-page-header-title> <nz-page-header-subtitle>This is a subtitle</nz-page-header-subtitle> <!--tags--> <nz-page-header-tags> <nz-tag nzColor="blue">Running</nz-tag> </nz-page-header-tags> <!--extra：普通按钮 + 更多下拉--> <nz-page-header-extra> <nz-space> <button *nzSpaceItem nz-button>Operation</button> <button *nzSpaceItem nz-button nzType="primary">Primary</button> <button *nzSpaceItem nz-button nz-dropdown [nzDropdownMenu]="menu" nzNoAnimation ...> <nz-icon nzType="more" nzTheme="outline" /> </button> </nz-space> <nz-dropdown-menu #menu="nzDropdownMenu"> <ul nz-menu> <li nz-menu-item>1st menu item length</li> <li nz-menu-item>2nd menu item length</li> <li nz-menu-item>3rd menu item length</li> </ul> </nz-dropdown-menu> </nz-page-header-extra> <!--content--> <nz-page-header-content> <div nz-row> <div class="content"> <p nz-paragraph>...</p> </div> <div class="content-image"> <img src="..." alt="content" /> </div> </div> </nz-page-header-content> </nz-page-header>

该示例同时引入了NzAvatarModule、NzBreadCrumbModule、NzButtonModule、NzDropdownModule、NzGridModule、NzIconModule、NzSpaceModule、NzTagModule、NzTypographyModule等模块，展示了页头与其他 ng-zorro-antd 组件的高组合性。

六、响应式与自动紧凑化：源码层面的实现

官方文档与示例强调「在不同大小的屏幕下，PageHeader 应有不同的表现」（见 demo/responsive.md）。这分两层实现：

第一层：组件内置的自动紧凑化。在 page-header.component.ts 中，组件通过NzResizeObserver（来自ng-zorro-antd/cdk/resize-observer）持续观测自身宽度，当宽度小于 768px时把compact置为true，从而为宿主添加ant-page-header-compactclass（page-header.component.ts），样式层会收紧标题字号、内边距等间距。这一逻辑对使用者完全透明，无需编写任何媒体查询。

第二层：业务内容的响应式布局。页头内部投影的业务内容（描述列表、统计、插图等）需要开发者自行通过 CSS 媒体查询配合。官方示例的做法是：

@media (max-width: 576px) { .content { display: block; } .main { width: 100%; margin-bottom: 12px; } .extra { width: 100%; } }

即在小屏下将并排的「信息 + 统计」改为上下堆叠（见 demo/responsive.ts）。示例 demo/content.ts 中插图区同样在 768px 以下改为独占一行（flex: 100%）。

七、RTL 支持与测试保障

ng-zorro-antd 对 RTL（从右到左）布局有系统级支持，PageHeader 也完整继承：Directionality的valueSignal被绑定到宿主的ant-page-header-rtlclass（page-header.component.ts），默认返回图标在 RTL 下自动变为arrow-right（page-header.component.ts）。

组件行为由 page-header.spec.ts 提供约 14 组测试覆盖，包括：

• 基础渲染：ant-page-header、ant-page-header-ghost与标题/副标题元素存在；
• 幽灵模式开关：nzGhost=false时不含 ghost class；
• 面包屑、内容区、操作区、标签、页脚、头像各区块的渲染；
• 返回按钮的三种状态（无历史不渲染、有历史渲染、点击触发location.back）；
• nzBack订阅后点击触发自定义回调；
• 默认图标为arrow-left，RTL 方向（通过testDirectionality工具）下布局正确切换。

这些测试既是行为契约，也是二次开发或迁移时验证兼容性的参照。

八、总结与最佳实践

从 index.en-US.md 的 API 与 page-header.component.ts 的实现可以看出，nz-page-header的设计遵循「输入属性提供快捷路径、投影区块提供完整定制」的双轨模式。实战中的建议：

1. 简单场景（只要标题/副标题）：直接用nzTitle/nzSubtitle输入属性，一行代码即可；
2. 复杂场景（需要标签、操作区、统计、页脚）：全部改用区块元素，结构更清晰、可读性更强，且不会与输入属性冲突（输入属性优先，二者不要混用同一语义区块）；
3. 返回行为：若页面需要「返回上一页」，优先让组件走默认的Location#back()（记得在应用中提供Location或引入RouterModule）；只有需要自定义返回逻辑（如带参数回跳）时才订阅(nzBack)；
4. 主题一致性：幽灵模式的全局默认值可通过全局配置provideNzConfig({ pageHeader: { nzGhost: false } })统一调整，避免逐页重复设置；
5. 响应式：依赖组件内置的 768px 自动紧凑化处理标题区，同时对内容区自定义响应式规则，实现完整的移动端适配。

PageHeader 是一个「布局容器」型组件，掌握其输入属性、区块体系与底层返回按钮逻辑后，即可在各类业务页面中快速搭建规范、一致且响应式的页面头部。

• UI组件
• 前端