ng-zorro-antd Result 组件完全指南：用 nz-result 构建成功、失败与异常状态反馈页-平芜编程栈

UI组件
前端

【免费下载链接】ng-zorro-antd

Angular UI Component Library based on Ant Design

项目地址：https://gitcode.com/gh_mirrors/ng/ng-zorro-antd

本篇指南基于 ng-zorro-antd（Angular UI 组件库）中 Result 组件官方文档展开，系统讲解nz-result的 7 种内置状态、5 个属性（Input）与 5 个内容指令（Counter Parts）的用法，并结合仓库源码（result.component.ts、result-cells.ts）与官方示例深入剖析其渲染原理。阅读完本文，你将能够独立搭建支付成功页、表单提交失败页、404/403/500 异常页以及带自定义图标的个性化结果页。

一、何时使用 Result 组件

按照官方文档的定位，nz-result属于 Feedback（反馈）类组件，用于反馈一系列操作任务的结果。使用场景通常是：

重要操作完成后需要告知用户处理结果，且反馈信息较为复杂（不只是弹一个提示，而是需要展示标题、副标题、说明内容与操作按钮的完整页面）；
表单提交、支付、注册、审核等流程的终态页面；
页面级错误状态展示，如 404 页面未找到、403 无权限、500 服务器错误。

它的默认外观样式位于 components/result/style/index.less，与其他 ng-zorro-antd 组件一样支持主题变量定制。

二、快速上手：模块导入与第一个成功页

使用前需要导入NzResultModule，该模块在 result.module.ts 中定义，并从 public-api.ts 对外导出。

import { NgModule } from '@angular/core'; import { NzResultModule } from 'ng-zorro-antd/result'; @NgModule({ imports: [NzResultModule] }) export class YourFeatureModule {}

参照官方示例 success.ts，一个最典型的下单成功页可以这样写：

import { Component } from '@angular/core'; import { NzButtonModule } from 'ng-zorro-antd/button'; import { NzResultModule } from 'ng-zorro-antd/result'; @Component({ selector: 'app-purchase-success', imports: [NzButtonModule, NzResultModule], template: ` <nz-result nzStatus="success" nzTitle="Successfully Purchased Cloud Server ECS!" nzSubTitle="Order number: 2017182818828182881 Cloud server configuration takes 1-5 minutes, please wait." > <div nz-result-extra> <button nz-button nzType="primary">Go Console</button> <button nz-button>Buy Again</button> </div> </nz-result> ` }) export class AppPurchaseSuccessComponent {}

注意这里nz-button需要额外导入NzButtonModule（来自ng-zorro-antd/button）。nz-result-extra是操作区指令，里面可以放任意操作按钮。通过nzStatus="success"，组件会自动渲染一个check-circle实心图标、绿色标题与整体成功态配色，无需手动传图标。

三、API 详解：nz-result 的五个属性

官方文档定义了nz-result的完整属性表，如下：

Property	Description	Type	Default
`nzTitle`	title	`TemplateRef<void> \\| string`	-
`nzSubTitle`	subTitle	`TemplateRef<void> \\| string`	-
`nzStatus`	result status, decides icons and colors	`'success' \\| 'error' \\| 'info' \\| 'warning'\\| '404' \\| '403' \\| '500'`	`'info'`
`nzIcon`	custom icon	`TemplateRef<void> \\| string`	-
`nzExtra`	operating area	`TemplateRef<void> \\| string`	-

在源码 result.component.ts 中，这五个属性全部以 Angular 现代 signal-based 的input()方式声明，与官方文档一一对应：

readonly nzIcon = input<string | TemplateRef<void>>(); readonly nzTitle = input<string | TemplateRef<void>>(); readonly nzSubTitle = input<string | TemplateRef<void>>(); readonly nzExtra = input<string | TemplateRef<void>>(); readonly nzStatus = input<NzResultStatusType>('info');

3.1 nzStatus：七种状态与图标映射

nzStatus决定整个结果页的图标与配色，是组件的核心。其类型定义（result.component.ts）将状态划分为两组：

export type NzResultIconType = 'success' | 'error' | 'info' | 'warning'; export type NzExceptionStatusType = '404' | '500' | '403'; export type NzResultStatusType = NzExceptionStatusType | NzResultIconType;

普通图标状态：success、error、info、warning，对应IconMap（result.component.ts）中四个内置的 fill 主题图标：

const IconMap: Record<NzResultIconType, string> = { success: 'check-circle', error: 'close-circle', info: 'exclamation-circle', warning: 'warning' };

异常页面状态：404、403、500，对应三个内置的内联 SVG 插画组件（源码位于 components/result/partial 目录）：
- 404→ not-found.ts（页面未找到插画，含电脑与放大镜图形）；
- 500→ server-error.component.ts（服务器错误插画，含服务器与"500"字样）；
- 403→ unauthorized.ts（无权限插画，含锁形挂锁图形）。

