Avatar 头像

头像组件用于代表用户、实体或团队。它可以显示图片、缩写文字，也可以作为图标的载体。 借助头像列表容器，你还能轻松实现团队成员的堆叠展示。

基础用法

最常规的用法是传入 src 属性以显示一张图片。当图片加载失败或未提供图片时，组件会自动降级显示 text 属性中的文字。

💡 智能截取：如果文字包含中文，会自动截取第一个汉字；如果是纯英文，则截取前三个字母并大写。

<TAvatar src="/avatar.png"></TAvatar>
<TAvatar text="张三"></TAvatar>
<TAvatar text="Alex" color="blue-lt"></TAvatar>
<TAvatar text="WK" color="purple-lt"></TAvatar>
<TAvatar text="李四" src="/404.png"></TAvatar>

头像形状 (Shape)

组件默认使用轻微的圆角 (rounded)。

你可以通过设置 shape 属性将其修改为完全的圆形 (circle) 或直角方形 (square)。

<TAvatar src="/avatar.png" shape="rounded"></TAvatar>
<TAvatar src="/avatar.png" shape="circle"></TAvatar>
<TAvatar src="/avatar.png" shape="square"></TAvatar>

尺寸与大小 (Size)

我们提供了从 xs 到 xl 多种统一规格的尺寸。

选择最适合你页面布局的尺寸来保持层级分明。

<TAvatar src="/avatar.png" size="xs"></TAvatar>
<TAvatar src="/avatar.png" size="sm"></TAvatar>
<TAvatar src="/avatar.png" size="md"></TAvatar>
<TAvatar src="/avatar.png" size="lg"></TAvatar>
<TAvatar src="/avatar.png" size="xl"></TAvatar>

背景颜色 (Color)

对于文字降级头像，提供明确的背景色有助于区分不同的用户。

仅推荐使用 -lt 浅色变体。

<TAvatar text="A" color="primary-lt"></TAvatar>
<TAvatar text="B" color="success-lt"></TAvatar>
<TAvatar text="C" color="danger-lt"></TAvatar>
<TAvatar text="D" color="yellow-lt"></TAvatar>
<TAvatar text="E" color="indigo-lt"></TAvatar>

状态指示与徽章 (Status & Badges)

你可以为头像添加状态指示器，以显示用户的在线/离线状态，或者提示他们收到的消息数量。

得益于组件的组合性，你只需要将 TBadge 组件直接放入 TAvatar 的默认插槽中，它就会自动吸附到头像的边缘。

<TAvatar src="/avatar.png">
  <TBadge color="success"></TBadge>
</TAvatar>
<TAvatar text="SA">
  <TBadge color="warning"></TBadge>
</TAvatar>
<TAvatar src="/avatar.png">
  <TBadge color="danger"></TBadge>
</TAvatar>
<TAvatar shape="circle" src="/avatar.png">
  <TBadge color="danger">5</TBadge>
</TAvatar>

头像列表 (Avatar List)

当你需要展示一组关联的用户（例如：项目成员、点赞列表）时，请使用 TAvatarList 容器。

你可以直接在容器上统一下发 size 和 shape，内部的头像会自动继承。

<TAvatarList size="sm" shape="circle">
  <TAvatar text="赵" color="blue-lt"></TAvatar>
  <TAvatar text="钱" color="azure-lt"></TAvatar>
  <TAvatar text="孙" color="indigo-lt"></TAvatar>
  <TAvatar text="李" color="purple-lt"></TAvatar>
</TAvatarList>

堆叠与数量折叠 (Stacked & Max)

开启 stacked 属性后，列表内的头像会像扑克牌一样层叠显示，非常适合节省空间。

搭配 max 属性，你可以限制最多显示的头像数量。

多出的部分会自动被隐藏，并在末尾生成一个汇总标记（如 +3）。

<TAvatarList stacked :max="4" size="md" shape="circle">
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
  <TAvatar src="/avatar.png"></TAvatar>
</TAvatarList>

API

TAvatar 属性 (Props)

属性名	说明	类型	默认值
src	图片头像的 URL 地址。	string	undefined
text	当没有图片或图片加载失败时显示的替代文字。	string	'A'
alt	原生 img 的 alt 属性，或 aria-label。	string	'Avatar'
size	头像大小。（若被包裹在 List 中，优先使用 List 的尺寸）	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
shape	头像形状。（若被包裹在 List 中，优先使用 List 的形状）	'rounded'| 'square'| 'circle'	'rounded'
color	降级为文字显示时的背景色。支持主题色和 -lt 浅色变体。	TablerColor	undefined

TAvatarList 属性 (Props)

属性名	说明	类型	默认值
stacked	开启头像堆叠模式，头像将部分重叠展示以节省空间。	boolean	false
max	列表最大显示数量。超过此数量的头像将被隐藏，并显示 +N。	number	6
size	统一下发给内部所有头像的尺寸。	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
shape	统一下发给内部所有头像的形状。	'rounded' | 'square' | 'circle'	'rounded'