Avatar

基础反馈

基于 Bootstrap 5 的头像组件，用于展示用户图片或名称缩写，支持图片加载失败自动回退、多种尺寸与形状、背景色变体与描边，并通过 AvatarGroup 提供堆叠展示、数量折叠和组级默认配置

Component Demo

Basic usage and examples of the Avatar component

图片头像

传入 `src` 显示图片头像，图片会以裁剪方式填充整个头像区域

尺寸

张张张张张张

预设尺寸对应 24/32/40/48/64 像素，也可传入数字自定义像素大小，文字会随尺寸等比缩放

形状

张张张

背景色变体

PRSESUDAWAINLIDA

名称缩写

张JDMCADRB?

通过 `name` 自动生成缩写：中文取首字（姓）、英文取各单词首字母；提供 `children` 时优先使用自定义内容，两者都未提供时显示「?」

图片加载失败回退

图片加载失败时自动回退到 `children` 或 `name` 生成的缩写，避免出现空头像

描边

张

`border` 使用 `--bs-body-bg` 颜色描边，在图片或彩色背景上与页面自然分隔

自定义内容

✓📷JS!

`children` 支持任意内容，可用于展示状态图标、等级标记等

头像组

使用 AvatarGroup 将多个头像堆叠展示，默认以 8px 重叠并自动添加分隔描边

数量上限

通过 `max` 限制显示数量，超出部分折叠为「+N」占位头像

组级设置

张李王

AvatarGroup 上的 `bg`、`shape`、`size`、`border` 会作为组内 Avatar 的默认值，单个 Avatar 可通过同名属性覆盖

交互演示

在图片、名称缩写与自定义内容之间切换

API Documentation

Complete API reference for the Avatar component

Props

Avatar

属性名	类型	默认值	描述
`alt`	`string`	-	图片替代文本；未提供时依次回退为 `name`（若提供）和空字符串
`as`	`ElementType`	`'span'`	渲染的根元素类型
`bg`	`AvatarBg`	`'secondary'`	头像背景色变体，对应 Bootstrap 的 `text-bg-*` 工具类，用于兜底内容的底色
`border`	`boolean`	`false`	是否显示描边，描边颜色取自 `--bs-body-bg`，用于与页面背景区分
`children`	`ReactNode`	-	兜底内容，优先于 `name` 自动生成的缩写
`className`	`string`	-	自定义类名
`name`	`string`	-	用户名称，自动生成缩写：中文取首字（姓）、英文取各单词首字母；未提供任何内容时显示「?」
`shape`	`AvatarShape`	`'circle'`	头像形状，`circle` 圆形、`rounded` 圆角方形、`square` 方形
`size`	`AvatarSize \| number`	`'md'`	头像尺寸，预设值对应 24/32/40/48/64 像素，也可传入数字指定像素大小
`src`	`string`	-	图片地址；加载失败时自动回退到 `children` 或 `name` 生成的缩写
`...rest`	`HTMLAttributes`	-	根元素的所有原生属性（如 `title`、`style`、`aria-label` 等）

AvatarGroup

属性名	类型	默认值	描述
`as`	`ElementType`	`'div'`	渲染的根元素类型
`bg`	`AvatarBg`	-	组内 Avatar 的默认背景色，可被单个 Avatar 的 `bg` 覆盖
`border`	`boolean`	`true`	组内 Avatar 的默认描边，堆叠时用于彼此分隔，可被单个 Avatar 的 `border` 覆盖
`children`	`ReactNode`	-	组内头像，通常为多个 Avatar
`className`	`string`	-	自定义类名，作用于根容器
`max`	`number`	-	最多显示的头像数量（含「+N」占位头像），超出部分折叠为「+N」
`overlap`	`number \| string`	`8`	头像之间的重叠距离，传入数字表示像素，也可传入任意 CSS 长度
`shape`	`AvatarShape`	-	组内 Avatar 的默认形状，可被单个 Avatar 的 `shape` 覆盖
`size`	`AvatarSize \| number`	-	组内 Avatar 的默认尺寸，可被单个 Avatar 的 `size` 覆盖
`...rest`	`HTMLAttributes`	-	根容器的所有原生属性（如 `style`、`aria-label` 等）

Type Definitions

AvatarBg

头像背景色变体类型

export type AvatarBg =
  'danger' | 'dark' | 'info' | 'light' | 'primary' | 'secondary' | 'success' | 'warning';

AvatarGroupContextValue

头像组上下文值接口，供 `useAvatarGroup` 使用

export interface AvatarGroupContextValue {
  bg?: AvatarBg;
  border: boolean;
  shape?: AvatarShape;
  size?: AvatarSize | number;
}

AvatarGroupProps

头像组组件属性接口

export interface AvatarGroupProps extends HTMLAttributes<HTMLElement> {
  as?: ElementType;
  bg?: AvatarBg;
  border?: boolean;
  children?: ReactNode;
  className?: string;
  max?: number;
  overlap?: number | string;
  shape?: AvatarShape;
  size?: AvatarSize | number;
}

AvatarProps

头像组件属性接口

export interface AvatarProps extends HTMLAttributes<HTMLElement> {
  alt?: string;
  as?: ElementType;
  bg?: AvatarBg;
  border?: boolean;
  children?: ReactNode;
  className?: string;
  name?: string;
  shape?: AvatarShape;
  size?: AvatarSize | number;
  src?: string;
}

AvatarShape

头像形状类型

export type AvatarShape = 'circle' | 'rounded' | 'square';

AvatarSize

头像尺寸类型

export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';