Avatar 头像

展示用户、团队或对象的头像。

尺寸与形状

小尺寸

默认尺寸

大尺寸 · 方形

未读提醒

basic.tsx

import { Avatar, Badge, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarBasic() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>小尺寸</Text>
        <Avatar size="sm">LF</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>默认尺寸</Text>
        <Avatar>LE</Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>大尺寸 · 方形</Text>
        <Avatar size="lg" shape="square">
          UI
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>未读提醒</Text>
        <Badge dot>
          <Avatar alt="未读消息">A</Avatar>
        </Badge>
      </Flex>
    </Flex>
  );
}

图片头像

圆形图片

方形图片

image.tsx

import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarImage() {
  const image = '../avatar-portrait.svg';
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>圆形图片</Text>
        <Avatar src={image} alt="Alex" size="lg" />
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>方形图片</Text>
        <Avatar src={image} alt="Alex" size={64} shape="square" imageProps={{ loading: 'lazy' }} />
      </Flex>
    </Flex>
  );
}

加载失败与默认头像

加载失败时显示文字

未设置图片时显示默认图标

fallback.tsx

import { Avatar, Flex, Text } from '@ifhover/leaf-ui';

export function AvatarFallback() {
  return (
    <Flex gap="md" align="center" wrap justify="center">
      <Flex direction="column" gap="sm" align="start">
        <Text>加载失败时显示文字</Text>
        <Avatar src="data:image/png;base64,broken" alt="图片加载失败">
          LF
        </Avatar>
      </Flex>
      <Flex direction="column" gap="sm" align="start">
        <Text>未设置图片时显示默认图标</Text>
        <Avatar alt="访客" />
      </Flex>
    </Flex>
  );
}

扩展用法

extensions.tsx

import { Avatar, AvatarGroup } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <AvatarGroup maxCount={3}>
      {['Ada', 'Ben', 'Cara', 'Dan', 'Eva'].map((name) => (
        <Avatar key={name} alt={name}>
          {name.slice(0, 1)}
        </Avatar>
      ))}
    </AvatarGroup>
  );
}

Avatar API

属性	类型	默认值	说明
`src / srcSet`	`string`	—	图片地址 / 响应式图片候选
`alt`	`string`	文字或语言默认值	可访问名称
`imageProps`	`Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' \| 'srcSet' \| 'alt' \| 'onError'>`	—	图片原生属性，如 loading、sizes、crossOrigin、objectFit 样式
`onError`	`() => void`	—	图片加载失败回调
`size`	`'sm' \| 'md' \| 'lg' \| number`	`'md'`	预设尺寸或像素值
`shape`	`'circle' \| 'square'`	`'circle'`	形状
`icon / children`	`ReactNode`	—	没有图片时的图标 / 文字内容

类型

可导入以下类型定义属性、组装数据或处理回调。

import type { AvatarProps } from '@ifhover/leaf-ui';

使用说明

图片加载失败时自动显示 children、icon 或默认头像，图片地址变化后会重试。alt 为头像提供可访问名称；图片自身避免重复朗读。imageProps.style 可调整裁切方式。

扩展类型

import type { AvatarGroupProps } from '@ifhover/leaf-ui';

AvatarGroupProps API

属性	类型	默认值	说明
`maxCount`	`number`	`Infinity`	最多勾选或展示数量
`size`	`'sm' \| 'md' \| 'lg' \| number`	—	尺寸或间距预设
`shape`	`'circle' \| 'square'`	—	裁剪形状
`maxContent`	`(hiddenCount: number) => ReactNode`	—	自定义溢出人数

#Avatar 头像

#尺寸与形状

#图片头像

#加载失败与默认头像

#扩展用法

#Avatar API

#类型

#使用说明

#扩展类型

#AvatarGroupProps API