Avatar
表示用户、组织或对象身份。中文惯用名：头像。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.avatar |
| 名称 | Avatar |
| 二级分类 | 通用（general） |
| 用途 | 表示用户、组织或对象身份 |
| 描述 | 中文惯用名：头像。 |
预览
静态结构：Base UI Avatar.Root（data-slot="avatar"，size-8 rounded-full overflow-hidden）；src 存在时渲染 avatar-image（data-slot="avatar-image"，size-full object-cover），fallback 存在时渲染 avatar-fallback（data-slot="avatar-fallback"，bg-muted 居中弱化文本），图片加载中 / 失败由原语自动回落到 fallback；默认尺寸 size-8（32px），更大 / 更小经 className 覆盖；src 与 fallback 均缺省时只剩空容器。
DSL 结构
{
"type": "Avatar",
"props": {
"src": "https://i.pravatar.cc/64",
"alt": "用户头像",
"fallback": "张"
}
}何时用
何时使用
- 表示用户、组织或对象身份：头部用户区、评论作者、成员列表、任务负责人。
- 图片缺失或加载失败时的稳定占位：fallback 提供首字母 / 简称，避免布局跳动。
- 需要与姓名并排的紧凑身份标识：配合 Flex 的 gap 排列。
何时不用
- 单纯展示图片内容（封面、截图、插图）：使用 Image。
- 需要展示身份详情（姓名 + 角色 + 联系方式）：用 Card、Descriptions 承接，Avatar 只做标识。
- 需要可点击进入个人主页时，外层用 Button / Link 承载交互，Avatar 本身不承载。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 图片头像 | 圆形裁切照片（object-cover） | 用户 / 组织有头像资源 |
| 文本兜底 | 灰底居中首字母或简称 | 无头像资源时的默认身份标识 |
| 加载失败回落 | 自动切到 fallback（不出现破图） | 外链头像失效、内网资源不可达 |
| 自定义尺寸 | 经 className 覆盖 size-8 | 头部大号身份区 / 列表小号标识 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | — | 图片地址 |
alt | string | — | 图片替代文本（缺省空字符串，纯装饰时不朗读） |
fallback | string | — | 加载失败或缺省时的占位文本（如首字母） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（尺寸常在此覆盖） |
使用规范
- 同时给 src 与 fallback：只给 src 时网络失败会留下空位。
- fallback 用姓名首字或对象简称，同一系统内规则统一（如统一取首字）。
- 作为纯装饰时 alt 留空；承载身份语义时写清对象名称。
- 头像尺寸跟随容器密度（8 的倍数），不逐处自定义奇数尺寸。
正例
- ✓ Header 用户区：Avatar src + fallback 首字母，右侧并排用户名。
- ✓ 成员列表：每行 Avatar 表示成员，小尺寸经 className 设定。
反例
- ✕ 用 Avatar 展示文章封面图（应使用 Image）。
- ✕ 不设 fallback 依赖外链头像可用（破图破坏布局与可信度）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。