定价

Avatar 更新日志

  • 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