Avatar

Avatar 是对 @base-ui/react/avatar 的封装，提供头像展示、图片加载回退和头像组功能。

引入

import {
  Avatar,
  AvatarImage,
  AvatarFallback,
  AvatarBadge,
  AvatarGroup,
  AvatarGroupCount,
} from "aui-components";

基本用法

<Avatar>
  <AvatarImage src="https://example.com/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

图片加载成功：显示 AvatarImage
图片加载失败：显示 AvatarFallback（首字母、图标等）

子组件

子组件	说明
`Avatar`	根容器
`AvatarImage`	头像图片
`AvatarFallback`	图片加载失败时的回退内容
`AvatarBadge`	右下角状态标记
`AvatarGroup`	头像组容器
`AvatarGroupCount`	头像组的 "+N" 计数

Avatar Props

属性	类型	默认值	说明
`className`	`enum`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`enum`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`enum`	—	Style applied to the element, or a function that returns a style object based on the component's state.
`size`	`enum`	`default`	—

尺寸

尺寸	样式
`default`	`size-8`
`sm`	`size-6`
`lg`	`size-10`

<div className="flex items-center gap-2">
  <Avatar size="sm">
    <AvatarFallback>S</AvatarFallback>
  </Avatar>
  <Avatar size="default">
    <AvatarFallback>M</AvatarFallback>
  </Avatar>
  <Avatar size="lg">
    <AvatarFallback>L</AvatarFallback>
  </Avatar>
</div>

AvatarBadge

在头像右下角显示状态标记：

<Avatar>
  <AvatarImage src="..." alt="User" />
  <AvatarFallback>JD</AvatarFallback>
  <AvatarBadge className="bg-green-500" />
</Avatar>

位置：absolute right-0 bottom-0
样式：圆角方形，bg-primary，ring 环绕

AvatarGroup

将多个头像组合展示：

<AvatarGroup>
  <Avatar>
    <AvatarImage src="user1.jpg" />
  </Avatar>
  <Avatar>
    <AvatarImage src="user2.jpg" />
  </Avatar>
  <Avatar>
    <AvatarImage src="user3.jpg" />
  </Avatar>
  <AvatarGroupCount>+5</AvatarGroupCount>
</AvatarGroup>

头像之间有 -space-x-2 重叠
每个头像带 ring-2 ring-background 分隔

在组件库中的使用

Avatar 被 Attachment 组件内部使用，用于显示附件缩略图：

// AttachmentThumb 内部
<Avatar className="h-full w-full rounded-none">
  <AvatarImage src={src} className="rounded-none object-cover" />
  <AvatarFallback>
    <FileTextIcon className="size-8" />
  </AvatarFallback>
</Avatar>

完整示例

export function UserAvatar() {
  return (
    <div className="flex items-center gap-2">
      <Avatar>
        <AvatarImage src="https://github.com/user.png" alt="User Name" />
        <AvatarFallback>UN</AvatarFallback>
      </Avatar>
      <div>
        <p className="text-sm font-medium">User Name</p>
        <p className="text-xs text-muted-foreground">Online</p>
      </div>
    </div>
  );
}

export function ProjectMembers() {
  return (
    <AvatarGroup>
      <Avatar size="sm">
        <AvatarImage src="member1.jpg" />
      </Avatar>
      <Avatar size="sm">
        <AvatarFallback>JD</AvatarFallback>
      </Avatar>
      <Avatar size="sm">
        <AvatarFallback>AK</AvatarFallback>
      </Avatar>
      <AvatarGroupCount>+3</AvatarGroupCount>
    </AvatarGroup>
  );
}

Avatar

On this page