Avatar 头像

Avatar 显示一个人或一个 Agent 的头像，没有图片时显示名字缩写。AvatarGroup 把几个头像叠在一起，放不下的收成一个“+N”头像。

演示

基础用法

size 可以是 small、medium、large（和按钮同高，放在一行里能对齐），也可以是像素数。

形状和边框

头像跟随主题的圆角：Brutal 是直角，Elegant 是小圆角。round 变成圆形；bordered 在 Brutal 下加一圈墨线，在 Elegant 下加一圈浅色描边。

文字

文字默认是头像边长的 40%，放不下时会自动缩小，完整的名字也能装进去。可以在输入框里试试。

颜色

color 设置背景色，上面的文字颜色用 style.color 设置。用不同的颜色角色区分 Agent 和人很合适；除了缩写，也可以放图标。

加载失败

src 加载失败时先试 fallbackSrc，再不行就显示 renderFallback 或子元素。图片加载过程中也会先显示子元素。

搭配徽标

把头像包在 Badge 里，显示未读数或在线状态。

头像组

AvatarGroup 让头像互相叠压，并给每个头像加上边框把它们隔开。设置 max 后，放不下的会合并成一个“+N”头像。组上的 size 和 round 对里面所有头像生效；也可以直接把头像作为子元素传入，Avatar 和 PixelAvatar 可以混在一起。expandOnHover 在鼠标移上去时把头像展开，vertical 改成从上往下叠。

名字提示和剩余头像菜单

组件本身不带弹出层：用 renderAvatar 给每个头像包一个 Tooltip 显示名字，用 renderRest 把“+N”换成一个 Dropdown，点击后列出被收起的人。

懒加载

单独用 lazy 时交给浏览器原生的懒加载。配合 intersectionObserverOptions，图片会在滚进指定容器后才开始加载，在此之前显示 renderPlaceholder。

Avatar 属性

名称	类型	默认值	说明	版本
`src`	`string`	`undefined`	图片地址。	未发布
`alt`	`string`	`undefined`	图片的替代文本。不传时图片视为装饰。	未发布
`children`	`ReactNode`	`undefined`	文字或图标。没有 `src`、图片加载中、所有图片都失败时显示。文字会自动缩小以放进头像。	未发布
`size`	`small \| medium \| large \| number`	`medium`	预设尺寸或以 px 为单位的边长。在头像组里默认用组的尺寸。	未发布
`round`	`boolean`	`false`	圆形，而不是主题的默认形状。	未发布
`bordered`	`boolean`	`false`	加边框。在头像组里总是开启。	未发布
`color`	`string`	`undefined`	背景色。	未发布
`objectFit`	`fill \| contain \| cover \| none \| scale-down`	`cover`	图片如何填满头像。	未发布
`fallbackSrc`	`string`	`undefined`	`src` 加载失败时尝试的图片。	未发布
`renderFallback`	`() => ReactNode`	`undefined`	所有图片都加载失败时显示的内容，默认是 `children`。	未发布
`renderPlaceholder`	`() => ReactNode`	`undefined`	图片加载中显示的内容，默认是 `children`。	未发布
`lazy`	`boolean`	`false`	快进入视口时才加载图片。	未发布
`intersectionObserverOptions`	`{ root?, rootMargin?, threshold? }`	`undefined`	配合 `lazy`，头像进入这个容器后才加载。`root` 可以是元素或选择器。	未发布
`imgProps`	`ImgHTMLAttributes`	`undefined`	传给 `<img>` 元素的属性。	未发布
`onLoad`	`(event) => void`	`undefined`	图片加载完成时调用。	未发布
`onError`	`(event) => void`	`undefined`	`src` 或 `fallbackSrc` 加载失败时调用。	未发布

Avatar 也接受原生 span 属性和 ref。只放图标的头像应该加上 role="img" 和 aria-label。

AvatarGroup 属性

名称	类型	默认值	说明	版本
`options`	`{ src: string; alt?: string }[]`	`[]`	要显示的头像。选项类型可以自定义（泛型）。	未发布
`max`	`number`	`undefined`	最多显示几个头像；超出时最后一个变成“+N”。	未发布
`maxStyle`	`CSSProperties`	`undefined`	“+N”头像的样式。	未发布
`size`	`small \| medium \| large \| number`	`undefined`	组内头像的默认尺寸。	未发布
`round`	`boolean`	`undefined`	组内头像默认的 `round`。	未发布
`vertical`	`boolean`	`false`	从上往下叠。	未发布
`expandOnHover`	`boolean`	`false`	鼠标悬停时展开。	未发布
`renderAvatar`	`({ option }) => ReactNode`	`undefined`	渲染单个选项。	未发布
`renderRest`	`({ options, rest }) => ReactNode`	`undefined`	渲染“+N”头像。	未发布
`children`	`ReactNode`	`undefined`	放在 `options` 之前的头像。	未发布

AvatarGroup 渲染为带 role="group" 的 div，请给它一个说明成员是谁的 aria-label。“+N”头像读作“还有 N 个”。

#演示

#基础用法

#形状和边框

#文字

#颜色

#加载失败

#搭配徽标

#头像组

#名字提示和剩余头像菜单

#懒加载

#Avatar 属性

#AvatarGroup 属性

演示