企业官网建设流程全解析

• UI组件
• 前端

nz-avatar（头像组件）用于代表用户或事物，是数据展示场景中的高频基础组件。在 ng-zorro-antd 中，头像支持**图片（Image）、图标（Icon）与字符（Letter）**三种展示类型，其中 Icon 与字符型头像可以自定义图标颜色与背景色。阅读本文后，你将掌握三种类型的完整用法、渲染优先级与加载失败的 fallback 机制，并能直接复制可运行的示例代码到自己的 Angular 项目中。

三种类型的核心概念

根据 type.md 的说明，头像组件支持三种类型：

其中，Icon 类型和字符类型都可以通过内联style自定义图标颜色及背景色；图片类型则可通过nzSrcSet、nzAlt、nzLoading、nzFetchPriority等属性做更细粒度的控制。

完整示例：一行代码展示六种头像形态

官方演示位于 type.ts，覆盖了三种类型的典型用法：

import { Component } from '@angular/core'; import { NzAvatarModule } from 'ng-zorro-antd/avatar'; @Component({ selector: 'nz-demo-avatar-type', imports: [NzAvatarModule], template: ` <nz-avatar nzIcon="user" /> <nz-avatar nzText="U" /> <nz-avatar nzText="USER" /> <nz-avatar nzIcon="user" nzSrc="//zos.alipayobjects.com/rmsportal/ODTLcjxAfvqbxHnVXCYX.png" /> <nz-avatar nzText="U" style="color:#f56a00; background-color:#fde3cf;" /> <nz-avatar nzIcon="user" style="background-color:#87d068;" /> `, styles: ` nz-avatar { margin-top: 16px; margin-inline-end: 16px; } ` }) export class NzDemoAvatarTypeComponent {}

这段模板依次演示了：

1. nzIcon="user"—— 纯图标头像；
2. nzText="U"—— 单字符头像；
3. nzText="USER"—— 多字符头像（多字符会被自动缩放以适配容器）；
4. nzIcon="user" nzSrc="..."—— 同时指定图标与图片地址，此时图片优先渲染；
5. nzText="U"+style="color:#f56a00; background-color:#fde3cf;"—— 自定义字符颜色与背景色；
6. nzIcon="user"+style="background-color:#87d068;"—— 自定义图标背景色。

示例组件通过imports: [NzAvatarModule]独立引入头像模块，无需在 NgModule 中额外声明，体现了组件自身的模块化设计。

渲染优先级与 fallback 机制（源码级原理）

在 avatar.component.ts 的模板中，三种类型的渲染遵循严格的优先级：

