# AvatarGroup 更新日志

先阅读 [完整 LICENSE](https://snowui.dev/LICENSE)；同任务、同版本、同范围去重。

- 2026-09-21：统一使用文档、源码属性表与 Site / AI 阅读入口；仅文档修订，不改变组件行为。

### v1.8.7 (2026-09-02)

- 根据现有源码补齐逐属性说明、默认回退和使用边界；未改变组件运行时行为。

- **AvatarGroup-Docs.2026-05-25** 源码顶部历史更新日志已归档；后续新增变更统一写入本文档 更新日志，源码顶部只保留职责、当前关键架构与文档路径。

### v1.8.6 (2026-04-25)

#### 修复
- **AG-Fix.10** 修复 `layout="stack"` 时 hover 样式错乱：stack 定位与 mask 不再写入子 Avatar 的 inline style，改由 AvatarGroup 维护的实例级 CSS 规则承接，避免子 Avatar hover 时由 Frame 重写 `style` 属性并清掉父级几何样式。

### v1.8.5 (2026-02-13)

#### 修复
- **AG-Fix.8** 修复 `+N` 计数头像尺寸与普通头像不一致：在 `.snowui-avatar-group` 统一设置 `font-size: var(--text-16)`，让尺寸链路与 Avatar 子项一致（统一消费 `--size-*` 梯度 token）。
- **AG-Fix.9** `+N` 尺寸 fallback 从 `em` 改为 `rem`，避免无 size 场景受父级字号影响。

### v1.8.1 (2026-02-13)

#### 修复
- **AG-Fix.6** 修正了 `sizeMap` 中错误的 Token 倍率计算逻辑，解决了头像组尺寸偏差问题。

#### 破坏性变更
- **AG-Breaking.1** 彻底移除了已弃用的 `groupSize` 和 `avatarSize` 属性。现由 `size` 统一驱动。

#### 修复
- **AG-Fix.4** **对齐加固**：通过将 `stack` 模式下的计数器改为 `absolute` 定位并修正容器基线，解决了 48px 以下尺寸出现的偏移。
- **AG-Fix.5** **资源匹配优化**：向资源子组件透传 `size` 时应用 `Math.round()` 取整，确保 sub-pixel 尺寸下（如 36.36px）仍能加载匹配的图片规格。

#### 新功能
- **AG-Feat.3** 增强了尺寸传导的灵活性，系统现在支持透传任意精度的计算尺寸，由子组件 (`Avatar`) 自动适配其 `rem` 样式。

### v1.7.0 (2026-02-06)

#### 新功能
- **AG-Feat.2** 实现了基于 CSS Mask 的“True Cutout”边框切割效果。
- **AG-Style.5** **尺寸逻辑重构**：统一使用 `size` 属性驱动布局。简化了 `stack` 模式下的心智模型（`size` 即容器大小），并维持头像比例自动适配。
- **AG-Style.6** 修正了 `stack` 模式下 `max=3` 的固定角度。

### v1.6.0 (2026-02-05)

#### 新功能
- **AG-Feat.1** 新增 `layout`、`groupSize`、`avatarSize` 以支持线性与圆形堆叠布局。

#### 架构重构
- **AG-Refactor.1** stack 模式固定 3 个头像 + `+N`，并支持 `avatarSize` 撑大 `groupSize`。
- **AG-Refactor.2** `stack` 模式下未传 `avatarSize` 时按 `groupSize * 0.6` 推导默认头像大小。
- **AG-Refactor.4** `stack` 模式默认头像尺寸改为基于 `max` 的分段比例。
- **AG-Refactor.5** `stack` 模式位置角度与层级顺序按 45° 斜线规则固定。

### v1.5.7 (2026-02-05)

#### 样式优化
- **AG-Style.4** 溢出计数 `overflowText` 增加 `+99` 封顶逻辑。
- **AG-Style.3** 统一溢出计数背景颜色为用户指定的灰色 (#EDEDED)，并更新 CSS 回退方案。

### v1.5.6 (2026-02-05)

#### 架构重构
- **Size Context**: 尺寸上下文逻辑移至 `Frame` 层。`AvatarGroup` 的 `size` 属性现在通过 `Frame` 自动向所有子组件（Avatar, Icon, Badge）传播。

### v1.5.4 (2026-02-03)

#### 样式优化
- **AG-Style.1** 叠放边框厚度基准调整为 `var(--border-2)`（size=32）

### v1.5.3 (2026-02-03)

#### 修复
- **AG-Fix.3** 补齐 Frame 能力开关显式传参

### v1.5.2 (2026-02-03)

#### 修复
- **AG-Fix.2** 内部变量命名对齐 snowui 规范，移除非必须字重样式

### v1.5.1 (2026-02-03)

#### 修复
- **AG-Fix.1** 统一溢出头像与普通头像的叠放间距计算

### v1.5.0 (2026-02-03)

#### 新功能
- **AG2.1** 新增 `size` 属性控制组内头像默认尺寸，子头像尺寸优先

### v1.4.3 (2026-02-03)

#### 修复
- **AG1.5** 同步选择器写法以避免样式解析错误，并清理示例资源引用

### v1.4.2 (2026-02-03)

#### 修复
- **AG1.4** 同步文档与实际实现的子元素标记规则

### v1.4.1 (2026-02-03)

#### 样式优化
- **AG1.3** 补充边框切割、间距与溢出头像颜色规则

### v1.4.0 (2026-02-03)

#### 新功能
- **AG1.1** 新增 `max` 属性，支持溢出计数展示 `+N`
- **AG1.2** 叠放规则应用于所有直接子元素，并采用边框切割策略

### v1.3.1 (2026-02-03)
- 适配 Avatar 新 API，移除 alt / fallback 示例