---
title: Avatar 头像
description: 代表用户身份的图片、首字母或图标
category: Basic
status: beta
since: 0.3.4
tags: [avatar, identity, profile]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
:::TuffDemoWrapper{demo="AvatarBasicDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar src="https://avatars.githubusercontent.com/u/1?v=4" alt="GitHub user" />
    <TxAvatar name="Talex 梦魂" />
    <TxAvatar icon="user" />
    <TxAvatar>张</TxAvatar>
  </template>
---
:::

### 尺寸
`size` 取预设名或自定义像素值。
:::TuffDemoWrapper{demo="AvatarSizesDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar size="small" name="Small" />
    <TxAvatar size="medium" name="Medium" />
    <TxAvatar size="large" name="Large" />
    <TxAvatar size="xlarge" name="Extra Large" />
    <TxAvatar :size="56" name="Custom Size" />
  </template>
---
:::

### 文字头像
:::TuffDemoWrapper{demo="AvatarTextDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar>张</TxAvatar>
    <TxAvatar>阿博</TxAvatar>
    <TxAvatar>用户</TxAvatar>
  </template>
---
:::

### 图标头像
:::TuffDemoWrapper{demo="AvatarIconDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar icon="user" />
    <TxAvatar icon="team" />
  </template>
---
:::

### 头像组
超过 `max` 的头像折叠为 `+N`。
:::TuffDemoWrapper{demo="AvatarGroupDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :max="3" size="small" :overlap="10">
      <TxAvatar name="Talex 梦魂" />
      <TxAvatar name="Alex Lee" />
      <TxAvatar name="Mira Chen" />
      <TxAvatar name="Noah Park" />
      <TxAvatar name="Lina Song" />
    </TxAvatarGroup>
  </template>
---
:::

### 悬浮效果
`hoverEffect` 控制单个头像的悬浮反馈，`spreadOnHover` 让整组悬浮时展开。
:::TuffDemoWrapper{demo="AvatarGroupHoverDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :overlap="12">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>

    <!-- 负的 spreadOverlap 在头像间留出间隙 -->
    <TxAvatarGroup :overlap="12" spread-on-hover :spread-overlap="-4">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>

    <TxAvatarGroup :overlap="12" hover-effect="none">
      <TxAvatar v-for="id in 5" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>
  </template>
---
:::

### 溢出浮层
`overflowPopover` 在 `+N` 上弹出被折叠的头像，`overflow` 插槽可替换面板内容。
:::TuffDemoWrapper{demo="AvatarGroupPopoverDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatarGroup :max="3" :overlap="12" overflow-popover>
      <TxAvatar v-for="id in 8" :key="id" :src="`https://avatars.githubusercontent.com/u/${id}?v=4`" />
    </TxAvatarGroup>
  </template>
---
:::

### 状态
:::TuffDemoWrapper{demo="AvatarStatusDemo" code-lang="vue"}
---
code: |
  <template>
    <TxAvatar status="online" name="在线" />
    <TxAvatar status="offline" name="离线" />
    <TxAvatar status="busy" name="忙碌" />
    <TxAvatar status="away" name="离开" />
  </template>
---
:::

### 最佳实践

- 生成身份标识时传 `name`，不要手写首字母。
- `src` 是真实用户图片时提供有意义的 `alt`。
- `status` 只表示在线状态；文字型系统状态用 `TxStatusBadge`。
- 组内显示 `status` 时加大 `overlap` 或开启 `spreadOnHover`，避免状态点被遮住。
- 溢出浮层只用于查看成员；需要操作成员时用列表组件。

## API 参考

### TxAvatar

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `src` | `string` | - | 图片地址；加载失败时回退。 |
| `alt` | `string` | - | 图片替代文本，`src` 为真实用户图片时提供。 |
| `name` | `string` | - | 用于生成首字母的名称。 |
| `icon` | `string` | - | 回退图标名，传给 `TxIcon`。 |
| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge' \| number \| \`${number}\` \| \`${number}px\`` | `'medium'` | 预设名或正数像素尺寸；无效值被忽略。 |
| `status` | `'online' \| 'offline' \| 'busy' \| 'away'` | - | 角落的状态点，位置随 `shape` 内缩。 |
| `shape` | `'circle' \| 'square' \| 'rounded'` | `'circle'` | 头像形状。 |
| `clickable` | `boolean` | `false` | 启用点击样式、按钮语义与 `click` 事件。 |
| `backgroundColor` | `string` | - | 回退内容的背景色。 |
| `textColor` | `string` | 设置 `backgroundColor` 时默认为 `'#ffffff'` | 回退内容的文字颜色；仅与 `backgroundColor` 一起生效。 |

#### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `click` | - | `clickable` 时点击或按 Enter / Space 触发。 |

#### 插槽

| 插槽名 | Props | 说明 |
|------|------|------|
| `default` | - | 自定义回退内容，优先于 `icon` 与 `name`。 |

### TxAvatarGroup

#### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `max` | `number` | 子节点数量 | 折叠为 `+N` 前最多显示的头像数；负数按 0 处理。 |
| `size` | `AvatarSize` | - | 注入未自行设置 `size` 的子头像。 |
| `overlap` | `number \| string` | `8` | 相邻头像的重叠距离，数字按 px 计。 |
| `hoverEffect` | `'none' \| 'lift'` | `'lift'` | 单个头像的悬浮反馈；`lift` 上浮、加阴影并置顶。 |
| `spreadOnHover` | `boolean` | `false` | 整组悬浮时把重叠过渡到 `spreadOverlap`。 |
| `spreadOverlap` | `number \| string` | `0` | 展开后的重叠距离，负值留出间隙。 |
| `overflowPopover` | `boolean` | `false` | 在 `+N` 上挂载溢出浮层。 |
| `overflowPopoverTrigger` | `'hover' \| 'click'` | `'hover'` | 浮层触发方式。 |
| `overflowPopoverPlacement` | `PopoverPlacement` | `'top'` | 浮层相对 `+N` 的位置。 |

#### 插槽

| 插槽名 | Props | 说明 |
|------|------|------|
| `default` | - | `TxAvatar` 或兼容的头像 VNode。 |
| `overflow` | `{ nodes: VNode[], count: number }` | 溢出浮层的面板内容；`nodes` 为被 `max` 截掉的头像。 |

## 概述

- 内容按图片、默认插槽、`icon`、`name` 首字母、默认 `user` 图标的顺序回退；图片加载失败同样回退。
- 首字母取第一个与最后一个单词的首字符，并转为大写。
- `clickable` 时根节点带 `role="button"` 与 `tabindex="0"`，Enter / Space 与点击一样触发 `click`。
- 组内 `z-index` 自左向右递增，右侧头像盖住左侧头像的右下角（含状态点）；`lift` 将悬浮头像置顶。
- 开启 `overflowPopover` 且有溢出时，`+N` 由 `TxPopover` 包裹；否则是普通头像，不产生浮层。
- 减少动态效果时取消悬浮位移与过渡，保留置顶与阴影。

## 技术实现

- 根节点不裁切，裁切在图片与回退层上，状态点因此能伸出形状。
- 组内的负 margin 与 `z-index` 来自样式表（`--tx-avatar-group-overlap`、`--tx-avatar-group-index`），子头像只内联描边。
- 源码：`packages/tuffex/packages/components/src/avatar/`。

<TuffDocSourceLink />

## 自定义

| 变量 | 写入方 | 用途 |
|------|--------|------|
| `--tx-avatar-size` | 自定义 `size` | 宽高。 |
| `--tx-avatar-font-size` | 自定义 `size` | 回退文字与图标字号。 |
| `--tx-avatar-status-size` | 自定义 `size` | 状态点外径（含描边）。 |
| `--tx-avatar-status-border` | 自定义 `size` | 状态点描边宽度。 |
| `--tx-avatar-bg` | `backgroundColor` | 回退背景色。 |
| `--tx-avatar-text` | `textColor`（需 `backgroundColor`） | 回退文字颜色。 |
| `--tx-avatar-ring` | 调用方 / 主题 | 状态点与组内头像的描边色，默认 `--tx-bg-color`。 |
| `--tx-avatar-group-overlap` | `overlap` | 解析后的重叠距离。 |
| `--tx-avatar-group-spread-overlap` | `spreadOverlap` | 展开后的重叠距离。 |
| `--tx-avatar-group-hover-z` | 调用方 / 主题 | 悬浮置顶的 `z-index`，默认 `999`。 |
| `--tx-avatar-group-overflow-width` | 调用方 / 主题 | 溢出面板换行前的最大宽度，默认 `232px`。 |
| `--tx-avatar-group-border` | 调用方 / 主题 | 组内头像的描边色。 |

`--tx-avatar-*-preset`、`--tx-avatar-status-diameter`、`--tx-avatar-status-ring`、`--tx-avatar-status-inset`、`--tx-avatar-group-gap`、`--tx-avatar-group-index`、`--tx-avatar-group-more-z` 是内部变量，不要直接设置。