Avatar 头像

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

星见书音

翻译了 128 本轻小说

<script setup lang="ts">
  import { Avatar, Card, Inline, Stack, Text } from '@hina-ui/vue'
</script>

<template>
  <Card class="w-full max-w-sm">
    <Inline gap="sm">
      <Avatar size="lg" src="/avatars/selfie.webp" name="星见书音" />
      <Stack gap="none">
        <Text class="font-medium">星见书音</Text>
        <Text tone="muted" size="sm">翻译了 128 本轻小说</Text>
      </Stack>
    </Inline>
  </Card>
</template>

vue

用法

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

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

星

<script setup lang="ts">
  import { Avatar, Inline } from '@hina-ui/vue'
</script>

<template>
  <Inline>
    <Avatar src="/avatars/paper.webp" alt="星见书音" />
    <Avatar name="星见书音" />
    <Avatar />
  </Inline>
</template>

vue

示例

尺寸

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

<script setup lang="ts">
  import { Avatar, Inline } from '@hina-ui/vue'
</script>

<template>
  <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>
</template>

vue

回退

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

星

中文取首字

西文取两个首字母

没有名字时用图标

图片加载失败

<script setup lang="ts">
  import { Avatar, Inline, Stack, Text } from '@hina-ui/vue'
</script>

<template>
  <Inline align="start" class="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>
</template>

vue

头像组

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

全部显示

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

<script setup lang="ts">
  import { Avatar, AvatarGroup, Stack, Text } from '@hina-ui/vue'

  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: '睡觉' },
  ]
</script>

<template>
  <Stack>
    <Stack gap="xs">
      <Text tone="muted" size="sm">全部显示</Text>
      <AvatarGroup>
        <Avatar v-for="m in members.slice(0, 4)" :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">
        <Avatar v-for="m in members" :key="m.name" :src="m.src" :alt="m.name" />
      </AvatarGroup>
    </Stack>
  </Stack>
</template>

vue

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

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

import { computed } from 'vue'
import { useAvatarGroup, type AvatarVariants } from '@hina-ui/vue'

const props = defineProps<{ size?: AvatarVariants['size'] }>()
const group = useAvatarGroup()
const size = computed(() => props.size ?? group?.value.size ?? 'md')

max 按默认插槽提供的条目计数，支持直接写在插槽中的 v-for。自定义组件内部渲染的多个头像不会分别计数；需要准确的 +N 时，让每个插槽条目代表一个头像。

自定义内容

默认插槽覆盖内置的回退内容，可以是图标或短文本。

★

<script setup lang="ts">
  import { Bot } from '@lucide/vue'
  import { Avatar, Inline } from '@hina-ui/vue'
</script>

<template>
  <Inline>
    <Avatar>
      <Bot />
    </Avatar>
    <Avatar>★</Avatar>
  </Inline>
</template>

vue

行为

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

API

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

插槽	说明
`default`	覆盖内置的回退内容

AvatarGroup

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

插槽	说明
`default`	一组头像

useAvatarGroup

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

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

用法

示例

尺寸

回退

头像组

自定义内容

行为

无障碍

API

AvatarGroup

useAvatarGroup