# Avatar 更新日志

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

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

### v2.12.5 (2026-09-02)

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

### v2.12.4 (2026-08-28)

- 新增 `fallbackColor` 六种具名默认 Gradient 配色与 `fallbackSeed` 稳定身份映射；推荐传入 `user.id`，相同 seed 跨刷新保持同色。
- 默认配色优先级调整为显式颜色、稳定 seed、名称回退、固定 `blue`；完全匿名头像不再依赖组件实例 ID。

### v2.12.3 (2026-08-15)

- 默认 Gradient hover 改为按需挂载四个模块缓存的预栅格 SVG 图层，不再创建运行时 filter DOM；活动 Gradient 同时继承共享视口暂停能力。

### v2.12.2 (2026-08-15)

- 将 Avatar hover alpha 艺术色与 Gradient、GradientMotion 的画面艺术色分项登记；Avatar 自身的例外只拥有图片与普通组件 fallback 的六色 hover 染色。

### v2.12.1 (2026-08-15)

- 登记默认 Gradient 与图片 / 普通组件头像 hover 六色为专业艺术色例外；边界以 StyleSpec §2.1.3 为准。

### v2.12.0 (2026-08-06)

- 默认 Gradient fallback 常态不再为每个 Avatar 创建完整 Gradient 组件、实例 ID、hover 状态与响应式派生链，只渲染共享静态图。
- hover 时按需挂载完整 Gradient 水波与五色 Overlay，退出 0.5 秒后回收；`gradientMotion` 继续显式常驻完整 Gradient。
- 静态图使用原生 lazy loading、异步解码和低请求优先级，长表格只优先处理视口附近头像。

### v2.11.1 (2026-08-03)

- 修复外部传入的 Badge / Icon 子内容被内部 Frame `children` 片段同名遮蔽、未进入 DOM 的问题。
- Avatar 根盒统一使用 `vertical-align: middle`，使 `empty`、图片与 Gradient 头像在同一行保持一致的垂直位置。

### v2.11.0 (2026-08-03)

- 默认 Gradient fallback 的四层水波改为七段非对称闭环路径，避免可见的 A→B→A 原路折返。
- 每次 hover 从六组相位 / 方向组合中随机选择且不重复上一组；不增加活动图层、filter 或逐帧 JavaScript。

### v2.10.0 (2026-08-02)

- 默认 Gradient Avatar 常态继续使用缓存静态图，hover 时由 Gradient 按需淡入四层独立周期的水波形变；离开后释放实时 SVG 与 filter。
- `gradientMotion` 语义收窄为“是否常驻运行”，不再阻止默认 hover 的按需水波形变。

### v2.9.1 (2026-08-02)

- 默认 Gradient fallback 的四层基础矢量形变改为关闭，新增 `gradientMotion` 显式开启入口。
- Gradient 自有的认可版本五色 Overlay hover 不受基础形变开关影响。

### v2.9.0 (2026-08-02)

- 根据认可版本的原始运行条件，默认 Gradient 头像恢复 `.snowui-media-hoverable`、`.snowui-media-hoverable-has-visual` 与 `.snowui-media-hoverable-visual` 三层契约。
- Gradient 重新位于普通 visual 容器内并同时获得旧版 `brightness(0.92)` 反馈；仍跳过 Avatar 当前的单色 alpha filter，图片、Logo 与其他 fallback 保持现状。

### v2.8.0 (2026-08-02)

- 默认 Gradient fallback 改用专用直连渲染路径，不再经过普通 `.snowui-avatar-visual` 与 Avatar SVG 单色滤镜合成层。
- Gradient 直接成为圆形裁切容器的视觉内容；Avatar 只负责尺寸、最外层裁切、hover 状态与 Badge，Gradient 自行管理 SVG、颜色顺序和双层 Overlay。
- 图片、Logo 与其他组件 fallback 继续使用 Avatar 原有 visual / alpha filter hover，不受此分支影响。

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

