企业官网建设流程全解析

• UI组件
• 前端

本文讲解 ng-zorro-antd 中 Empty（空状态）组件的内置图片切换机制：当页面或列表暂无数据时，如何通过nzNotFoundImage属性把默认的插画风格替换为更紧凑的simple风格。读完本文，你将掌握nzNotFoundImage的全部取值与类型（内置关键字、自定义图片地址、TemplateRef 模板），理解simple与default两套内置 SVG 的源码实现差异，并能结合nzNotFoundContent、nzNotFoundFooter与全局NZ_CONFIG配置出贴合业务场景的空状态方案。

一、demo 演示：一行代码切换为 simple 风格

在官方文档的演示用例中，"选择图片 / Chose image" 这一示例（见 components/empty/demo/simple.md）给出了最简单的用法：通过设置nzNotFoundImage为simple，即可选择另一种风格的图片。其配套的 TypeScript 实现（components/empty/demo/simple.ts）如下：

import { Component } from '@angular/core'; import { NzEmptyModule } from 'ng-zorro-antd/empty'; @Component({ selector: 'nz-demo-empty-simple', imports: [NzEmptyModule], template: `<nz-empty nzNotFoundImage="simple" />` }) export class NzDemoEmptySimpleComponent {}

核心就一句话：在<nz-empty>组件上绑定nzNotFoundImage="simple"。模板中不需要引入任何额外的 SVG 或样式文件，因为两套内置图片都以组件形式打包在NzEmptyModule中，开箱即用。

二、simple与default：两套内置图片的源码实现

nz-empty组件（components/empty/empty.component.ts）在内部维护了一个内置图片关键字表：

const NzEmptyDefaultImages = ['default', 'simple'] as const; type NzEmptyNotFoundImageType = (typeof NzEmptyDefaultImages)[number] | null | string | TemplateRef<void>;

即nzNotFoundImage的完整取值域为：'default' | 'simple' | null | string | TemplateRef<void>，其中string表示自定义图片地址，TemplateRef<void>表示模板。默认值为'default'。

组件模板中通过isImageBuildIn标志决定渲染分支（见 components/empty/empty.component.ts）：

<div class="ant-empty-image"> @if (!isImageBuildIn) { <ng-container *nzStringTemplateOutlet="nzNotFoundImage"> <img [src]="nzNotFoundImage" [alt]="isContentString ? nzNotFoundContent : 'empty'" /> </ng-container> } @else { @if (nzNotFoundImage === 'simple') { <nz-empty-simple /> } @else { <nz-empty-default /> } } </div>

该分支由ngOnChanges中检测nzNotFoundImage的变化来驱动（components/empty/empty.component.ts）：

if (nzNotFoundImage) { const image = nzNotFoundImage.currentValue || 'default'; this.isImageBuildIn = NzEmptyDefaultImages.findIndex(i => i === image) > -1; }

当传入的字符串命中default/simple两个关键字时，判定为内置图片；否则视为自定义图片地址，走<img>分支渲染。

2.1 simple 风格 SVG

simple风格由NzEmptySimpleComponent提供（components/empty/partial/simple.ts），是一个 64×41 的紧凑插画：下方一条椭圆投影，上方一个信封/盒子造型的主体。关键结构如下：

<svg class="ant-empty-img-simple" width="64" height="41" viewBox="0 0 64 41" xmlns="http://www.w3.org/2000/svg"> <g transform="translate(0 1)" fill="none" fill-rule="evenodd"> <ellipse class="ant-empty-img-simple-ellipse" cx="32" cy="33" rx="32" ry="7" /> <g class="ant-empty-img-simple-g" fill-rule="nonzero"> <path d="M55 12.76L44.854 1.258C44.367.474 43.656 0 42.907 0H21.093c-.749 0-1.46.474-1.947 1.257L9 12.761V22h46v-9.24z" /> <path class="ant-empty-img-simple-path" d="M41.613 15.931c0-1.605.994-2.93 2.227-2.931H55v18.137..." /> </g> </g> </svg>

样式类ant-empty-img-simple、ant-empty-img-simple-ellipse、ant-empty-img-simple-g、ant-empty-img-simple-path对应的配色与描边规则定义在 components/empty/style/index.less 中，因此simple图片的颜色会跟随主题（默认、暗色、紧凑等）自动变化。

2.2 default 风格 SVG

与之相对，默认风格NzEmptyDefaultComponent（components/empty/partial/default.ts）是一张 184×152 的插画：包含盒子主体、右上角的纸飞机以及底部的阴影，图形复杂度明显高于simple，适合页面级的大面积空状态：

