AvatarGroup 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

将多个头像排列或叠放展示，并以数量提示收起的成员，适合团队、协作者与参与者列表。

使用选择

用于多个参与者头像的横向或叠放展示。联系人详情列表仍使用普通列表，不用 AvatarGroup 承载整行信息。

• 参与排列与 +N 计数的直接子项必须声明 as="item"；用 max 限制可见数量。

• row 的 size 表示单个头像尺寸；stack 的 size 表示组容器尺寸，不要用同一数值假定两种布局的头像大小相同。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Avatar, AvatarGroup } from '@snowui-design-system/components';	import { Avatar3d04, AvatarAbstract02, AvatarAbstract04, AvatarByewind, AvatarFemale04, AvatarFemale06, AvatarMale03, AvatarMale05 } from '@snowui-design-system/resource-svelte';</script> <AvatarGroup size={40} layout="row" max={4}>	<Avatar as="item" src={AvatarByewind} dataName="ByeWind, maintainer" />	<Avatar as="item" src={AvatarFemale04} dataName="Maya, design" />	<Avatar as="item" src={Avatar3d04} dataName="Leo, components" />	<Avatar as="item" src={AvatarMale03} dataName="Noah, documentation" />	<Avatar as="item" src={AvatarAbstract02} dataName="Ari, accessibility" />	<Avatar as="item" src={AvatarFemale06} dataName="Sofia, research" />	<Avatar as="item" src={AvatarMale05} dataName="Eli, engineering" />	<Avatar as="item" src={AvatarAbstract04} dataName="Kai, community" />	<Avatar as="item" fallbackSeed="user-community-108" aria-label="Additional community member" /></AvatarGroup>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

组合模式

AvatarGroup 使用显式组合模式：调用方显式书写 <Avatar as="item">，AvatarGroup 只负责排列、叠放、溢出计数和统一 size Context，不拥有 Avatar 的业务数据，因此不提供 parts.Avatar。每个 Avatar 的差异 Props 直接写在对应实例上。

用于将多个头像或任意子元素以叠放形式组合展示，并在超出显示数量时自动以数字提示。

布局模型

主布局模型：复合管理布局。

• AvatarGroup 的区域结构为 group root / visible avatar items / overflow count / stack positioning。

• 子项 Avatar、Icon、Badge 仍各自保持内禀原子或内联外壳布局；AvatarGroup 只管理集合排列、遮罩切割和溢出计数。

• row 和 stack 是集合布局模式，不是 Button 式内联外壳，也不是 Frame 的三槽位宿主。

• 尺寸上下文通过 Frame context 下发给子项，排列和重叠规则属于 AvatarGroup 私有逻辑。

功能概览 (User)

• 多头像布局（支持线性叠放与圆形堆叠）

• 超出数量时自动显示 +N 溢出计数（最高显示 +99）

• 与任意子元素组合（不仅限于 Avatar）

• 边框切割叠放与溢出头像配色遵循 Avatar 规则

2. 视觉规则

1. 布局规则：

   • row: 线性排列，数量不限；使用边框切割方式进行叠放。

   • stack: 圆形堆叠，2/3 个头像固定位置排列，4 个及以上固定显示 3 个头像 + +N。当发生溢出时，+N 占用一个头像位置（stack 中如 max=2 或 max=3 时显示 1/2 个头像 + +N；row 则保留 max 个头像，另显示计数）。

2. 位置与层级（stack 模式）：

   • 中心点角度（以圆心为原点，顺时针为负角）：

     • max=2：-45°、135°

     • max=3：-90°、150°、30°

     • max>=4：-45°、-135°、135°、45°

   • 层级顺序：从下到上依次为 红、绿、蓝、紫。

   • +N 位置：始终占用 红色位置（最低层）。

3. True Cutout 边框切割：头像叠放使用基于 CSS Mask 的真实边框切割技术，确保在任何背景颜色下均呈现精准的缝隙。

   • 切割比例：边框厚度基准为 0.04em（相对于头像尺寸）。

   • Row 布局：切除左侧项与右侧项重叠的部分。

   • Stack 布局：低层头像根据与其重叠的所有高层头像的相对坐标，动态生成复合遮罩进行精准切割。

4. 统一尺寸驱动 (Unified Sizing)：

   • 核心逻辑：通过单一属性 size 控制视觉。

   • Stack 模式：size 代表容器。头像按 max 对应比例自动分发（1:1.8, 1:2.0, 1:2.2）。内部传导允许亚像素精度（如 36.36px）。

   • Row 模式：size 代表头像。容器高度自动跟随。

5. 对齐优化：容器强制执行 vertical-align: top 和 line-height: 0，确保在任何字号环境下头像均能像素级对齐。

6. 叠放间距：叠放重叠比例固为头像尺寸的 25% (0.25)。

7. 溢出头像颜色：+N 头像的文字为固定黑色，底色为 #EDEDED。配合 stack 模式时，计数器自动应用绝对定位以消除布局抖动。

8. 资源匹配：向子组件透传 size 时，系统自动向上取整（Math.round），确保 AvatarByewind 等资源组件能加载到最匹配的图片分辨率。

3. 使用示例

<AvatarGroup size={24}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" /></AvatarGroup>

<AvatarGroup max={2} size={32}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" />    <Avatar as="item" /></AvatarGroup>

<AvatarGroup layout="stack" size={80} max={3}>    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" src={AvatarByewind} />    <Avatar as="item" />    <Avatar as="item" /></AvatarGroup>

[!IMPORTANT] 溢出背景样式: 头像组溢出计数 (+N) 的背景颜色已按用户要求制定为灰色 #EDEDED。此样式具有最高优先级，且作为系统默认回退方案。

在此处添加您的自定义说明、业务逻辑约束或特定示例。