### v2.7.0 (2026-08-02)

- 删除自动首字母生成；无显式图片 / fallback / fallbackText 时默认渲染按名称或实例 seed 分散配色的 Gradient。
- 新增 `variant="empty"`，承接原灰色背景与用户图标空头像视觉。
- Avatar 单色随机 hover 改用 SVG flood + alpha composite，只染图片或普通组件实际绘制的非透明像素。
- Gradient fallback 恢复自身多色循环，Avatar 对其跳过单色滤镜，避免双重叠加。

### v2.6.0 (2026-08-02)

- 默认 hover 从五色双层持续循环简化为单层 Overlay；每次 pointer enter 随机六色之一，同一次 hover 内颜色固定。
- 每次 pointer enter 都独立从六种颜色中等概率抽取，同一次 hover 内颜色固定。
- 默认首字母、fallbackText 和用户图标提升到 Overlay 上方，避免文字与图标被染色。
- 删除十层 opacity 动画，只保留一个 0.5s opacity 过渡层。

### v2.5.0 (2026-08-02)

- 将 Gradient avatar-image 专用 hover 完整迁移到 Avatar，作为所有 Avatar 视觉状态的默认 hover。
- 删除 Avatar 对共享 media-hoverable brightness / 背景加深分支的消费，避免双重反馈。
- Avatar 自行管理随机五色、双层 Overlay、10s 循环、0.5s 入口缓冲、disabled 与 reduced-motion。

### v2.4.19 (2026-06-10)

#### 新功能
- 新增 `fallback` 组件入口，支持将 `GradientMotion` 等视觉组件作为默认头像。
- 新增 `as="avatar-image"` 角色化组合说明，头像图片层可覆盖默认回退并保留 badge overlay。

### v2.4.18 (2026-03-15)

#### 修复
- **AV-Docs.1** 统一代码头、文档头与 changelog 版本号为 `v2.4.18`。
- **AV-Style.8** 移除 Avatar 内部对 `--snowui-frame-hover-image-override` 的定义，改为组件自身 hover 规则关闭背景叠加，并补齐模板 `data-disabled` 输出，保持禁用态选择器与模板同步。

### v2.4.12 (2026-03-06)

#### 调整
- **AV-Hover.1** 恢复 Avatar 旧版 hover 视觉分层：图片模式压暗 `.snowui-avatar-visual`，首字母模式压暗 `.snowui-avatar-background`，默认回退模式仅做背景色过渡。
- **AV-Hover.2** 保留 `.snowui-hoverable` 语义，改用 `--snowui-avatar-hover-image-override` 的声明式覆写关闭默认 hover 叠加层。
- **AV-Hover.3** 所有 hover 规则统一排除禁用态，确保 `disabled` 时无额外 hover 反馈。

### v2.4.10 (2026-02-18)

#### 调整
- **AV-Typography.1** 组件内回退文本、首字母与根容器行高统一改为 `line-height: 1`，保留字号比例链路不变。
- **AV-HTML.1** 根节点样式变量改为按需注入：默认 `container/text` 尺寸因子由组件 CSS 提供，不再在默认态输出内联 `style`。

### v2.4.8 (2026-02-13)

#### 优化
- **AV-Style.6** 微调角标比例：`DOT_SIZE_RATIO` 调整为 `0.28`，`DOT_BORDER_RATIO` 调整为 `0.1`，确保视觉更紧凑。
- **AV-Style.7** 闭环比例计算：角标尺寸与切割中心、偏移量均通过比例常数动态计算，适配所有头像尺寸。
- **AV-Refactor.6** 代码格式化：优化 CSS 锁定类声明格式。

### v2.3.7 (2026-02-13)

#### 修复
- **AV-Fix.13** 定位并修复尺寸倍增根因：Avatar 尺寸链路中 `--text-scale` 与 `--size-scale` 参与计算后导致放大。现通过归一化计算抵消全局系数影响。
- **AV-Fix.14** 保持纯 Token 实现前提下，确保 `size` 与容器实际尺寸一致，并保留单一比例文字联动。

