NG-ZORRO 头像组（nz-avatar-group）组合展示实战：从演示代码到源码原理-育师

UI组件
前端

【免费下载链接】ng-zorro-antd

Angular UI Component Library based on Ant Design

项目地址：https://gitcode.com/gh_mirrors/ng/ng-zorro-antd

本文围绕 NG-ZORRO 组件库中 Avatar 头像组（Avatar Group）的组合展示能力展开。头像组用于将多个头像并排呈现，常见于团队协作、项目成员、评论回复等需要"多人集合"展示的场景。通过阅读本文，你将掌握nz-avatar-group的基本用法、头像的四种展示形态（图片 / 图标 / 文字 / 自定义内容）、超出数量时的折叠聚合技巧，以及其底层组件与样式实现原理，可直接在 Angular 项目中落地使用。

一、头像组是什么：组合展示的核心形态

在头像组演示文档中，头像组的定位被一句话概括为"头像组合展现"（Avatar group display）。与单个nz-avatar不同，nz-avatar-group是一个纯粹的组合容器：它本身不渲染具体内容，而是将内部多个nz-avatar按组的方式排布，形成水平重叠、整齐划一的视觉队列。

从使用形态上看，头像组通常承载两种交互意图：

并列展示：将多个成员头像依次排列，完整呈现所有成员；
聚合折叠：当成员数量超出可展示范围时，以 "+N" 文本头像的形式收敛剩余成员，保留整体信息的完整性。

这两种形态在官方演示 group.ts 中均有完整示例，下文将逐一拆解。

二、基础用法：构建第一个头像组

头像组的使用非常轻量，只需在模板中把若干个nz-avatar放进nz-avatar-group容器即可。以官方演示的第一个组为例（来源：group.ts）：

<nz-avatar-group> <nz-avatar nzIcon="user" nzSrc="//zos.alipayobjects.com/rmsportal/ODTLcjxAfvqbxHnVXCYX.png" /> <nz-avatar style="background-color: #f56a00" nzText="U" /> <nz-avatar style="background-color: #87d068" nz-tooltip nzTooltipTitle="NG-ZORRO User" nzIcon="user" /> <nz-avatar style="background-color: #1890ff" nzText="NG" /> <nz-avatar [nzSize]="32"> <nz-icon nzType="ant-design" nzTheme="outline" /> </nz-avatar> </nz-avatar-group>

对应的组件类（group.ts）声明如下：

@Component({ selector: 'nz-demo-avatar-group', imports: [NzAvatarModule, NzDividerModule, NzTooltipModule, NzIconModule], template: `...` }) export class NzDemoAvatarGroupComponent {}

要点说明：

需要导入NzAvatarModule（来自ng-zorro-antd/avatar）；示例中还同时引入了NzDividerModule、NzTooltipModule、NzIconModule，分别用于示例间的分隔线、头像上的提示气泡和自定义图标内容；
这个示例同时演示了图片头像、文字头像、图标头像、自定义内容头像四种形态，以及通过[nzSize]="32"直接指定像素尺寸的用法；
中间的头像通过nz-tooltip与nzTooltipTitle="NG-ZORRO User"挂载了悬浮提示，说明头像组内部可以自由组合任意nz-avatar的既有能力，而不只是静态展示。

头像的四种展示形态

在组合场景中，每个成员头像的类型取决于你传入的属性，其优先级与判定逻辑可在 avatar.component.ts 的ngOnChanges中确认：

形态	关键属性	判定逻辑（源码可见）
图片头像	`nzSrc`（可选`nzSrcSet`、`nzAlt`）	只要传入`nzSrc`即为图片头像
图标头像	`nzIcon`	未设置`nzSrc`且设置了`nzIcon`
文字头像	`nzText`	未设置`nzSrc`且设置了`nzText`
自定义内容	直接放入`ng-content`	任意模板内容，如`<nz-icon>`或其他元素

渲染模板（avatar.component.ts）依次判断nzIcon、nzSrc、nzText，最后兜底渲染ng-content，因此当图片加载失败时还会走imgError的降级逻辑：若nzIcon存在则回退到图标，否则回退到文字（avatar.component.ts）。

三、聚合折叠：用 "+N" 收敛超出成员

头像组最有代表性的能力是"数量折叠"。当成员很多、界面空间有限时，可以把剩余人数合并成一个文字头像。官方演示的第二个组（来源：group.ts）给出了标准写法：

<nz-avatar-group> <nz-avatar nzIcon="user" nzSrc="//zos.alipayobjects.com/rmsportal/ODTLcjxAfvqbxHnVXCYX.png" /> <nz-avatar style="background-color: #f56a00" nzText="U" /> <nz-avatar style="background-color: #fde3cf; color: #f56a00" nzText="+2" /> </nz-avatar-group>

实现思路并不复杂：

前两个头像正常展示具体成员；
第三个头像使用nzText="+2"，配合自定义背景色（#fde3cf）与文字色（#f56a00）标识"还有 2 位成员未展示"；
该"头像"本质上仍是普通nz-avatar，所以它同样继承文字头像的尺寸计算与缩放逻辑（见下文第四节），只是文本内容换成了人数标识。

这是目前组件 API 层面给出的官方组合方式——nz-avatar-group本身不提供maxCount之类的自动折叠属性，需要由业务方根据数据量自行决定渲染几个真实头像、何时切换为 "+N" 文字头像。需要更多折叠交互时，可结合nz-tooltip或自定义弹出层展示完整成员列表。

四、文字头像的自动缩放：保证组内视觉整齐

头像组能呈现"大小一致、文字不溢出"的整齐效果，关键在于文字头像内部有一套自动缩放机制，其实现位于 avatar.component.ts 的calcStringSize方法：

