---
url: /components/avatar.md
---
# Avatar 头像

头像组件：支持图片地址（加载失败自动回退到默认插槽）、文字内容与三档尺寸，圆形与方形两种形状；AvatarGroup 将相邻头像叠放显示，并统一向子头像注入 size / shape。头像也可与 Badge 组合显示未读数。

## 基础用法

`size` 传数字时按像素渲染（宽高与行高同步），传 small / default / large 走三档（24 / 40 / 56px）；`shape="square"` 切换方形。

## 文字头像

无 `src` 时直接渲染默认插槽内容，可通过样式定制底色与字号，常用于姓名首字、团队名。

## 加载失败回退

`src` 加载失败（onerror）时自动切换为默认插槽内容；未提供插槽则显示为空白底。`alt` 与 `srcSet` 透传给 img。

## 头像组叠放

AvatarGroup 统一注入 size 与 shape，相邻头像自动叠放并带背景描边；组内末尾常放置计数头像（如 +3）表示更多成员。

## 组内单项覆盖

子头像显式指定 size（非 default）时以子头像为准，可突出关键成员；shape 则由组统一决定，子级设置会被组覆盖。

## 与徽标组合

头像与 Badge 组合展示未读数或在线状态，Badge 自动定位到头像右上角。

## API