#### 根因说明
- `--size` 基于 `em`，而 `em` 又受组件 `font-size` 影响；同时 `--text` 与 `--size` 各自有全局 scale 系数。
- 在 Avatar 旧链路中，容器尺寸会隐式叠乘全局系数，表现为约 3 倍放大。

### v2.3.8 (2026-02-13)

#### 修复
- **AV-Fix.15** 定位到真实根因为样式优先级冲突：Avatar 根节点内联 `style` 中的 `width/height`（Level 6）覆盖了 `.snowui-avatar-lock-size`（Level 4）归一化规则，导致锁定逻辑失效。
- 调整为仅在内联样式输出组件变量，不再输出 `width/height`；宽高统一回到组件 CSS 规则计算，保证锁定类可生效并符合 `StyleSpec` 优先级体系。

### v2.3.9 (2026-02-13)

#### 修复
- **AV-Fix.16** 修复 `lock-size` 条件误判：仅当 `sizeRatio/avatarSizeRatio` 为有效数值时才跟随 scale，避免 `null/空值` 透传导致未加锁定类。
- **AV-Fix.17** 在锁定模式下同步锁定 `min/max width/height`，防止外部最小尺寸约束把头像容器撑大。

### v2.3.10 (2026-02-13)

#### 修复
- **AV-Fix.18** 容器尺寸主链路由 `--size(em)` 切换为归一化 `--text` 长度链路，避免 `em` 在复杂上下文中被额外 font-size 影响而出现倍增。
- **AV-Fix.19** 回退文字与首字母字号同步使用归一化 `--text` 链路，继续保持与头像容器的单一比例（约 0.375）。

#### 说明
- 当 Token 基准 `--size` 以 `em` 定义时，理论上会受当前元素最终 `font-size` 影响；在存在外部样式或级联覆盖时，可能与预期比例发生偏移。
- 当前实现仍属于纯 Token 方案（未引入 px 常量），但改用更稳定的归一化长度基准来保证 Avatar 容器语义尺寸稳定。

### v2.4.0 (2026-02-13)

#### 修复
- **AV-Fix.20** 最终收敛到“固定尺寸语义 Token”方案：Avatar 容器尺寸改为 `var(--size-fixed) * factor`，文本改为 `var(--text-fixed) * factor`。
- **AV-Fix.21** `tokens.css` 新增 `--size-fixed`（4px）与 `--text-fixed`（16px）作为组件内“绝对语义”基准，避免宿主页面修改 `html font-size` 时 Avatar 尺寸随之放大。

#### 关键说明（为何此前纯 Token 链路无法稳定）
- 现有基础 Token `--size` 使用 `em`，`--text` 使用 `rem`。当宿主页面存在根字号放大时，Avatar 的 16/20/24 等“固定像素语义”会被整体放大。
- 因此，在不回退到组件内硬编码 `px` 的前提下，需要在 Token 层提供“绝对语义基准”并由 Avatar 使用。

### v2.4.1 (2026-02-13)

#### 修复
- **AV-Fix.22** 增加内联尺寸硬锁（仍基于 Token 变量）：根节点内联输出 `font-size/width/height/min/max`，确保外部级联无法改写 Avatar 容器语义尺寸。

#### 调试标记
- 根节点新增 `data-avatar-version="2.4.1-inline-lock"`，用于确认页面是否加载到最新 Avatar 实现。

### v2.4.2 (2026-02-13)

#### 规范回归
- **AV-Refactor.3** 移除临时调试用内联尺寸硬锁与版本标记，恢复为组件 CSS（Level 2/4）控制尺寸，符合 `StyleSpec.md` 优先级规范。
- 保留 Token 语义方案：容器与文字继续使用 `tokens.css` 中的固定语义基准变量（`--size-fixed` / `--text-fixed`）进行计算。

