UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载导读Empty空状态是 ng-zorro-antd 中用于数据为空时给用户明确提示的核心展示组件。本文以 components/empty/doc/index.zh-CN.md 为骨架结合 empty.component.ts、embed-empty.component.ts、config.ts 以及 empty.spec.ts 等源码与测试完整讲解nz-empty的三个核心输入属性nzNotFoundImage、nzNotFoundContent、nzNotFoundFooter、NZ_CONFIG全局配置项nzDefaultEmptyContent、NZ_EMPTY_COMPONENT_NAME注入令牌以及如何通过全局配置统一替换 Table、Select、Cascader、Transfer、List 等组件内部的空状态占位。读完本文你将能独立完成从默认空状态到组件级、模板级、全局级三层自定义的完整实战配置。何时使用当目前没有数据时nz-empty用于向用户提供显式的提示占位。典型场景包括表格无数据、下拉列表无可选项、搜索结果为空、列表为空等。ng-zorro-antd 的多数数据组件如 Table、List、Select、Cascader、Transfer、TreeSelect 等在数据为空时都会通过内部的NzEmbedEmptyComponent自动渲染空状态无需手动引入。nz-empty组件 APInz-empty的完整输入参数如下表所示默认导出自 public-api.ts使用前需在模块或独立组件中导入NzEmptyModule参数说明类型默认值[nzNotFoundImage]设置显示图片为string时表示自定义图片地址string \| TemplateRefvoiddefault[nzNotFoundContent]自定义描述内容string \| TemplateRefvoid \| null-[nzNotFoundFooter]设置自定义 footerstring \| TemplateRefvoid-参数详解与源码印证在 empty.component.ts 中图片取值被限定为内置枚举[default, simple]或自定义字符串/TemplateRefconst NzEmptyDefaultImages [default, simple] as const; type NzEmptyNotFoundImageType (typeof NzEmptyDefaultImages)[number] | null | string | TemplateRefvoid;组件的模板根据isImageBuildIn决定渲染路径当nzNotFoundImage命中内置枚举时simple渲染nz-empty-simple /否则渲染nz-empty-default /内置 SVG 占位图定义见 partial/default.ts 与 partial/simple.ts当传入的是自定义图片地址或模板时则通过*nzStringTemplateOutlet输出img [src]nzNotFoundImage [alt]...。ngOnChanges中的判断逻辑empty.component.ts如下if (nzNotFoundImage) { const image nzNotFoundImage.currentValue || default; this.isImageBuildIn NzEmptyDefaultImages.findIndex(i i image) -1; }即未传图片时默认回退为default传入任意非内置字符串则视为自定义图片 URL。描述文案nzNotFoundContent可接受字符串、TemplateRef或null。特别地传入null表示不渲染描述区域对应官方 description 示例 的nz-empty [nzNotFoundContent]null /未传或传字符串时默认文案取自 i18n 的Empty.description接口定义见 nz-i18n.interface.ts各语言包如 ar_EG.ts、zh_CN.ts 均有对应文案。组件在ngOnInit中订阅i18n.localeChange切换语言时描述文案会自动更新empty.component.ts。nzNotFoundFooter用于在空状态底部追加操作区如新建按钮同样支持字符串与模板两种形式渲染在ant-empty-footer容器内。基础用法示例最简用法对应 basic 示例nz-empty /渲染内置默认大图与本地化描述文案。需要更紧凑的样式时可切换simple图片对应 simple 示例nz-empty nzNotFoundImagesimple /自定义图片、描述与 footer模板形式nzNotFoundContent、nzNotFoundFooter传入TemplateRef时可插入任意结构与交互完整示例见 customize 示例nz-empty nzNotFoundImagehttps://gw.alipayobjects.com/zos/antfincdn/ZHrcdLPrvN/empty.svg [nzNotFoundContent]contentTpl [nzNotFoundFooter]footerTpl ng-template #contentTpl spanCustomize a href#APIDescription/a/span /ng-template ng-template #footerTpl button nz-button nzTypeprimary (click)onClick()Create Now/button /ng-template /nz-empty组件源码通过*nzStringTemplateOutlet来自NzOutletModule见 empty.component.ts统一处理字符串与模板两种入参因此上面两种形式写法等价、可自由混用。NZ_CONFIG全局配置nzDefaultEmptyContent除组件级自定义外ng-zorro-antd 还允许通过全局配置统一替换所有组件内部的默认空状态。nzEmpty配置接口只有一个字段参数说明类型nzDefaultEmptyContent用户自定义的全局空组件可通过undefined取消自定义的全局空组件Typeany \| TemplateRefstring \| string \| undefined官方文档给出的提供方式在根配置中声明{ provide: NZ_CONFIG, useValue: { empty: { nzDefaultEmptyContent } } }其中nzDefaultEmptyContent可以是字符串、TemplateRefstring或组件类Typeany。从 embed-empty.component.ts 看其取值通过NzConfigService.getConfigForComponent(empty)读取private getUserDefaultEmptyContent(): TypeNzSafeAny | TemplateRefstring | string | undefined { return (this.configService.getConfigForComponent(empty) || {}).nzDefaultEmptyContent; }运行时动态切换全局空组件全局配置同样支持在运行时通过NzConfigService.set(empty, ...)动态切换完整示例见 config 示例effect(() { const template this.customize() ? this.customTpl : undefined; this.nzConfigService.set(empty, { nzDefaultEmptyContent: template }); });当传入undefined时即取消自定义的全局空组件回退到内置默认空状态这一行为也被 empty.spec.ts 的用例所覆盖。NzEmbedEmptyComponent在构造函数中订阅了onConfigChangeEventForComponent(empty, ...)因此配置变化会立即触发重渲染无需重启或手动刷新。全局空状态的生效范围与尺寸适配nzDefaultEmptyContent会被注入到所有内嵌空状态场景Table、List、Select、TreeSelect、Cascader、Transfer、Mention 等组件在数据为空时均通过nz-embed-emptyNzEmbedEmptyComponent渲染空状态。从源码检索看tbody.component.ts、list-cell.ts、option-container.component.ts、tree-select.component.ts、cascader.component.ts、transfer-list.component.ts、mention.component.ts 均引用了该内嵌组件。NzEmbedEmptyComponent还会根据宿主组件名称自动适配空状态尺寸embed-empty.component.tsfunction 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 ; } }即Select/TreeSelect/Cascader/Transfer 使用simple小图并附加ant-empty-smallTable/List 使用simple图并附加ant-empty-normal其余组件渲染完整默认空状态。这一行为被 empty.spec.ts 断言验证检查ant-empty-normal类与NZ-EMPTY-SIMPLE元素。InjectionTokenNZ_EMPTY_COMPONENT_NAME当你以组件类Typeany形式提供全局自定义空组件时ng-zorro-antd 会向该组件注入令牌NZ_EMPTY_COMPONENT_NAME其值为当前宿主组件的名称如table、select以便你在自定义空组件内部感知自己正显示在哪个组件里Token说明参数NZ_EMPTY_COMPONENT_NAME将会被注入到用户的全局自定义空组件中告诉该组件其所在组件的名称string令牌定义见 config.tsexport const NZ_EMPTY_COMPONENT_NAME new InjectionTokenstring( typeof ngDevMode ! undefined ngDevMode ? nz-empty-component-name : );注入的实现位于 embed-empty.component.ts当全局内容为组件类时NzEmbedEmptyComponent会创建一个携带该令牌的Injector并通过ComponentPortal动态挂载自定义组件const injector Injector.create({ parent: this.injector, providers: [{ provide: NZ_EMPTY_COMPONENT_NAME, useValue: this.nzComponentName }] }); this.contentType component; this.contentPortal new ComponentPortal(content, this.viewContainerRef, injector);全局自定义空组件组件类示例在自定义空组件中通过inject(NZ_EMPTY_COMPONENT_NAME)获取宿主名称import { Component, inject } from angular/core; import { NZ_EMPTY_COMPONENT_NAME } from ng-zorro-antd/empty; Component({ selector: app-global-empty, template: divData Not Found in {{ componentName }}/div }) export class AppGlobalEmptyComponent { componentName inject(NZ_EMPTY_COMPONENT_NAME); }然后在根配置中声明为全局空组件{ provide: NZ_CONFIG, useValue: { empty: { nzDefaultEmptyContent: AppGlobalEmptyComponent } } }此时无论 Table、Select 还是其他组件出现空状态都会渲染AppGlobalEmptyComponent并通过注入的令牌得知自己所属的组件名。这一组件类 注入令牌的组合也被 empty.spec.ts 的 service injection 测试用例所验证断言自定义组件被渲染且内容为Im in component list。三种全局内容形式与优先级综合 embed-empty.component.ts 的renderEmpty逻辑全局空内容的处理规则为内容类型按string→TemplateRef→ 组件类依次判定分别走文本渲染、模板渲染与 Portal 动态挂载宿主组件自身的specificContent如各组件内部传入的空状态内容优先于全局配置即组件级 全局级全局内容为undefined时取消自定义回退到内置nz-empty按尺寸规则选择 simple/默认图。嵌入式空状态的使用方式虽然nz-embed-emptyNzEmbedEmptyComponent主要由 Table、Select 等组件内部自动使用但它同样是一个可引用的公开组件selector 为nz-embed-emptyexportAs 为nzEmbedEmptyembed-empty.component.ts。它接收两个输入nzComponentName宿主组件名称用于决定尺寸normal/small并作为NZ_EMPTY_COMPONENT_NAME的注入值specificContent组件级空状态内容优先级高于全局配置。NzEmptyModule同时导出了NzEmptyComponent、NzEmbedEmptyComponent及相关的 partial 组件见 empty.module.ts因此只需导入一次模块即可同时使用nz-empty与内嵌空状态能力。完整实战从局部到全局的三层自定义方案将上述 API 组合起来可以形成一套完整的三层空状态定制策略层级手段作用范围典型场景组件级nzNotFoundImage/nzNotFoundContent/nzNotFoundFooter单个nz-empty实例页面内独立占位、带操作按钮的空结果页内嵌组件级specificContentnz-embed-empty输入单个数据组件仅某个表格/下拉的空状态定制全局级NZ_CONFIGnzDefaultEmptyContentstring / TemplateRef / 组件类所有内嵌空状态全站统一品牌化空状态、多语言空文案推荐落地顺序先用默认nz-empty验证页面效果 → 需要局部定制时使用nzNotFound*三个输入 → 需要全站统一时通过NZ_CONFIG提供全局内容 → 需要在自定义组件里感知宿主组件名称时使用组件类形式并注入NZ_EMPTY_COMPONENT_NAME。所有配置均可通过NzConfigService.set在运行时动态变更且配置变化会即时生效embed-empty.component.ts 中订阅了 empty 配置变更事件。延伸阅读组件实现empty.component.ts图片/文案/尺寸判断逻辑、embed-empty.component.ts全局内容注入与渲染、config.ts类型与令牌定义内置占位图partial/default.ts、partial/simple.ts示例代码basic、simple、description、customize、config含 md 说明测试用例empty.spec.ts尺寸适配、string/template/component 三种内容、service injection样式文件style/index.lessant-empty系列样式类全局配置机制可参考 core/config 下的NZ_CONFIG与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 空状态组件自定义图片、描述与 Footer 附属内容实战ng zorro antd Empty 空状态组件自定义图片、描述与 Footer 附属内容实战 本篇技术文章以 ng zorro antd 中 EmptyUI组件前端Ant Design Vue Empty 空状态组件完全指南占位图、自定义与全局配置Ant Design Vue Empty 空状态组件完全指南占位图、自定义与全局配置 Empty空状态是 Ant Design Vue 中用于“数据为空”前端UI组件设计系统Ant Design Empty 组件完全指南空状态占位符的定制、内置图片与全局配置Ant Design Empty 组件完全指南空状态占位符的定制、内置图片与全局配置 空状态Empty State是数据密集型界面的必备要素。在 Ant前端UI组件设计系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考