@if (nzIcon && hasIcon) { <nz-icon [nzType]="nzIcon" /> } @else if (nzSrc && hasSrc) { <img [src]="nzSrc" ... (error)="imgError($event)" /> } @else if (nzText && hasText) { <span class="ant-avatar-string" #textEl>{{ nzText }}</span> }

即：Icon 优先于图片、图片优先于字符。而在ngOnChanges（avatar.component.ts）中，组件对输入属性做了归一化：

ngOnChanges(): void { this.hasText = !this.nzSrc && !!this.nzText; this.hasIcon = !this.nzSrc && !!this.nzIcon; this.hasSrc = !!this.nzSrc; }

可以看到图片（nzSrc）的优先级最高：只要设置了nzSrc，hasText与hasIcon都会被强制置为false；只有未提供nzSrc时，nzIcon才优先生效，其次才是nzText。

这解释了示例中第 4 个头像nzIcon="user" nzSrc="..."为何最终显示为图片：两者并存时图片胜出。nzSrcSet（多分辨率资源）与nzAlt（替代文本）会通过[attr.srcset]、[attr.alt]透传到原生<img>元素上，见 avatar.component.ts。

图片加载失败时的自动降级

当图片加载失败时，imgError方法（avatar.component.ts）会执行 fallback 逻辑：

imgError(event: Event): void { this.nzError.emit(event); if (!event.defaultPrevented) { this.hasSrc = false; this.hasIcon = false; this.hasText = false; if (this.nzIcon) { this.hasIcon = true; } else if (this.nzText) { this.hasText = true; } this.cdr.detectChanges(); } }

即：图片加载失败后，如果同时提供了nzIcon则降级为图标头像，否则若提供了nzText则降级为字符头像；而通过(nzError)事件调用event.preventDefault()可以阻止这一默认降级行为，交给开发者自行处理。这一行为在 avatar.spec.ts 中有对应测试：先断言getType(dl)为'image'，手动触发 error 后断言变为'icon'。

自定义颜色与背景色

Icon 与字符型头像的自定义方式非常直观——直接通过组件的宿主元素样式注入：

<!-- 字符：同时自定义文字颜色与背景色 --> <nz-avatar nzText="U" style="color:#f56a00; background-color:#fde3cf;" /> <!-- 图标：自定义背景色，图标颜色继承默认主题 --> <nz-avatar nzIcon="user" style="background-color:#87d068;" />

原理上，组件以ViewEncapsulation.None方式渲染，宿主元素带ant-avatar类（avatar.component.ts），并依据输入动态切换ant-avatar-icon、ant-avatar-image等语义类，因此开发者传入的style会直接作用于头像外层容器，文字与图标样式随之生效。字符颜色即color属性，背景色即background-color属性，两者可独立设置。

字符自动缩放：nzGap 的底层作用

字符头像的文本不会直接溢出：afterEveryRender钩子会调用calcStringSize()（avatar.component.ts）计算缩放比例：

private calcStringSize(): void { ... const childrenWidth = textEl.offsetWidth; const avatarWidth = this.el.getBoundingClientRect?.().width ?? 0; const offset = this.nzGap * 2 < avatarWidth ? this.nzGap * 2 : 8; const scale = avatarWidth - offset < childrenWidth ? (avatarWidth - offset) / childrenWidth : 1; textEl.style.transform = `scale(${scale}) translateX(-50%)`; ... }

当文本宽度超过「头像宽度 − 两倍nzGap」时，文本会被等比缩放。因此nzGap（字符距离左右两侧边界的像素数，默认4）不仅决定间距，还直接影响文本的缩放临界点；对于「USER」这类多字符头像，该机制保证文本始终完整显示在圆形容器内。样式细节见 style/index.less。

nz-avatar 完整 API 参考

结合 index.zh-CN.md 与组件源码，nz-avatar支持以下输入属性：

几点说明：

• nzShape、nzSize、nzGap支持全局配置（对应NzConfigKey中的'avatar'，见 avatar.component.ts），可在应用入口统一设置；
• nzSize传入数字或响应式对象（{ xs, sm, md, ... }）时，组件内部借助NzBreakpointService订阅断点变化动态计算尺寸，并将数值换算为 CSS 像素（customSize），字体大小自动取尺寸的一半（customFontSize，见 avatar.component.ts）；
• 若需要以编程方式批量配置头像，可复用 types.ts 中导出的NzAvatarProps接口（含shape、size、gap、src、srcSet、alt、icon、text、error字段）。

组合场景：分组头像

三种类型同样适用于分组场景。nz-avatar-group（实现见 avatar-group.component.ts）只是带ant-avatar-group类的简单内容容器，内部可混用任意类型的nz-avatar：

<nz-avatar-group> <nz-avatar nzIcon="user" /> <nz-avatar nzText="U" /> <nz-avatar nzSrc="https://example.com/avatar.png" /> </nz-avatar-group>

分组后头像之间的间距、堆叠与遮罩样式由 style/group.less 提供，适合团队成员列表、多用户标签等展示场景。

小结

头像的三种类型——图片、Icon、字符——覆盖了「用户真实头像 / 占位图标 / 姓名缩写」三类最常见的业务诉求。使用时牢记三点：同时设置nzSrc与nzIcon时图片优先；Icon 与字符型可通过宿主style直接定制颜色与背景色；图片加载失败时组件会按「图标 → 字符」顺序自动降级，且可通过(nzError)的preventDefault()接管处理。官方演示代码与测试（type.ts、avatar.spec.ts）均可直接作为实现与验证依据。

• UI组件
• 前端