### v2.4.3 (2026-02-13)

#### 规范修正
- **AV-Refactor.4** 移除 `--size-fixed` / `--text-fixed` 方案，回归标准 Token：`--size` / `--text`。
- 继续保留归一化计算（抵消 `--size-scale` / `--text-scale`）与 `lock-size` 策略，确保尺寸稳定且符合 `StyleSpec`。

### v2.4.4 (2026-02-13)

#### 规范修正
- **AV-Refactor.5** 移除 Avatar 中对 `--size-scale` / `--text-scale` 的直接计算，改为仅使用标准基准 Token `--size` / `--text` 参与尺寸与字号计算。

### v2.4.5 (2026-02-13)

#### 修复
- **AV-Fix.23** 调整 Avatar 角标上下文默认 dot 尺寸，使 `<Badge as="badge" />` 在 Avatar 中与 Badge 单独使用的默认点尺寸保持一致，避免出现“Avatar 内点徽标尺寸偏差”。

### v2.4.6 (2026-02-13)

#### 修复
- **AV-Fix.24** `Badge as="badge"` 在 Avatar 内改为按头像容器尺寸等比缩放：默认 `badgeSize` 由固定值改为 `containerSize * ratio`。
- **AV-Fix.25** 同步调整 Avatar dot cutout 的遮罩半径与定位计算，确保缩放后徽标与切割位置保持一致。

### v2.4.7 (2026-02-13)

#### 修复
- **AV-Fix.26** 恢复切割边框视觉粗细：将 dot 边框厚度改为随 dot 尺寸同比缩放，并沿用旧版粗细比例（`0.04 / 0.25 = 0.16`）。
- **AV-Fix.27** `badgeStyle` 的 top/right inset 与 cutout 半径统一改为同一边框比例链路，避免大尺寸头像下边框显得过细。

### v2.3.6 (2026-02-13)

#### 重构
- **AV-Refactor.1** 按需求回退到纯 Token 实现：移除 `px` 尺寸变量，恢复 `width/height/font-size` 的 Token 计算链路。
- **AV-Refactor.2** 保持 `size` 语义不变（控制头像容器尺寸）以及单一比例（约 `0.375`）的文本联动。

### v2.3.5 (2026-02-13)

#### 修复
- **AV-Fix.12** 进一步屏蔽全局缩放系数影响：Avatar 容器尺寸与回退文字尺寸统一改为 `px` 变量驱动，避免 `--size-scale`/`--text-scale` 引发的倍数放大。
- **比例保持**: 容器与文字继续使用单一比例（约 `0.375`）联动，满足“近似比例”要求。

#### 说明
- 在 SnowUI 里，`--size`/`--text` 是可被全局系数放大的 Token。如果主题或容器环境修改了 `--size-scale`/`--text-scale`，纯 Token 映射会按设计同比放大。
- 若业务要求 Avatar 尺寸始终等于传入 `size`（绝对像素），需要像当前方案一样走组件内绝对尺寸变量，或新增“不受全局 scale 影响”的专用 Token。

### v2.3.4 (2026-02-13)

#### 修复
- **AV-Fix.11** 按排查策略先屏蔽 Scale：将 Avatar 容器宽高改为内联 `style` 输出，阻断父级 `.snowui-scale` 对 `.snowui-avatar` 宽高的级联覆盖。
- **规范说明**: 内联样式仅用于 `width/height` 动态尺寸，符合 `StyleSpec.md` 2.9 允许场景。

### v2.3.3 (2026-02-13)

#### 修复
- **AV-Fix.10** 修复父级 `Frame` 开启 `scale apply` 时 Avatar 被级联放大的问题：默认启用容器尺寸锁定，保持 `size` 语义稳定。
- **兼容增强**: 当显式传入 `sizeRatio` 或 `avatarSizeRatio` 时，Avatar 允许跟随 Scale 链路。

### v2.3.2 (2026-02-13)