<svg class="ant-empty-img-default" width="184" height="152" viewBox="0 0 184 152" xmlns="http://www.w3.org/2000/svg"> <!-- 盒子、纸飞机与阴影的 path / ellipse 定义 --> </svg>

两者由 components/empty/public-api.ts 一并导出，组件内部在NzEmptyComponent的imports中同时引入NzEmptyDefaultComponent与NzEmptySimpleComponent，根据关键字按需渲染。

三、nzNotFoundImage的更多用法

3.1 自定义图片地址

当传入的字符串不是default/simple时，会被当作图片 URL 渲染为<img>，例如官方 customize 演示（components/empty/demo/customize.ts）：

<nz-empty nzNotFoundImage="https://gw.alipayobjects.com/zos/antfincdn/ZHrcdLPrvN/empty.svg" [nzNotFoundContent]="contentTpl" [nzNotFoundFooter]="footerTpl" > <ng-template #contentTpl> <span>Customize <a href="#API">Description</a></span> </ng-template> <ng-template #footerTpl> <button nz-button nzType="primary" (click)="onClick()">Create Now</button> </ng-template> </nz-empty>

这里同时演示了nzNotFoundContent（自定义描述内容）与nzNotFoundFooter（自定义操作区）的模板用法，可用于在空状态里加入"创建数据"之类的引导按钮。

3.2 传入 TemplateRef

nzNotFoundImage也支持TemplateRef<void>，适用于需要完全自定义图片区域（例如插入动画或复杂排版）的场景。NzEmptyComponent使用nzStringTemplateOutlet指令（来自ng-zorro-antd/core/outlet）统一处理字符串与模板两种形态。

四、API 汇总

nz-empty组件（见 components/empty/doc/index.zh-CN.md 的 API 章节）的核心输入属性如下：

其中描述文案支持 i18n：组件在ngOnInit中订阅NzI18nService.localeChange，读取语言包中的Empty.description作为默认描述（见 components/empty/empty.component.ts），因此无需手动传描述也会随全局语言切换。

五、simple 风格在内嵌空状态中的应用

除独立使用外，simple图片还被 ng-zorro-antd 的"内嵌空状态"机制大量复用：NzEmbedEmptyComponent（components/empty/embed-empty.component.ts）会根据宿主组件名自动适配尺寸，并优先选用simple风格：

@switch (size) { @case ('normal') { <nz-empty class="ant-empty-normal" nzNotFoundImage="simple" /> } @case ('small') { <nz-empty class="ant-empty-small" nzNotFoundImage="simple" /> } @default { <nz-empty /> } }

尺寸映射逻辑getEmptySize定义在同一文件中：

function getEmptySize(componentName: string): NzEmptySize { switch (componentName) { case 'table': case 'list': return 'normal'; case 'select': case 'tree-select': case 'cascader': case 'transfer': return 'small'; default: return ''; } }

也就是说，Table、List 使用normal尺寸的 simple 图片，Select、TreeSelect、Cascader、Transfer 等下拉类组件使用small尺寸的 simple 图片，其余场景使用默认的default插画。这正是simple风格"紧凑、轻量"定位的体现，也是官方在各类数据组件空状态中统一采用的视觉方案。

六、全局统一配置自定义空组件

如果希望全局替换所有组件的空状态内容，可通过NZ_CONFIG提供empty.nzDefaultEmptyContent（类型为Type<any> | TemplateRef<string> | string | undefined）：

{ provide: NZ_CONFIG, useValue: { empty: { nzDefaultEmptyContent } } }

当配置了全局自定义空组件后，NzEmbedEmptyComponent会优先渲染自定义内容，只有未配置时才回退到内置的 simple/default 图片。若想取消自定义、恢复内置图片，把nzDefaultEmptyContent置为undefined即可。此外，NZ_EMPTY_COMPONENT_NAME这个 InjectionToken（定义于 components/empty/config.ts）会把宿主组件名（如table、select）注入到自定义空组件中，便于自定义组件按场景差异化渲染。

七、小结

• 切换内置图片风格只需一行：<nz-empty nzNotFoundImage="simple" />；
• 内置关键字仅default与simple两个，分别对应 184×152 的插画与 64×41 的紧凑图形，SVG 实现见 components/empty/partial/default.ts 与 components/empty/partial/simple.ts；
• 非关键字字符串会被当作图片地址渲染为<img>，也支持传入TemplateRef<void>完全自定义图片区域；
• Table、List、Select、Cascader 等组件的内嵌空状态默认使用simple风格，由 components/empty/embed-empty.component.ts 统一编排；
• 需要全局定制时，通过NZ_CONFIG的empty.nzDefaultEmptyContent配置自定义空组件。

• UI组件
• 前端