Avatar 头像
Data Display
智能自动检测
简介
基于图像的UserProfile元素，用于展示自定义图形标识。当图片源被省略、正在加载或加载失败时，它会优雅地回退到格式化的姓名首字母或通用占位图标。主要用于个人资料导航触发器、消息列表、评论和社区名录。
Avatar 组件已作为 avatar 区块完整集成到 Page Builder 中，内容作者和开发者可以直接在 CMS 内轻松配置个人资料路径、尺寸比例和视觉主题。
用法
以下示例展示了内容编辑者如何绑定和构建头像组件。
1. 高保真个人资料头像（带图片源）
加载高分辨率用户图片。自动处理后台网络加载，并在解析完成后以动画形式呈现。
{
"type": "avatar",
"src": "https://images.unsplash.com/photo-1534528741775-53994a69daeb?q=80&w=200&auto=format&fit=crop",
"name": "Jane Doe",
"size": "lg",
"interactive": true
}
JD
2. 强调首字母回退（不带图片源）
当个人资料图片缺失时，Avatar 会自动解析用户 name 属性，计算并渲染正确的姓名首字母（例如 "Jane Doe" -> "JD"），叠加在强调色主题之上。
{
"type": "avatar",
"name": "Jane Doe",
"variant": "solid",
"colorPalette": "blue",
"size": "md",
"interactive": true
}
JD
3. 圆角占位头像
当既未提供图片路径也未提供用户名时，渲染标准的圆角用户图标。
{
"type": "avatar",
"shape": "rounded",
"size": "md",
"interactive": true
}
属性
| 属性 | CMS 字段类型 | 默认值 | 说明 / 可选项 |
|---|---|---|---|
个人资料图片 (src) | image | - | 图片 URL 或相对资源路径。提供此项会触发 Tier-2 水合。 |
用户名 (name) | string | - | 账户用户名。解析首末字符以生成视觉首字母。 |
替换描述 (alt) | string | - | 供屏幕阅读器使用的图片替代文本描述。 |
尺寸比例 (size) | select | "md" | 控制头像的高度、宽度与首字母文本比例。 • 选项： "2xs"、"xs"、"sm"、"md"、"lg"、"xl"、"2xl"。 |
视觉变体 (variant) | select | "subtle" | 应用于回退首字母背景的样式叠加。 • 选项： "solid"、"surface"、"subtle"、"outline"。 |
圆角形状 (shape) | select | "full" | 头像边界的弯曲程度。 • 选项： "square"、"rounded"、"full"。 |
配色主题 (colorPalette) | select | "blue" | 用于回退背景主题的强调色。 • 选项： blue、green、red、purple、orange、amber、cyan、slate。 |
强制交互 (interactive) | boolean | true | 确保即时的客户端加载监控与平滑的回退过渡。 |
开发者说明与无障碍
- 水合岛屿： Avatar 作为 Tier-2 条件岛屿执行。如果未指定图片
src，它会直接编译为轻量静态标记，客户端 JS 占用为零。如果提供了src，它会在客户端进行水合，以自动管理异步加载周期（loading->loaded/error）。 - WAI-ARIA 合规： 在底层，回退首字母与图标在语义化
<span>标签内运行。如果头像仅用于装饰，请确保alt属性被省略或留空，以便屏幕阅读器跳过它。