每次渲染完成后（通过afterEveryRender触发），测量文字元素的真实宽度childrenWidth与头像容器宽度avatarWidth；
计算左右留白offset：默认nzGap * 2，但当头像过小（nzGap * 2不小于头像宽度）时自动退化为固定值8，避免缩放异常；
若文字宽度超出可用宽度(avatarWidth - offset)，则按比例scale缩放文字，并通过transform: scale(...) translateX(-50%)保持居中。

这一机制解释了为什么nzText="NG"这类多字符文字头像不会撑破圆形边界，也解释了nzText="+2"折叠头像能自然适配任意尺寸的头像组。nzGap的默认值为4，可通过nzGap属性或全局配置调整（见 avatar.component.ts）。

五、核心 API 速查表

头像组由nz-avatar-group容器与nz-avatar成员组成，完整参数定义见官方 API 文档。

nz-avatar 成员参数

参数	说明	类型	默认值	全局配置
`[nzIcon]`	设置头像的图标类型，参考`Icon`	`string`	-
`[nzShape]`	指定头像的形状	`'circle' \\| 'square'`	`'circle'`	✅
`[nzSize]`	设置头像的大小	`'large' \\| 'small' \\| 'default' \\| number \\| { xs, sm, ... }`	`'default'`	✅
`[nzGap]`	字符类型距离左右两侧边界单位像素	`number`	`4`	✅
`[nzSrc]`	图片类头像的资源地址	`string`	-
`[nzSrcSet]`	设置图片类头像响应式资源地址	`string`	-
`[nzAlt]`	图像无法显示时的替代文本	`string`	-
`[nzText]`	文本类头像	`string`	-
`[nzLoading]`	设置图片类头像`<img>`元素原生`loading`属性	`'eager' \\| 'lazy'`	`'eager'`
`[nzFetchPriority]`	设置图片类头像`<img>`元素原生`fetchpriority`属性	`'high' \\| 'low' \\| 'auto'`	`'auto'`
`(nzError)`	图片加载失败事件，调用`preventDefault`会阻止默认 fallback 行为	`EventEmitter<Event>`	-

其中带 ✅ 的参数可通过 NG-ZORRO 的全局配置（NZ_CONFIG中avatar键）统一设置，例如默认形状、默认尺寸与默认nzGap；nzSize自 22.1.0 起支持{ xs, sm, md, lg, xl, xxl }形式的响应式对象，组件内部会结合NzBreakpointService订阅当前断点动态取值（见 avatar.component.ts）。

nz-avatar-group 容器

<nz-avatar-group> <nz-avatar nzIcon="user" /> <!-- ... --> </nz-avatar-group>

容器不提供额外参数，只负责包裹与排版。

六、源码级原理：容器组件与重叠样式

容器组件的实现

NzAvatarGroupComponent是一个极简的投影容器（avatar-group.component.ts）：

@Component({ selector: 'nz-avatar-group', exportAs: 'nzAvatarGroup', template: `<ng-content />`, host: { class: 'ant-avatar-group' } }) export class NzAvatarGroupComponent {}

它通过<ng-content />将内部头像原样投影，仅在宿主元素上挂载ant-avatar-group样式类。也就是说，头像组的所有视觉呈现都来自样式层，而非组件逻辑。

重叠与间距的样式实现

头像组"错落重叠、前后叠压"的视觉效果定义在 group.less 中：

.@{avatar-prefix-cls}-group { display: inline-flex; .@{avatar-prefix-cls} { border: 1px solid @avatar-group-border-color; &:not(:first-child) { margin-inline-start: @avatar-group-overlapping; } } &-popover { .@{ant-prefix}-avatar + .@{ant-prefix}-avatar { margin-inline-start: @avatar-group-space; } } }

关键点：

容器使用inline-flex，保证头像水平排列并随内容自然撑开；
每个头像带1px边框（颜色为@avatar-group-border-color），使重叠部分能清晰区分前后层级；
从第二个头像开始应用负值语义的margin-inline-start: @avatar-group-overlapping产生重叠效果（该值通常为负数），形成"卡片叠放"观感；
预留了-popover子样式：当折叠列表用弹出层展示时，弹出层内部的头像改用@avatar-group-space间距，避免继续重叠。

头像本身的基础样式（圆形、尺寸、字号、图片铺满等）在 index.less 中通过avatar-sizemixin 生成，并支持ant-avatar-lg/ant-avatar-sm尺寸变体。

测试验证

仓库测试 avatar.spec.ts 验证了容器渲染后的关键约束：查询NzAvatarGroupComponent指令对应的宿主元素，断言其classList中包含ant-avatar-group。这说明host上的样式类绑定是头像组对外呈现的契约，任何对组样式的自定义都应基于该类展开。

七、实战建议

数据驱动渲染：头像组非常适合配合*ngFor或@for从成员数组渲染；当数组长度超过阈值（如 3~4 个）时，渲染前N-1个真实头像 + 一个nzText="+N"的聚合头像，即可低成本实现折叠。
善用降级策略：nzSrc加载失败时组件会自动回退到nzIcon/nzText（avatar.component.ts），给成员头像同时配置nzSrc与nzText可避免图片失效时出现空白。
组合其他组件：头像组内部可自由混用nz-tooltip（成员姓名提示）、nz-badge（在线状态角标）等能力，使其从静态展示升级为可交互的信息面板。
自定义样式扩展：如需调整重叠幅度、边框颜色或折叠态配色，可通过覆盖ant-avatar-group样式类实现，同时注意同步调整 group.less 中对应的 Less 变量。