基础

Avatar 用户头像

用于用户头像场景的 MoriUI 组件。

资源

导入

import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup, AvatarGroupCount, AvatarImage } from 'moriui'

组合方式

Avatar 组合 AvatarImage 与 AvatarFallback；徽标和分组按需加入，图片失败时由 Reka UI 切换回退内容。

RTL

头像内容与分组顺序继承外围 dir；文本标签在 RTL 环境保持正确阅读方向。

示例

概览

头像以可辨识的回退文字保持稳定占位。

森UI

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <div class="flex items-center gap-3">
    <Avatar><AvatarFallback>森</AvatarFallback></Avatar><Avatar><AvatarFallback>UI</AvatarFallback></Avatar>
  </div>
</template>

基础

使用 AvatarFallback 提供图片不可用时的内容。

森

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <Avatar><AvatarFallback>森</AvatarFallback></Avatar>
</template>

状态徽标

AvatarBadge 在头像边缘表达在线状态。

森

<script setup lang="ts">
  import {
    Avatar,
    AvatarBadge,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <Avatar><AvatarFallback>森</AvatarFallback><AvatarBadge><span class="sr-only">在线</span></AvatarBadge></Avatar>
</template>

图标徽标

用可访问名称补充仅图标徽标的含义。

森

<script setup lang="ts">
  import { Check } from '@lucide/vue'
  import {
    Avatar,
    AvatarBadge,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <Avatar>
    <AvatarFallback>森</AvatarFallback><AvatarBadge aria-label="已验证">
      <Check class="size-3" />
    </AvatarBadge>
  </Avatar>
</template>

头像组

AvatarGroup 紧凑排列多位成员。

林周陈

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback,
    AvatarGroup
  } from 'moriui'
</script>

<template>
  <AvatarGroup><Avatar><AvatarFallback>林</AvatarFallback></Avatar><Avatar><AvatarFallback>周</AvatarFallback></Avatar><Avatar><AvatarFallback>陈</AvatarFallback></Avatar></AvatarGroup>
</template>

剩余数量

AvatarGroupCount 汇总未展示成员。

林周

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback,
    AvatarGroup,
    AvatarGroupCount
  } from 'moriui'
</script>

<template>
  <AvatarGroup>
    <Avatar><AvatarFallback>林</AvatarFallback></Avatar><Avatar><AvatarFallback>周</AvatarFallback></Avatar><AvatarGroupCount aria-label="另有 3 位成员">
      +3
    </AvatarGroupCount>
  </AvatarGroup>
</template>

图标计数

使用图标入口指向完整成员列表。

林周

<script setup lang="ts">
  import { Users } from '@lucide/vue'
  import {
    Avatar,
    AvatarFallback,
    AvatarGroup,
    AvatarGroupCount
  } from 'moriui'
</script>

<template>
  <AvatarGroup>
    <Avatar><AvatarFallback>林</AvatarFallback></Avatar><Avatar><AvatarFallback>周</AvatarFallback></Avatar><AvatarGroupCount aria-label="查看全部成员">
      <Users class="size-4" />
    </AvatarGroupCount>
  </AvatarGroup>
</template>

尺寸

sm、default 与 lg 覆盖常见密度。

小中大

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <div class="flex items-end gap-3">
    <Avatar size="sm">
      <AvatarFallback>小</AvatarFallback>
    </Avatar><Avatar><AvatarFallback>中</AvatarFallback></Avatar><Avatar size="lg">
      <AvatarFallback>大</AvatarFallback>
    </Avatar>
  </div>
</template>

账户入口

头像可放入语义正确的按钮作为菜单入口。

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback,
    Button
  } from 'moriui'
</script>

<template>
  <Button
    type="button"
    size="icon"
    variant="ghost"
    class="rounded-full"
    aria-label="打开账户菜单"
  >
    <Avatar><AvatarFallback>森</AvatarFallback></Avatar>
  </Button>
</template>

RTL

在 RTL 文本流中组合头像和名称。

موملف المستخدم

<script setup lang="ts">
  import {
    Avatar,
    AvatarFallback
  } from 'moriui'
</script>

<template>
  <div dir="rtl" class="flex items-center gap-3">
    <Avatar><AvatarFallback>مو</AvatarFallback></Avatar><span class="text-sm">ملف المستخدم</span>
  </div>
</template>

API

属性	类型	默认值	说明
Avatar size	`'sm' \| 'default' \| 'lg'`	`'default'`	头像尺寸。
AvatarImage src	`string`	`—`	必填图片地址；加载状态由 Reka UI 管理。
AvatarImage loadingStatusChange	`'idle' \| 'loading' \| 'loaded' \| 'error'`	`—`	图片加载状态变化事件。
AvatarFallback delayMs	`number`	`undefined`	延迟显示回退内容的毫秒数。
AvatarBadge class	`HTMLAttributes["class"]`	`undefined`	合并到状态徽标上的调用方类。
AvatarGroup class	`HTMLAttributes["class"]`	`undefined`	合并到头像分组上的调用方类。
AvatarGroupCount class	`HTMLAttributes["class"]`	`undefined`	合并到剩余数量标记上的调用方类。
Avatar as / asChild	`string \| Component / boolean`	`'span' / false`	来自 Reka Primitive 的元素组合能力。

无障碍说明

AvatarImage 需要可理解的 alt；纯装饰头像可使用空 alt。仅颜色表达的 AvatarBadge 必须配合屏幕阅读器文本或 aria-label。

关联组件

状态徽记信息条目