ng-zorro-antd Empty 空状态组件：使用 nzNotFoundImage=“simple“ 切换内置图片风格

UI组件前端【免费下载链接】ng-zorro-antdAngular UI Component Library based on Ant Design项目地址https://gitcode.com/gh_mirrors/ng/ng-zorro-antd点击查看免费下载本文讲解 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 nzNotFoundImagesimple / }) export class NzDemoEmptySimpleComponent {}核心就一句话在nz-empty组件上绑定nzNotFoundImagesimple。模板中不需要引入任何额外的 SVG 或样式文件因为两套内置图片都以组件形式打包在NzEmptyModule中开箱即用。二、simple与default两套内置图片的源码实现nz-empty组件components/empty/empty.component.ts在内部维护了一个内置图片关键字表const NzEmptyDefaultImages [default, simple] as const; type NzEmptyNotFoundImageType (typeof NzEmptyDefaultImages)[number] | null | string | TemplateRefvoid;即nzNotFoundImage的完整取值域为default | simple | null | string | TemplateRefvoid其中string表示自定义图片地址TemplateRefvoid表示模板。默认值为default。组件模板中通过isImageBuildIn标志决定渲染分支见 components/empty/empty.component.tsdiv classant-empty-image if (!isImageBuildIn) { ng-container *nzStringTemplateOutletnzNotFoundImage 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.tsif (nzNotFoundImage) { const image nzNotFoundImage.currentValue || default; this.isImageBuildIn NzEmptyDefaultImages.findIndex(i i image) -1; }当传入的字符串命中default/simple两个关键字时判定为内置图片否则视为自定义图片地址走img分支渲染。2.1 simple 风格 SVGsimple风格由NzEmptySimpleComponent提供components/empty/partial/simple.ts是一个 64×41 的紧凑插画下方一条椭圆投影上方一个信封/盒子造型的主体。关键结构如下svg classant-empty-img-simple width64 height41 viewBox0 0 64 41 xmlnshttp://www.w3.org/2000/svg g transformtranslate(0 1) fillnone fill-ruleevenodd ellipse classant-empty-img-simple-ellipse cx32 cy33 rx32 ry7 / g classant-empty-img-simple-g fill-rulenonzero path dM55 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 classant-empty-img-simple-path dM41.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与之相对默认风格NzEmptyDefaultComponentcomponents/empty/partial/default.ts是一张 184×152 的插画包含盒子主体、右上角的纸飞机以及底部的阴影图形复杂度明显高于simple适合页面级的大面积空状态svg classant-empty-img-default width184 height152 viewBox0 0 184 152 xmlnshttp://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.tsnz-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这里同时演示了nzNotFoundContent自定义描述内容与nzNotFoundFooter自定义操作区的模板用法可用于在空状态里加入创建数据之类的引导按钮。3.2 传入 TemplateRefnzNotFoundImage也支持TemplateRefvoid适用于需要完全自定义图片区域例如插入动画或复杂排版的场景。NzEmptyComponent使用nzStringTemplateOutlet指令来自ng-zorro-antd/core/outlet统一处理字符串与模板两种形态。四、API 汇总nz-empty组件见 components/empty/doc/index.zh-CN.md 的 API 章节的核心输入属性如下参数说明类型默认值[nzNotFoundImage]设置显示图片为string时表示自定义图片地址default/simple为内置图片string \| TemplateRefvoiddefault[nzNotFoundContent]自定义描述内容string \| TemplateRefvoid \| null语言包默认描述[nzNotFoundFooter]设置自定义 footerstring \| TemplateRefvoid-其中描述文案支持 i18n组件在ngOnInit中订阅NzI18nService.localeChange读取语言包中的Empty.description作为默认描述见 components/empty/empty.component.ts因此无需手动传描述也会随全局语言切换。五、simple 风格在内嵌空状态中的应用除独立使用外simple图片还被 ng-zorro-antd 的内嵌空状态机制大量复用NzEmbedEmptyComponentcomponents/empty/embed-empty.component.ts会根据宿主组件名自动适配尺寸并优先选用simple风格switch (size) { case (normal) { nz-empty classant-empty-normal nzNotFoundImagesimple / } case (small) { nz-empty classant-empty-small nzNotFoundImagesimple / } 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类型为Typeany | TemplateRefstring | 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 nzNotFoundImagesimple /内置关键字仅default与simple两个分别对应 184×152 的插画与 64×41 的紧凑图形SVG 实现见 components/empty/partial/default.ts 与 components/empty/partial/simple.ts非关键字字符串会被当作图片地址渲染为img也支持传入TemplateRefvoid完全自定义图片区域Table、List、Select、Cascader 等组件的内嵌空状态默认使用simple风格由 components/empty/embed-empty.component.ts 统一编排需要全局定制时通过NZ_CONFIG的empty.nzDefaultEmptyContent配置自定义空组件。赞分享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 Empty 空状态组件内置图片指南用 PRESENTED_IMAGE_SIMPLE 一键切换简洁风格占位图Ant Design Empty 空状态组件内置图片指南用 PRESENTED_IMAGE_SIMPLE 一键切换简洁风格占位图 在 Ant Design 中前端UI组件设计系统ng-zorro-antd Empty 全局化配置实战用 NzConfigService 一处定义所有组件的空状态ng zorro antd Empty 全局化配置实战用 NzConfigService 一处定义所有组件的空状态 本篇基于 ng zorro antd 的UI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考