#AvatarGroup 头像组
成组展示成员头像,支持文字头像与人数折叠。使用 Avatar 定义每个成员。
#基础用法
将成员头像放入 AvatarGroup,通过每个 Avatar 的 alt 提供成员名称。
ABCDE
basic.tsx
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';
export function AvatarBasic() {
return (
<AvatarGroup aria-label="团队成员">
{['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
<Avatar key={name} alt={name}>
{name.slice(0, 1)}
</Avatar>
))}
</AvatarGroup>
);
}
组内文字头像的颜色用于区分成员,不表示状态。
#示例
#尺寸
通过 AvatarGroup.size 统一设置组内头像尺寸。
小中大
ABC
ABC
ABC
sizes.tsx
import { Avatar, AvatarGroup, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';
const sizes = [
{ value: 'sm', label: '小' },
{ value: 'md', label: '中' },
{ value: 'lg', label: '大' },
] as const;
export function AvatarSizes() {
return (
<Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
{sizes.map(({ value, label }) => (
<Fragment key={value}>
<Text tone="muted">{label}</Text>
<Flex align="center" wrap>
<AvatarGroup size={value} aria-label={`${label}号团队成员头像`}>
{['Ada', 'Ben', 'Cara'].map((name) => (
<Avatar key={name} alt={name}>
{name.slice(0, 1)}
</Avatar>
))}
</AvatarGroup>
</Flex>
</Fragment>
))}
</Grid>
);
}
#图片头像
通过 alt 为头像提供成员名称;只显示首字母时,也应提供完整名称。
image.tsx
import { Avatar } from '@ifhover/leaf-ui';
const portrait = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(
'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><title>Alex avatar illustration</title><rect width="100" height="100" fill="#e8efe8"/><path d="M8 100c2-27 17-42 42-42s40 15 42 42" fill="#32744d"/><path d="M36 62h28l-4 14-10 7-10-7z" fill="#e5af85"/><ellipse cx="50" cy="40" rx="22" ry="27" fill="#edc3a0"/><path d="M27 44c-8-30 8-38 23-38 23 0 30 22 23 41l-6-16-5-9c-9 10-20 14-31 14z" fill="#2e3c31"/><path d="M43 54q7 5 14 0" fill="none" stroke="#b1775a" stroke-width="2" stroke-linecap="round"/></svg>',
)}`;
export function AvatarImage() {
return <Avatar src={portrait} alt="Alex" />;
}
#加载失败与默认头像
图片加载失败时显示 children、icon 或默认图标。更换图片地址后会重试加载。
文字回退
AL
默认图标fallback.tsx
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';
export function AvatarFallback() {
return (
<Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
<Text tone="muted">文字回退</Text>
<Flex align="center" wrap>
<Avatar src="data:image/png;base64,broken" alt="Alex">
AL
</Avatar>
</Flex>
<Text tone="muted">默认图标</Text>
<Flex align="center" wrap>
<Avatar alt="访客" />
</Flex>
</Grid>
);
}
#头像组折叠
设置 maxCount 限制可见成员数量,通过 +N 查看其余成员。
ABC
extensions.tsx
import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';
export function ExtensionDemo() {
return (
<AvatarGroup maxCount={3} aria-label="团队成员">
{['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
<Avatar key={name} alt={name}>
{name.slice(0, 1)}
</Avatar>
))}
</AvatarGroup>
);
}
#形状
通过 Avatar.shape 设置圆形或方形头像。
圆形
LF
方形LF
shapes.tsx
import { Avatar, Flex, Grid, Text } from '@ifhover/leaf-ui';
export function AvatarShapes() {
return (
<Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
<Text tone="muted">圆形</Text>
<Flex align="center" wrap>
<Avatar shape="circle" alt="Leaf">
LF
</Avatar>
</Flex>
<Text tone="muted">方形</Text>
<Flex align="center" wrap>
<Avatar shape="square" alt="Leaf">
LF
</Avatar>
</Flex>
</Grid>
);
}
#API
#AvatarGroup API
成组展示成员头像及折叠人数的参数。
#AvatarGroupProps API
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
maxCount | number | Infinity | 最多展示的头像数,超出部分折叠为 +N。 |
size | AvatarProps['size'] | — | 头像尺寸预设;数字为像素值。 |
shape | AvatarProps['shape'] | — | 裁剪形状 |
maxContent | (hiddenCount: number) => ReactNode | — | 自定义溢出人数 |
#Avatar API
组内单个成员头像的参数。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | — | 头像图片地址。 |
srcSet | string | — | 响应式图片候选。 |
imageProps | Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'alt' | 'onError'> | — | 图片原生属性,如 loading、sizes、crossOrigin、objectFit 样式 |
alt | string | 文字或语言默认值 | 可访问名称 |
size | 'sm' | 'md' | 'lg' | number | 'md' | 预设尺寸或像素值 |
shape | 'circle' | 'square' | 'circle' | 形状 |
icon | ReactNode | — | 没有图片时显示的图标。 |
onError | () => void | — | 图片加载失败回调 |
children | ReactNode | — | 没有图片时显示的文字或内容。 |