ng-zorro-antd Empty 全局化配置实战：用 NzConfigService 一处定义所有组件的空状态

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本篇基于 ng-zorro-antd 的empty组件「全局化配置」示例Default Config demo讲解如何通过NzConfigService/NZ_CONFIG一次性为 Select、TreeSelect、Cascader、Transfer、Table、List 等组件设置统一的空状态Empty内容。读完本文你将掌握全局空状态的两种配置方式静态注入与运行时动态设置、三种内容形态string / TemplateRef / 组件类、组件级内容优先于全局配置的覆盖规则以及底层NzEmbedEmptyComponent的实现原理。1. 背景为什么需要「全局化配置」ng-zorro-antd 中多个组件在数据为空时都会展示占位图与提示文案例如空表格、空列表、无选项的下拉框。若逐组件用nzNotFoundContent之类的属性定制重复成本高且风格容易不一致。Empty 模块为此提供了「全局自定义空组件」能力只要在应用配置中声明empty.nzDefaultEmptyContent上述组件的空状态会统一替换为你提供的内容。官方文档doc/index.zh-CN.md对此的描述是你或许知道或者用过一些类似nzNotFoundContent的属性来自定义组件数据为空时的内容现在它们都会使用Empty组件。你可以通过在NZ_CONFIG中提供{ empty: { nzDefaultEmptyContent: something } }来定义一个自定义的全局空组件。对应本文的核心示例文件为 demo/config.md 与 demo/config.ts文档标题即「全局化配置 / Default Config」正文一句话概括了目标自定义全局组件的 Empty 样式。 UseNzEmptyServiceset global Empty style.需要说明的是「NzEmptyService」是早期文档中的叫法。在当前仓库源码中检索不到独立的NzEmptyService实现全局空状态的读写已经收敛到统一的配置服务NzConfigService配合NZ_CONFIG注入器这也是当前版本推荐的写法。2. 官方 Demo 走读一个开关切换全局空状态demo/config.ts 的完整实现如下核心部分import { Component, TemplateRef, ViewChild, effect, inject, signal } from angular/core; import { FormsModule } from angular/forms; import { NzConfigService } from ng-zorro-antd/core/config; import { NzEmptyModule } from ng-zorro-antd/empty; // 其余为各业务组件模块NzSelectModule、NzTableModule、NzListModule 等 Component({ selector: nz-demo-empty-config, imports: [FormsModule, NzSelectModule, NzTableModule, NzListModule, /* … */], template: nz-switch nzUnCheckedChildrendefault nzCheckedChildrencustomize [(ngModel)]customize / nz-divider / h3Select/h3 nz-select stylewidth: 200px / h3TreeSelect/h3 nz-tree-select stylewidth: 200px; / h3Cascader/h3 nz-cascader stylewidth: 200px; [nzShowSearch]true [nzOptions][] / h3Transfer/h3 nz-transfer / h3Table/h3 nz-table [nzData][] theadtrthTitle/ththAge/th/tr/thead tbody/tbody /nz-table h3List/h3 nz-list [nzDataSource][] / ng-template #customTpl let-name div styletext-align: center; nz-icon nzTypesmile stylefont-size: 20px; / pData Not Found in {{ name }}/p /div /ng-template }) export class NzDemoEmptyConfigComponent { private readonly nzConfigService inject(NzConfigService); ViewChild(customTpl, { static: false }) customTpl?: TemplateRefstring; readonly customize signal(false); constructor() { effect(() { const template this.customize() ? this.customTpl : undefined; this.nzConfigService.set(empty, { nzDefaultEmptyContent: template }); }); } }这段代码值得注意的三个点nzConfigService.set(empty, { nzDefaultEmptyContent: template })是唯一的全局配置入口。第一个参数empty对应NzConfigOptions中的empty字段其类型定义在 config.tsexport interface EmptyConfig { nzDefaultEmptyContent?: TypeNzSafeAny | TemplateRefstring | string | undefined; }可见全局空内容支持三种形态组件类Type、模板引用TemplateRef、纯字符串string。effect()绑定信号变化demo 用customize信号驱动——开关打开时传入自定义TemplateRef关闭时传undefined。传undefined即「取消全局自定义」让各组件恢复默认 Empty 占位这与 doc/index.zh-CN.md 中「可通过undefined来取消自定义的全局空组件」的说明一致。模板上下文参数let-name自定义模板中Data Not Found in {{ name }}的name会被注入为「宿主组件名称」如list、table从而在同一个全局模板里区分不同组件。该上下文由NzEmptyCustomContent类型的TemplateRefstring承载见 config.ts。3. 静态配置方式NZ_CONFIG注入器除运行时set外还可以在应用启动时静态声明适用于「整站统一换皮」场景示例来自 doc/index.zh-CN.md{ provide: NZ_CONFIG, useValue: { empty: { nzDefaultEmptyContent // 可以是 string、TemplateRef 或自定义组件类 } } }NZ_CONFIG是 ng-zorro-antd 的全局配置注入器empty只是其中一个键NzConfigOptions.empty定义于 config.ts。单元测试 empty.spec.ts 中的「service injection」用例正是以TestBed.configureTestingModule({ providers: [{ provide: NZ_CONFIG, useValue: { empty: { nzDefaultEmptyContent: NzEmptyTestCustomComponent } } }] })的方式验证了这条路径全局注入一个自定义组件类后nz-list空状态被替换为该组件的渲染结果。4. 底层原理NzEmbedEmptyComponent如何工作各组件Table、List、Select 等内部并不直接渲染nz-empty而是嵌入一个内部组件nz-embed-empty它是全局配置的消费者。阅读 embed-empty.component.ts 可以得到完整的解析链1内容解析优先级。构造函数中订阅了empty键的配置变更事件每次变更都执行this.content this.specificContent || this.getUserDefaultEmptyContent()L91-L96specificContent是宿主组件自身传入的内容例如 List 的nzNoResult优先于全局配置全局配置则从configService.getConfigForComponent(empty)中读取nzDefaultEmptyContentL137-L139。这正是测试用例「should components prop has priority」empty.spec.ts所验证的覆盖规则先设置全局字符串空内容再给 List 绑定nzNoResult最终页面只显示组件级内容。2三种内容形态的渲染分支。renderEmpty()L114-L135按类型分派string/TemplateRef通过*nzStringTemplateOutlet渲染且模板上下文会携带$implicit: this.nzComponentName这就是第 2 节中let-name的由来Type自定义组件动态创建Injector额外提供NZ_EMPTY_COMPONENT_NAMEToken值即宿主组件名再用ComponentPortal挂载该组件。NZ_EMPTY_COMPONENT_NAME的定义见 config.ts其用途在 doc/index.zh-CN.md 中有明确说明「将会被注入到用户的全局自定义空组件中告诉该组件其所在组件的名称」。3尺寸自适应。getEmptySize()L29-L42按宿主组件名决定默认 Empty 尺寸table、list用normalant-empty-normalselect、tree-select、cascader、transfer用smallant-empty-small。这也解释了为什么 demo 里 Table 的空状态图和 Select 的空状态图大小不同。4回退渲染。当既无组件级内容、也无全局配置specificContent为null且content为空时模板回退到内置的nz-empty组件nzNotFoundImagesimple并按上述尺寸加ant-empty-normal/ant-empty-smallclass。5. 公共nz-empty组件的 API 参考全局配置最终影响的是内置nz-empty组件empty.component.ts。在需要单独展示空状态而非依赖宿主组件自动渲染时可以直接使用它其完整参数如下源自 doc/index.zh-CN.md参数说明类型默认值[nzNotFoundImage]设置显示图片为string时表示自定义图片地址string \| TemplateRefvoiddefault[nzNotFoundContent]自定义描述内容string \| TemplateRefvoid \| null-[nzNotFoundFooter]设置自定义 footerstring \| TemplateRefvoid-源码中nzNotFoundImage默认为default内置图片枚举为[default, simple]empty.component.ts#L26-L27传入simple或default时渲染内置 SVG 占位组件nz-empty-simple/nz-empty-default传入其他字符串时视为自定义图片 URL 并以img渲染传入TemplateRef则渲染模板。描述文案在未提供nzNotFoundContent时取 i18n 的Empty.description如中文「暂无数据」测试 empty.spec.ts#L110-L117 验证了切换en_US后变为No Data。6. 三种全局内容形态的验证依据empty.spec.ts 的「should support string, template and component」用例给出了三种形态的运行时行为可作为配置参考形态设置方式渲染结果stringconfigService.set(empty, { nzDefaultEmptyContent: empty })各组件空状态直接显示文本emptyTemplateRefconfigService.set(empty, { nzDefaultEmptyContent: this.template })渲染模板let-component上下文中可拿到宿主组件名用例断言输出I am in template listType静态NZ_CONFIG注入自定义组件类以 Portal 方式挂载组件组件内可inject(NZ_EMPTY_COMPONENT_NAME)获取宿主名如list重置configService.set(empty, { nzDefaultEmptyContent: undefined })恢复内置nz-emptyant-empty-normalNZ-EMPTY-SIMPLE图此外测试中的注释指出「运行时通过set动态传入组件类Type的分支存在兼容性限制」对应上游 Angular 框架的一个已知 issue而通过NZ_CONFIG静态注入组件类则被「service injection」用例完整验证通过。因此从源码结构看如果需要以「自定义组件类」作为全局空内容优先采用NZ_CONFIG静态注入方式这是当前仓库测试覆盖所支持的组合。7. 实践建议与边界说明结合源码使用全局空状态配置时的注意事项作用范围全局nzDefaultEmptyContent仅对内部使用nz-embed-empty的组件生效即 demo 覆盖的 Select、TreeSelect、Cascader、Transfer、Table、List 等尺寸映射列表即其来源见 embed-empty.component.ts#L29-L42。直接写nz-empty的自定义空状态不受全局配置影响需用nzNotFoundImage/nzNotFoundContent/nzNotFoundFooter单独定制。优先级记忆口诀组件自身属性如 List 的nzNoResult 全局empty.nzDefaultEmptyContent 内置默认 Empty。动态切换用信号/effectdemo 展示了以 Angular 信号 effect响应式切换全局配置的模式由于NzEmbedEmptyComponent通过onConfigChangeEventForComponent(empty, ...)订阅了变更运行时set后已挂载的各组件空状态会即时刷新。取消自定义传undefined而非空字符串——空字符串会被当作合法string内容渲染string分支中typeof content string即走文本渲染只有undefined才会回退到内置默认 Empty。自定义模板拿宿主名TemplateRef的隐式上下文参数与自定义组件的NZ_EMPTY_COMPONENT_NAME注入是同一机制在不同形态下的两种暴露方式可据此在一个全局模板里写出「Data Not Found in {{ name }}」这类按组件区分文案的内容。参考文件索引示例入口demo/config.md、demo/config.ts全局配置类型config.ts嵌入组件实现embed-empty.component.ts公共组件实现empty.component.tsToken 与类型定义config.ts行为验证empty.spec.ts组件 API 文档doc/index.zh-CN.md赞分享UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载相关推荐ng-zorro-antd组件状态持久化localStorage应用ng zorro antd组件状态持久化localStorage应用 为什么需要状态持久化 在Web应用开发中用户可能希望页面刷新或重新打开后保留之前的设置UI组件前端antd Empty 空状态组件完全指南API 用法、内置图片与语义化定制antd Empty 空状态组件完全指南API 用法、内置图片与语义化定制 本指南基于 ant design 仓库中的 Empty空状态组件文档 com前端UI组件设计系统警惕用Facebook追踪好友睡眠这款开源工具暴露社交隐私风险警惕用Facebook追踪好友睡眠这款开源工具暴露社交隐私风险 你是否想过社交媒体上的在线状态会暴露你的睡眠规律当你深夜刷Facebook时你的好UI组件前端上一篇告别单调用foobox中文版重新定义你的音乐播放体验下一篇Yii2 HTTP 缓存HttpCache实战指南Last-Modified、ETag 与 Cache-Control 客户端缓存详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考