当nzStatus落入这三种异常状态时，组件通过ExceptionStatus数组与isException计算信号（result.component.ts）识别，并使用@switch渲染对应的插画组件；否则渲染图标。这也是nzIcon、nzStatus取值的边界：异常状态下会忽略自定义图标而强制展示插画。

另外，状态还会影响宿主根元素上的 CSS 类：class计算信号（result.component.ts）会根据nzStatus追加ant-result-${status}类（如ant-result-success、ant-result-error），并支持ant-result-rtl用于 RTL 布局（依赖@angular/cdk/bidi的Directionality）。

3.2 nzTitle / nzSubTitle：标题与副标题

nzTitle、nzSubTitle既可以是纯字符串，也可以是TemplateRef<void>模板引用。当传入模板时，组件通过NzOutletModule提供的*nzStringTemplateOutlet指令渲染模板内容（result.component.ts）。

组件优先渲染属性值；只有属性未提供时，才退化为通过ng-content投影的div[nz-result-title]/div[nz-result-subtitle]内容。官方测试 result.spec.ts 验证了这一"属性优先、投影兜底"的重叠逻辑（props work and overlap contents）。

3.3 nzIcon：自定义图标

nzIcon提供两种自定义途径：

传入图标名（字符串）：会先尝试匹配IconMap中四个语义关键字（success/error/info/warning），匹配不到则直接当作nz-icon的nzType使用。例如官方示例 custom.ts 中的nzIcon="smile-o"会渲染smile-o图标：

<nz-result nzIcon="smile-o" nzTitle="Great, we have done all the operators!"> <div nz-result-extra> <button nz-button nzType="primary">Next</button> </div> </nz-result>

传入TemplateRef<void>：直接渲染自定义模板。

从源码的icon计算信号（result.component.ts）可以看出，该属性在渲染时始终以 fill 主题呈现（nzTheme="fill"），以保证与内置状态图标视觉一致。

3.4 nzExtra：操作区域

nzExtra对应结果页底部的操作区，同样支持字符串与TemplateRef<void>。官方文档将其描述为"operating area"，实践中通常放置"返回首页""重试""去控制台"等按钮，是结果页与用户交互的入口。

四、Counter Parts：五个内容指令

当不想用字符串/模板属性，而是希望直接在组件标签内书写结构化内容时，官方文档提供了以下 5 个指令作为nz-result的子元素使用：

Directive	Description
`[nz-result-icon]`	custom icon
`div[nz-result-title]`	title
`div[nz-result-subtitle]`	subtitle
`div[nz-result-content]`	contents, for detailed explanations
`div[nz-result-extra]`	extra content, usually an operating area

这些指令全部定义在 result-cells.ts 中，各自的宿主类如下：

指令类	选择器	自动挂载的 CSS 类
`NzResultIconDirective`	`[nz-result-icon]`	（无，仅作内容投影标记）
`NzResultTitleDirective`	`div[nz-result-title]`	`ant-result-title`
`NzResultSubtitleDirective`	`div[nz-result-subtitle]`	`ant-result-subtitle`
`NzResultContentDirective`	`div[nz-result-content]`	`ant-result-content`
`NzResultExtraDirective`	`div[nz-result-extra]`	`ant-result-extra`

其中nz-result-icon与nz-result-content在组件模板中通过ng-content的select选择器投影（result.component.ts），使子元素自动落入对应的语义化容器中；其余四个指令则承担"属性缺省时的兜底投影"职责，并自动获得对应 CSS 类以复用内置排版样式。

配合指令写法的一个完整示例（参考官方 success.ts 与测试组件 result.spec.ts）：

<nz-result nzStatus="success" nzTitle="Submission Succeeded"> <nz-icon nz-result-icon nzType="up" nzTheme="outline" /> <div nz-result-title>Content Title</div> <div nz-result-subtitle>Content SubTitle</div> <div nz-result-content>Detailed explanation goes here</div> <div nz-result-extra> <button nz-button nzType="primary">Go Console</button> </div> </nz-result>

提示：nz-result-icon的使用前提是nzStatus处于非异常状态（否则异常插画优先渲染）。该指令还常与NzIconModule的nz-icon搭配使用，可自行指定nzTheme（如outline）。

五、实战示例：错误页与详细说明区

div[nz-result-content]是错误反馈页最有价值的指令，可用于展开出错原因的明细。参照官方 error.ts，一个完整的表单提交失败页可以这样组织：

