Avatar 头像

代表一个用户或实体的圆形头像。

星见书音

翻译了 128 本轻小说

import { Avatar, Card, Inline, Stack, Text } from '@hina-ui/react'

export default function Demo() {
  return (
    <Card className="w-full max-w-sm">
      <Inline gap="sm">
        <Avatar size="lg" src="/avatars/selfie.webp" name="星见书音" />
        <Stack gap="none">
          <Text className="font-medium">星见书音</Text>
          <Text tone="muted" size="sm">
            翻译了 128 本轻小说
          </Text>
        </Stack>
      </Inline>
    </Card>
  )
}

tsx

用法

import { Avatar } from '@hina-ui/react'

src 是头像图片，name 是对应的名称。图片加载成功时显示图片，加载失败或没有图片时显示名称的首字母，没有名称时显示通用图标。

星

import { Avatar, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline>
      <Avatar src="/avatars/paper.webp" alt="星见书音" />
      <Avatar name="星见书音" />
      <Avatar />
    </Inline>
  )
}

tsx

示例

尺寸

三档分别是 24、32 和 40 像素。头像始终为圆形，不提供方形和圆角档位。

import { Avatar, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="center">
      <Avatar size="sm" src="/avatars/peek.webp" alt="星见书音" />
      <Avatar size="md" src="/avatars/peek.webp" alt="星见书音" />
      <Avatar size="lg" src="/avatars/peek.webp" alt="星见书音" />
    </Inline>
  )
}

tsx

回退

首字母按书写系统区分：中日韩文的名称取第一个字，西文的名称取前两段的首字母。图片加载失败时同样回退到首字母，加载失败的图片不会显示出来。

星

中文取首字

西文取两个首字母

没有名字时用图标

图片加载失败

import { Avatar, Inline, Stack, Text } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline align="start" className="gap-8">
      <Stack gap="xs" align="center">
        <Avatar name="星见书音" />
        <Text tone="muted" size="sm">
          中文取首字
        </Text>
      </Stack>
      <Stack gap="xs" align="center">
        <Avatar name="Shion Hoshimi" />
        <Text tone="muted" size="sm">
          西文取两个首字母
        </Text>
      </Stack>
      <Stack gap="xs" align="center">
        <Avatar />
        <Text tone="muted" size="sm">
          没有名字时用图标
        </Text>
      </Stack>
      <Stack gap="xs" align="center">
        <Avatar src="/missing.png" name="星见书音" />
        <Text tone="muted" size="sm">
          图片加载失败
        </Text>
      </Stack>
    </Inline>
  )
}

tsx

头像组

AvatarGroup 把多个头像叠在一起。max 限制显示的数量，超出的部分合并为一个 +N。AvatarGroup 的 size 统一整组的尺寸，单个头像自身的 size 优先。

全部显示

最多显示三个，其余折成计数

import { Avatar, AvatarGroup, Stack, Text } from '@hina-ui/react'

const members = [
  { src: '/avatars/paper.webp', name: '星见书音' },
  { src: '/avatars/peek.webp', name: '偷瞄' },
  { src: '/avatars/glass.webp', name: '玻璃' },
  { src: '/avatars/huh.webp', name: '疑惑' },
  { src: '/avatars/run.webp', name: '快跑' },
  { src: '/avatars/sleep.webp', name: '睡觉' },
]

export default function Demo() {
  return (
    <Stack>
      <Stack gap="xs">
        <Text tone="muted" size="sm">
          全部显示
        </Text>
        <AvatarGroup>
          {members.slice(0, 4).map(m => (
            <Avatar key={m.name} src={m.src} alt={m.name} />
          ))}
        </AvatarGroup>
      </Stack>
      <Stack gap="xs">
        <Text tone="muted" size="sm">
          最多显示三个，其余折成计数
        </Text>
        <AvatarGroup max={3} size="lg">
          {members.map(m => (
            <Avatar key={m.name} src={m.src} alt={m.name} />
          ))}
        </AvatarGroup>
      </Stack>
    </Stack>
  )
}

tsx

叠放间距和分隔环直接作用于组内的外层元素。自定义头像即使包了一层触发器，也不需要把组的布局类名转发给内层头像。包装元素的圆角和装饰仍由自定义组件控制。

自定义子组件可以从包根导入 useAvatarGroup，读取整组的尺寸；未放在头像组内时返回 null。例如在自定义头像组件中保留「自身尺寸优先」的规则：

'use client'

import { Avatar, useAvatarGroup, type AvatarVariants } from '@hina-ui/react'

export function MemberAvatar({ name, size }: { name: string; size?: AvatarVariants['size'] }) {
  const group = useAvatarGroup()
  return <Avatar name={name} size={size ?? group?.size ?? 'md'} />
}

tsx

max 按 children 中的条目计数，直接写在其中的数组（例如 members.map(...)）和 Fragment 会展开后计数。自定义组件内部渲染的多个头像不会分别计数；需要准确的 +N 时，让每个子元素代表一个头像。

自定义内容

children 覆盖内置的回退内容，可以是图标或短文本。

★

import { Bot } from 'lucide-react'
import { Avatar, Inline } from '@hina-ui/react'

export default function Demo() {
  return (
    <Inline>
      <Avatar>
        <Bot />
      </Avatar>
      <Avatar>★</Avatar>
    </Inline>
  )
}

tsx

行为

头像由 Image 渲染，因此地址同样经过 ImageResolverProvider 提供的解析函数，加载期间由骨架占位。
图片按 object-fit: cover 填满圆形，长宽比不同的图片不会变形。
没有 src 或图片加载失败时显示回退内容，失败的图片会被移除。
Image 的其余属性可以直接写在 Avatar 上，例如 fallback、lazy、eager，会原样透传。

API

属性	类型	默认值	说明
`src`	`string`	—	头像图片地址
`alt`	`string`	—	图片的替代文本，缺省时取 `name`
`name`	`string`	—	用于生成首字母的名称
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸
`className`	`string`	—	追加至根元素的类名

属性	说明
`children`	覆盖内置的回退内容

AvatarGroup

属性	类型	默认值	说明
`max`	`number`	—	最多显示的数量，其余合并为计数
`size`	`'sm' \| 'md' \| 'lg'`	—	整组的尺寸，单个头像可以覆盖
`className`	`string`	—	追加至容器的类名

属性	说明
`children`	一组头像

useAvatarGroup

useAvatarGroup() 返回 AvatarGroupContext | null。AvatarGroupContext 也从包根导出。

字段	类型	说明
`size`	`AvatarVariants['size']`	最近的头像组设置的尺寸；组未指定时为 `undefined`

用法

示例

尺寸

回退

头像组

自定义内容

行为

无障碍

API

AvatarGroup

useAvatarGroup