> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# Avatar

数据展示`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

使用图片、文字或图标标识用户与实体。

组件采用 tao-ui 原生实现，公共 API 对齐 Ant Design 6.7.0。外观、主题 token 与 Semantic DOM 定制遵循 tao-ui，主题通过 `TaoProvider` 配置。

尺寸继承 TaoProvider；方形头像使用 tao-ui 圆角，分组溢出使用 tao-ui Popover。

## 何时使用

使用简短姓名缩写和有意义的图片替代文本；分组可展示团队成员。

## 代码演示


### 尺寸与形状
```tsx preview
import { Avatar } from "@rockshin/tao-ui";

export default function Example() {
  return (
    <div
      style={{
        display: "flex",
        gap: 16,
        alignItems: "center",
        flexWrap: "wrap",
      }}
    >
      <Avatar size="small">A</Avatar>
      <Avatar>AB</Avatar>
      <Avatar size="large">CD</Avatar>
      <Avatar size={64} shape="square">
        EF
      </Avatar>
    </div>
  );
}
```

### 图片与图标
```tsx preview
import { Avatar } from "@rockshin/tao-ui";

const image = `data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80"><rect width="80" height="80" fill="#365e67"/><circle cx="40" cy="30" r="14" fill="#e0c2a1"/><path d="M12 80V70a28 28 0 0 1 56 0v10" fill="#d7ded5"/></svg>')}`;

export default function Example() {
  return (
    <div
      style={{
        display: "flex",
        gap: 16,
        alignItems: "center",
        flexWrap: "wrap",
      }}
    >
      <Avatar size={48} src={image} alt="Abstract profile" />
      <Avatar icon={<span aria-hidden="true">◎</span>} aria-label="Guest" />
      <Avatar shape="square">RS</Avatar>
    </div>
  );
}
```

### 文字自动缩放
```tsx preview
import { useState } from "react";
import { Avatar, Button } from "@rockshin/tao-ui";

const labels = ["A", "Ada", "Lovelace"];

export default function Example() {
  const [index, setIndex] = useState(0);
  return (
    <div
      style={{
        display: "flex",
        gap: 16,
        alignItems: "center",
        flexWrap: "wrap",
      }}
    >
      <Avatar size={48} gap={6}>
        {labels[index]}
      </Avatar>
      <Button onClick={() => setIndex((index + 1) % labels.length)}>
        Change name
      </Button>
    </div>
  );
}
```

### 分组与溢出
```tsx preview="iframe-follow"
import { Avatar } from "@rockshin/tao-ui";

export default function Example() {
  return (
    <Avatar.Group
      size="large"
      max={{
        count: 3,
        popover: { trigger: "click" },
        style: { background: "var(--tao-color-fill-secondary)" },
      }}
    >
      {["AL", "BT", "CW", "DX", "EY"].map((name) => (
        <Avatar key={name}>{name}</Avatar>
      ))}
    </Avatar.Group>
  );
}
```

### 响应式尺寸
```tsx preview="iframe-follow"
import { Avatar } from "@rockshin/tao-ui";

export default function Example() {
  return (
    <div
      style={{
        display: "flex",
        gap: 16,
        alignItems: "center",
        flexWrap: "wrap",
      }}
    >
      <Avatar size={{ xs: 32, sm: 48, lg: 72 }}>AL</Avatar>
      <span>Resize the preview to change the avatar size.</span>
    </div>
  );
}
```

### 局部主题与语义部件
```tsx preview
import { Avatar, TaoProvider } from "@rockshin/tao-ui";

export default function Example() {
  return (
    <TaoProvider
      size="large"
      theme={{ token: { colorPrimary: "oklch(0.45 0.08 205)" } }}
    >
      <div
        style={{
          display: "flex",
          gap: 16,
          alignItems: "center",
          flexWrap: "wrap",
        }}
      >
        <Avatar
          shape="square"
          styles={{
            root: {
              background: "var(--tao-color-primary)",
              color: "var(--tao-primary-fg)",
            },
            content: { fontWeight: 700 },
          }}
        >
          AL
        </Avatar>
        <Avatar shape="square">BT</Avatar>
      </div>
    </TaoProvider>
  );
}
```

## API


### [#](#avatar)Avatar



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |

