Avatar 头像

用来代表用户或事物，支持图片、图标或字符展示；AvatarGroup 以重叠方式组合展示多个头像。

何时使用

需要展示用户或事物的标识时。
需要在有限空间内展示多个人（使用 AvatarGroup 折叠为「+N」）。
需要在头像上叠加徽标、状态点（配合 Badge 使用）。

基础用法

支持便捷式（props 直出）与复合式（AvatarImage + AvatarFallback）两种写法。

<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@reglow/reui";
</script>

<template>
  <Avatar>
    <AvatarImage src="/reglow.png" alt="Reglow" />
    <AvatarFallback>RG</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarFallback>张</AvatarFallback>
  </Avatar>
</template>

便捷式用法

图片、图标、字符三种内容可直接通过 props 传入；内容优先级为 默认插槽 > src > icon。

<script setup lang="ts">
import { Avatar } from "@reglow/reui";
</script>

<template>
  <Avatar src="/reglow.png" alt="Reglow" size="large" />
  <Avatar icon="U" />
  <Avatar size="small" shape="square">张</Avatar>
  <Avatar :gap="1">Alex</Avatar>
</template>

头像尺寸

size 支持 small（24px）/ medium（32px，默认）/ large（40px）或自定义像素值；也可用 class 覆盖。

<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@reglow/reui";
</script>

<template>
  <Avatar size="small">
    <AvatarFallback>张</AvatarFallback>
  </Avatar>
  <Avatar size="medium">
    <AvatarFallback>张</AvatarFallback>
  </Avatar>
  <Avatar size="large">
    <AvatarFallback>张</AvatarFallback>
  </Avatar>
  <Avatar :size="56">
    <AvatarImage src="/reglow.png" alt="Reglow" />
    <AvatarFallback>RG</AvatarFallback>
  </Avatar>
</template>

文字与图标头像

无图片时可使用 AvatarFallback 展示文字或图标作为兜底；字符头像的字号会按尺寸自动推导，gap 控制字符与左右边界的距离（值越小字号越大）。

<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@reglow/reui";
import { User } from "lucide-vue-next";
</script>

<template>
  <Avatar>
    <AvatarFallback>张三</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarFallback>李</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="/reglow.png" alt="Reglow" />
    <AvatarFallback>
      <User class="size-4" />
    </AvatarFallback>
  </Avatar>
</template>

加载失败兜底

AvatarImage 的 src 加载失败时会自动隐藏图片，并显示 AvatarFallback 兜底内容；便捷式写法下则回退到 icon 或默认插槽内容。

<script setup lang="ts">
import { Avatar, AvatarImage, AvatarFallback } from "@reglow/reui";
</script>

<template>
  <!-- src 加载失败时自动隐藏图片并显示兜底内容 -->
  <Avatar>
    <AvatarImage src="/not-exists.png" alt="头像" />
    <AvatarFallback>张</AvatarFallback>
  </Avatar>
  <Avatar>
    <AvatarImage src="https://picsum.photos/seed/reui-avatar/80/80" alt="头像" />
    <AvatarFallback>RG</AvatarFallback>
  </Avatar>
</template>

头像组

AvatarGroup 将多个头像横向重叠排列，超出 max-count 的部分折叠为「+N」，悬浮/聚焦/点击可查看完整列表。 size / shape 统一作用于组内全部头像（单个头像可自行覆盖）。

<script setup lang="ts">
import { Avatar, AvatarGroup, AvatarImage, AvatarFallback } from "@reglow/reui";
</script>

<template>
  <AvatarGroup :max-count="3" size="large">
    <Avatar>
      <AvatarImage src="/reglow.png" alt="Reglow" />
      <AvatarFallback>RG</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>张</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>李</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>王</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>赵</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>钱</AvatarFallback>
    </Avatar>
  </AvatarGroup>
</template>

头像组配置

max 可同时配置折叠数量、+N 头像样式与气泡（方向 / 触发方式），等价于 max-count / max-style / max-popover-placement / max-popover-trigger。

<script setup lang="ts">
import { Avatar, AvatarGroup, AvatarFallback } from "@reglow/reui";

const max = {
  count: 2,
  style: { backgroundColor: "var(--primary)", color: "var(--primary-foreground)" },
  popover: { placement: "bottom", trigger: "click" },
};
</script>

<template>
  <AvatarGroup :max="max" shape="square">
    <Avatar>
      <AvatarFallback>张</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>李</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>王</AvatarFallback>
    </Avatar>
    <Avatar>
      <AvatarFallback>赵</AvatarFallback>
    </Avatar>
  </AvatarGroup>
</template>

导入

import { Avatar, AvatarGroup, AvatarImage, AvatarFallback } from "@reglow/reui";

组成

组件	说明
`Avatar`	容器（圆形/圆角方形裁剪，支持 `src` / `icon` / `size` / `shape` 等便捷 props）
`AvatarImage`	图片（`src` / `alt`），加载失败自动隐藏
`AvatarFallback`	兜底内容（字符 / 图标）
`AvatarGroup`	头像组（重叠排列 + `+N` 折叠列表）

API

Avatar Props

参数	说明	类型	默认值
src	图片地址（也可直接传图片 VNode）	`string \| VNode`	-
srcSet	响应式图片地址	`string`	-
alt	图像无法显示时的替代文本	`string`	-
icon	自定义图标（图片不可用时的兜底，优先级高于默认插槽）	`string \| VNode \| Component`	-
shape	形状（在 `AvatarGroup` 内默认继承分组配置）	`'circle' \| 'square'`	`'circle'`
size	大小（数字按 px；在 `AvatarGroup` 内默认继承）	`number \| 'large' \| 'medium' \| 'small'`	`'medium'`
gap	字符类型距离左右边界的像素值（越小字号越大）	`number`	`4`
draggable	图片是否允许拖动	`boolean`	`true`
crossOrigin	CORS 属性	`'anonymous' \| 'use-credentials' \| ''`	-
class / style	附加类名 / 样式	`string \| CSSProperties`	-

Avatar Events

事件名	说明	回调参数
load	图片加载完成	`(e: Event)`
error	图片加载失败	`(e: Event)`

Avatar Slots

插槽名	说明
default	头像内容（字符，或 `AvatarImage` + `AvatarFallback` 复合写法）
icon	自定义图标兜底（等价于 `icon` prop，插槽优先级更高）

AvatarGroup Props

参数	说明	类型	默认值
max	最多显示配置（数量 / `+N` 样式 / 气泡）	`{ count?: number; style?: CSSProperties; popover?: { placement?: 'top' \| 'bottom' \| 'left' \| 'right'; trigger?: 'hover' \| 'focus' \| 'click'; class?: string; style?: CSSProperties } }`	-
maxCount	最多显示的头像数量（等价于 `max.count`）	`number`	-
maxStyle	`+N` 头像样式（等价于 `max.style`）	`CSSProperties`	-
maxPopoverPlacement	`+N` 气泡方向（等价于 `max.popover.placement`）	`'top' \| 'bottom' \| 'left' \| 'right'`	`'top'`
maxPopoverTrigger	`+N` 气泡触发方式（等价于 `max.popover.trigger`）	`'hover' \| 'focus' \| 'click'`	`'hover'`
size	组内头像统一大小（可被单个 Avatar 覆盖）	`number \| 'large' \| 'medium' \| 'small'`	`'medium'`
shape	组内头像统一形状	`'circle' \| 'square'`	`'circle'`
class / style	附加类名 / 样式	`string \| CSSProperties`	-

AvatarGroup Slots

插槽名	说明
default	头像列表（`Avatar` 子节点）

AvatarImage / AvatarFallback

复合式写法的子组件，props 透传 reka-ui Avatar；尺寸与形状自动继承外层 Avatar / AvatarGroup。

Semantic DOM

avatar：头像根元素
avatar-img：便捷式的图片元素
avatar-image / avatar-fallback：复合式写法的图片 / 兜底元素
avatar-group：头像组容器（负外边距重叠 + 主题色描边）
avatar-group-more：+N 触发器
avatar-group-popover：+N 气泡内容面板

说明：头像已从 components/ui/avatar 迁移到 components/reui/avatar（ui 层保留 @deprecated 转发），原 @/components/ui/avatar、@reglow/reui/ui/avatar 引用无需改动即可获得升级版组件。

内容锚点

何时使用
基础用法
导入
组成
API