#### 修复
- **AV-Fix.8** 修复头像容器尺寸异常放大（约 3x）问题：容器尺寸改为 `size` 到 Token 因子的直接映射（`size / 4`）。
- **AV-Fix.9** 统一头像与文字的比例链路：内部文字/默认图标改为单一比例变量（约 `0.375`）驱动。
- **语义澄清**: `size` 明确表示头像容器尺寸，不等同于图片素材分辨率尺寸。

### v2.3.1 (2026-02-13)

#### 修复
- **AV-Fix.7** 修正了 Token 联动下的比例系数计算错误，彻底解决了 3x 漂移顽疾。
- **规范适配**: 移除内联 `font-size: 1rem`，改由 CSS 锚定以对齐 `StyleSpec.md` 2.9。

#### 重构
- **Token 对齐**: 全面回归 `tokens.css` 体系。
- **规范适配**: 遵循 `StyleSpec.md` 的权重、优先级与单位规范。
- **锚点锁定**: 修复 3x 漂移顽疾，通过 `font-size: 1rem` 锚定 `em` 基准。
- **比例优化**: 调整内部比例为 32:12 (0.375)。

### v2.2.0 (2026-02-12)

#### 重构
- 支持等比缩放：锁定头像与文字比例为 0.625
- 规范单位使用：头像大小使用 em，文字大小使用 rem
- 移除硬编码 sizeMap

### v2.1.25 (2026-02-05)

#### 样式优化
- **AV-Style.5** 默认头像 hover 仅背景过渡，图标不变色；图片模式滤镜仅在图片模式触发

### v2.1.26 (2026-02-05)

#### 架构重构
- **Size Context**: 支持从 `Frame` 上下文读取 `size`。当未显式传入 `size` 属性时，将自动使用上下文尺寸。
- **高分适配**: 修正了资源组件（Resource Component）的尺寸传递逻辑，确保 3x 高清资源能根据实际显示尺寸正确加载。

### v2.1.15 (2026-02-03)

#### 修复
- **AV-Fix.6** 移除跨组件内部变量写入，避免命名冲突

### v2.1.14 (2026-02-03)

#### 修复
- **AV-Fix.5** AvatarGroup 相关内部变量命名对齐 snowui 规范

### v2.1.13 (2026-02-03)

#### 修复
- **AV-Fix.4** 仅在显式 size 时写入 AvatarGroup 尺寸变量，避免影响间距计算

### v2.1.12 (2026-02-03)

#### 修复
- **AV-Fix.3** 修复 size 检测导致的运行时递归问题

### v2.1.11 (2026-02-03)

#### 新功能
- **AV-Feat.1** 当未显式传入 `size` 时，允许 AvatarGroup 的 `size` 作为默认尺寸

### v2.1.10 (2026-02-03)

#### 修复
- **AV-Fix.2** 仅在存在样式时输出 `style`，避免空属性

### v2.1.9 (2026-02-03)

#### 修复
- **AV-Fix.1** 尺寸映射改为使用 `--size-*` Token 变量

### v2.1.8 (2026-02-03)

#### 样式优化
- **AV-Style.4** 首字母回退改为单字母，字号与默认图标一致，背景色来自次要色 token，文字使用 static white

### v2.1.1 (2026-02-03)

#### 样式优化
- **AV-Style.3** 图片模式移除容器底色，Hover 仅作用图像

### v2.1.0 (2026-02-03)

#### 样式优化
- **AV-Style.2** Hover 改为图像亮度滤镜，适配不规则图形

### v2.0.0 (2026-02-03)

#### 破坏性变更
- **AV-Break.1** 移除 `variant` / `alt` / `fallback` / `delayMs` Props，统一由内部规则与外部样式控制

#### 样式优化
- **AV-Style.1** 明确默认圆角为 `50%`，外部样式可覆盖

#### 文档完善
- **AV-Doc.1** 更新样式与行为说明以匹配新 API