Avatar 头像
表示一个人或一个组织的圆形标识：优先显示图片，无法加载时回退到文字或图标。
用法
图片加载失败或未提供时落到 fallback
曦组件结构
加粗的是必需部件。
data-scope="avatar"：root · image · fallback
示例
加载失败回退
图片地址取不到时切到 fallback，切换由状态机决定而不是 CSS
回退尺寸
size 三档只改变直径，回退文字的字号随之缩放；默认档不输出 data-size
曦曦曦sm / 缺省 / lg形状
圆角是一个组件令牌，整圆、圆角方、直角都是同一个槽位换值；图片的圆角从根继承，不必另设
曦曦曦整圆（缺省）/ 圆角方 / 直角图标作为回退
fallback 是普通插槽，放图标与放缩写文字一样；没有名字可写时用图标表示某位用户
自定义直径与配色
三档之外的直径、底色、字色各是一个组件令牌；按人名分配颜色即逐个实例覆盖
曦加载状态
status-change 在状态落位时通知，过渡态 idle 不通知；未提供地址等同于无法获取，直接落为 error 由回退接管
曦地址有效 → 等待中回退地址取不到 → 等待中颜色
tone 改变淡底与回退文字的配色组；不写 tone 即中性默认，直径与字号都不受影响
设计指引
何时使用
- 在列表、评论、成员选择中标识身份。
何时不用
特性
- 加载状态通过回调通知；失败时自动显示
fallback。 - 直径与配色都是组件令牌，可逐实例覆盖。
tone切换淡底与回退文字的配色族；未设置时使用中性默认值。- 状态点与角标由作者挂在外部，组件不预设。
组合
最佳实践
- 回退内容应有意义：姓名缩写比通用人形图标携带更多信息。
alt写人名，不写“头像”。
反模式
- 只提供图片、不提供回退：图片失效后会留下空洞。
- 只用头像颜色编码身份而不提供文字。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-avatar> |
| Vue 组件 | XhAvatarFallback XhAvatarImage XhAvatarRoot |
| 组合式函数 | useAvatar |
| 状态机 | avatarMachine |
| 皮肤 | @xihan-ui/styles/avatar.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
src | string | ||
alt | string | ||
size | Size | 尺寸：sm / md / lg，默认 md；默认档不输出 data-size | |
tone | Tone | 颜色：决定底色与回退字使用哪组状态色；未提供时不输出 data-tone，使用皮肤的中性默认 | |
onStatusChange | (details: AvatarStatusChangeDetails) => void | 状态落定时通知，过渡态 idle 不通知。 |
事件
自定义元素将载荷放在 detail；Vue 使用同名 emit。
| 事件 | 载荷 | 说明 |
|---|---|---|
status-change | AvatarStatusChangeDetails | 加载状态变化；detail 为 { status: 'loading' | 'loaded' | 'error' } |
状态
公开状态写入 data-state。
| 部件 | 取值 |
|---|---|
root | 'idle' | 'loading' | 'loaded' | 'error' |
image | 'idle' | 'loading' | 'loaded' | 'error' |
fallback | 'idle' | 'loading' | 'loaded' | 'error' |
以下名称仅用于内部状态机。
状态：idle · loading · loaded · error
事件：SRC.CHANGE · IMAGE.LOAD · IMAGE.ERROR
判据：hasSrc
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
status | AvatarStatus | |
loaded | boolean | |
getRootProps | () => T['element'] | |
getImageProps | () => T['img'] | |
getFallbackProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
样式参考
皮肤
@xihan-ui/styles/avatar.css 使用 [data-scope="avatar"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-size | props.size |
root | data-state | 'idle' | 'loading' | 'loaded' | 'error' |
root | data-tone | props.tone |
image | data-state | 'idle' | 'loading' | 'loaded' | 'error' |
fallback | data-state | 'idle' | 'loading' | 'loaded' | 'error' |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-avatar-bg | root | background | defaulttone | --xh-_tone-subtle--xh-bg-subtle-opaque | avatar 的 root 部件 background 覆盖槽。 |
--xh-avatar-fg | root | color | defaulttone | --xh-_tone-fg--xh-fg-muted | avatar 的 root 部件 color 覆盖槽。 |
--xh-avatar-font-size | root | font-size | defaultsize=lgsize=sm | --xh-control-caption-lg--xh-control-caption-sm--xh-text-secondary-size | avatar 的 root 部件 font-size 覆盖槽。 |
--xh-avatar-font-weight | root | font-weight | default | --xh-font-weight-medium | avatar 的 root 部件 font-weight 覆盖槽。 |
--xh-avatar-radius | root | border-radius | default | --xh-shape-circle | avatar 的 root 部件 border-radius 覆盖槽。 |
--xh-avatar-size | root | block-sizeinline-size | defaultsize=lgsize=sm | --xh-control-h-lg--xh-control-h-md--xh-control-h-sm | avatar 的 root 部件 block-size、inline-size 覆盖槽。 |
动效
动效角色：出现（见动效规范）。
共享关键帧 xh-fade-in 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立。时长与缓动读动效令牌，改令牌即改全局节奏。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。