Avatar 头像

表示一个人或一个组织的圆形标识：优先显示图片，无法加载时回退到文字或图标。

HeadlessStylesVueReactWeb Components

用法

图片加载失败或未提供时落到 fallback

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

组件结构

加粗的是必需部件。

data-scope="avatar"：root · image · fallback

示例

加载失败回退

图片地址取不到时切到 fallback，切换由状态机决定而不是 CSS

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

尺寸

size 三档只改变直径，回退文字的字号随之缩放；默认档不输出 data-size

sm / 缺省 / lg

回退字随档位缩放

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

形状

圆角是一个组件令牌，整圆、圆角方、直角都是同一个槽位换值；图片的圆角从根继承，不必另设

整圆（缺省）/ 圆角方 / 直角

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

图标作为回退

fallback 是普通插槽，放图标与放缩写文字一样；没有名字可写时用图标表示某位用户

图元跟着档位一起换，取的是根流下来的前景色

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

自定义直径与配色

三档之外的直径、底色、字色各是一个组件令牌；按人名分配颜色即逐个实例覆盖

直径 56px

底色与字色逐个给

主题跟随站点浅色深色密度宽松紧凑对比度基线高对比方向从左到右从右到左

加载状态

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，使用皮肤的中性默认
fallbackDelay	number		回退内容延迟多久才露面（毫秒），默认 300。图片在这段时间里载好就直接出图，不先闪一下首字母—— 缓存命中与虚拟列表回收行时尤其明显。没有 src 或载入失败时回退内容立即露面，不等。
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 · FALLBACK.DUE · FALLBACK.RENDERED

判据：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"] 部件选择器书写，发布产物以挂载类 .xh-scope-avatar 代替其中的 data-scope（特异性相同），位于 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	default tone	--xh-_tone-subtle --xh-bg-subtle-active-opaque	avatar 的 root 部件 background 覆盖槽。
--xh-avatar-fg	root	color	default tone	--xh-_tone-fg --xh-fg-default	avatar 的 root 部件 color 覆盖槽。
--xh-avatar-font-size	root	font-size	default	--xh-_avatar-font-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-size font-size inline-size	default size=lg size=sm	--xh-control-h-lg --xh-control-h-md --xh-control-h-sm	avatar 的 root 部件 block-size、font-size、inline-size 覆盖槽。

动效

动效角色：出现（见动效规范）。

共享关键帧 xh-fade-in · xh-fade-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立。时长与缓动读动效令牌，改令牌即改全局节奏。

系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。