import { Component } from '@angular/core'; import { NzButtonModule } from 'ng-zorro-antd/button'; import { NzIconModule } from 'ng-zorro-antd/icon'; import { NzResultModule } from 'ng-zorro-antd/result'; import { NzTypographyModule } from 'ng-zorro-antd/typography'; @Component({ selector: 'nz-demo-result-error', imports: [NzButtonModule, NzIconModule, NzResultModule, NzTypographyModule], template: ` <nz-result nzTitle="Submission Failed" nzStatus="error" nzSubTitle="Please check and modify the following information before resubmitting." > <div nz-result-content> <div class="desc"> <h4 nz-title>The content you submitted has the following error:</h4> <p nz-paragraph> <nz-icon nzType="close-circle" /> Your account has been frozen <a>Thaw immediately &gt;</a> </p> <p nz-paragraph> <nz-icon nzType="close-circle" /> Your account is not yet eligible to apply <a>Apply immediately &gt;</a> </p> </div> </div> <div nz-result-extra> <button nz-button nzType="primary">Go Console</button> <button nz-button>Buy Again</button> </div> </nz-result> ` }) export class NzDemoResultErrorComponent {}

上述代码中nz-title、nz-paragraph来自NzTypographyModule，用于排版说明文字；出错原因逐条列出，并附带"立即解冻""立即申请"等行内跳转链接，构成一个信息完整、可操作的表单失败反馈页。这正是官方文档所说"反馈信息比较复杂"时的典型用法。

六、异常状态页（403 / 404 / 500）实战

当业务需要独立异常页时，直接设置nzStatus为对应值即可，无需额外引入任何插画资源——内置 SVG 已由NzResultNotFoundComponent、NzResultServerErrorComponent、NzResultUnauthorizedComponent三个内部组件提供，并且从 public-api.ts 看，这三个组件被包装为ɵ前缀的私有导出，仅服务于 ng-packagr 打包，不会污染用户 API 面。

以 403 无权限页为例（参考官方 fot.ts）：

import { Component } from '@angular/core'; import { NzButtonModule } from 'ng-zorro-antd/button'; import { NzResultModule } from 'ng-zorro-antd/result'; @Component({ selector: 'app-403-page', imports: [NzButtonModule, NzResultModule], template: ` <nz-result nzStatus="403" nzTitle="403" nzSubTitle="Sorry, you are not authorized to access this page."> <div nz-result-extra> <button nz-button nzType="primary">Back Home</button> </div> </nz-result> ` }) export class App403PageComponent {}

同样地，nzStatus="404"配合"页面不存在"文案、nzStatus="500"配合"服务器错误"文案，即可快速产出其余两个异常页。官方 demo 目录（components/result/demo）中提供了fof（404）、fot（403）等对应示例，可以直接对照。仓库还内置了info、warning状态的示例，覆盖全部 7 种状态。

七、源码实现原理：从 Input 到最终渲染

理解渲染链路有助于避免误用。以 result.component.ts 的模板为核心，整个渲染流程可归纳如下：

状态分流：isException()计算信号判断nzStatus是否为404/500/403。是 → 渲染对应插画子组件；否 → 进入图标分支。
图标优先级：非异常状态下，优先渲染nzIcon属性（字符串经IconMap或直接作nzType，模板则直接展开）；nzIcon未提供时，退化为ng-content投影的[nz-result-icon]；两者皆无，才使用按nzStatus从IconMap查出的defaultIcon()。
文本内容兜底：nzTitle、nzSubTitle属性存在时渲染属性内容（支持字符串模板展开），否则投影div[nz-result-title]、div[nz-result-subtitle]。
明细与操作区：nz-result-content无条件投影；nzExtra属性优先、div[nz-result-extra]兜底。

官方测试 result.spec.ts 对上述行为做了完整断言：宿主元素必须携带ant-result与ant-result-error类；属性提供的icon会覆盖状态默认图标（测试中nzIcon传入success时渲染anticon-check-circle）；标题、副标题、额外内容均按预期输出。若你在业务中同时使用了属性与指令，可依据该优先级规则预期最终表现。

八、小结与更多参考

nz-result是 ng-zorro-antd 中构建流程终态页面的标准答案：四个普通状态 + 三个异常状态一键切换，五个属性与五个指令互相配合，覆盖"标题 + 副标题 + 图标 + 明细 + 操作区"的完整结果页结构。建议按以下顺序查阅仓库资料继续深入：

官方英文文档：components/result/doc/index.en-US.md；
组件实现：result.component.ts、result-cells.ts；
内置插画：partial/not-found.ts、partial/server-error.component.ts、partial/unauthorized.ts；
可运行示例：components/result/demo 下的success.ts、error.ts、info.ts、warning.ts、fof.ts、fot.ts、custom.ts；
测试用例：result.spec.ts；
样式源码：components/result/style/index.less。

结合本篇的 API 说明与源码解析，你可以直接照抄示例代码到自己的 Angular 应用中，快速落地一套风格统一、语义明确的结果反馈页。