For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/v0.4.0/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/v0.4.0/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/v0.4.0/components/avatar.md.
A3S UI
  • 简体中文
  • v0.4.0

      • 头像

      头像用照片或稳定的后备标识帮助用户快速识别人、团队或自动化身份；它补充可见名称，不代替名称。

      实时预览

      林然

      界面工程 · 在线

      +3
      6 人参与

      用法

      引入 CSS

      导入 Tailwind 和完整样式包。

      @import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

      也可以只导入基础样式、头像组件和一个样式包。

      @import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/avatar.css";
@import "@a3s-lab/ui/styles/a3s.css";

      添加头像 HTML

      由根元素提供稳定名称；图片使用空 alt，后备首字母对读屏隐藏。这样图片加载成功或失败时都只读一次身份。

      <span class="avatar" role="img" aria-label="林然" data-state="ready">
  <img src="/people/lin-ran.jpg" alt="" />
  <span aria-hidden="true">LR</span>
</span>

      图片加载失败后由宿主把 data-state 改为 fallback。组件会隐藏失败图片并显示后备内容。

      HTML 结构

      元素或属性必填用途
      <span class="avatar">是单个身份的行内根元素
      role="img" 与 aria-label独立头像提供不随图片状态变化的身份名称
      直接子 <img alt="">可选照片；空替代文本避免与根名称重复
      直接子 <span aria-hidden="true">是首字母、图标或其他后备标识
      data-stateready、fallback由宿主同步图片加载结果
      data-sizesm、省略、lg24px、32px、40px 三个稳定尺寸
      .avatar-badge可选角落状态提示，只作为辅助视觉信号
      .avatar-group可选直接排列多个头像与一个 data-count 汇总项

      状态与变体

      图片与后备标识

      后备内容不是错误提示，而是身份的等价视觉表示。首字母必须来自稳定名称，不能用随机颜色或无法解释的占位图标。

      实时预览
      林然
      陈墨

      尺寸

      尺寸表达界面密度，不表达用户等级。列表使用小号或默认尺寸，账户入口和身份摘要可使用大号。

      实时预览

      状态与头像组

      角落徽点不能单独承担“在线”“忙碌”等含义；在附近保留可见状态文本。头像组显示有限数量并用汇总项说明其余成员，不能把几十个头像全部堆叠。

      实时预览
      林然 · 在线
      +3

      交互入口

      头像本身不是按钮。需要打开账户菜单时，把头像放进真实按钮，并由按钮命名操作；按钮内的头像设为装饰，避免重复朗读。

      实时预览

      RTL

      头像照片和首字母不镜像。头像组通过逻辑方向调整重叠顺序，身份名称仍由各自语言决定。

      实时预览
      +2
      فريق المراجعة

      可访问性

      独立头像由根元素提供一个稳定名称，图片 alt 为空、后备内容 aria-hidden="true"，避免图片和首字母被重复朗读。头像紧邻同名文本时，可以把整个头像设为 aria-hidden="true"。状态徽点只作视觉补充，在线、忙碌或离线必须同时有文字。可点击头像必须由外层按钮或链接承担名称、焦点和键盘行为。宿主负责身份数据、图片授权、加载失败、隐私与状态真实性；组件只负责呈现，不应根据头像颜色推断角色、在线状态或权限。