Avatar 头像

新粗野主义风格的头像组件，用于显示用户头像图片，支持回退显示。包含 Avatar、AvatarImage、AvatarFallback 三个子组件，支持多种变体、尺寸、形状和状态指示。

预览

Preview

尺寸

小默认大特大

形状

方形圆角

带图片

用户用户

变体

默主次强

状态

在在线离离线忙忙碌无

工牌吊孔（lanyard）

工班在线

安装

pnpm dlx brutx-vue@latest add avatar

用法

<script setup>
import { Avatar, AvatarImage, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar size="default" shape="square">
        <AvatarImage src="/avatar.jpg" alt="User avatar" />
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

回退行为

当图片加载失败时，AvatarFallback 会自动显示：

<script setup>
import { Avatar, AvatarImage, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar>
        <AvatarImage src="/broken-url.jpg" alt="User" />
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

状态指示

在头像右下角渲染状态小圆点（w-3 h-3 rounded-full border-3 border-brutal-bg）。status="none"（默认）时不渲染。

状态	颜色	说明
online	bg-brutal-success	在线（绿色）
offline	bg-brutal-muted	离线（灰色）
busy	bg-brutal-destructive	忙碌（红色）
none	—	不渲染（默认）

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar size="lg" status="online">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" status="offline">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" status="busy">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    </div>
</template>

变体

控制头像根容器与 AvatarFallback 的背景色，通过 provide/inject 下发给子组件。

变体	根容器背景	回退背景
default	bg-brutal-muted/20	bg-brutal-muted
primary	bg-brutal-primary/20	bg-brutal-primary
secondary	bg-brutal-secondary/20	bg-brutal-secondary
accent	bg-brutal-accent/20	bg-brutal-accent

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar size="lg" variant="default">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="primary">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="secondary">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
        <Avatar size="lg" variant="accent">
            <AvatarFallback>JD</AvatarFallback>
        </Avatar>
    </div>
</template>

尺寸

尺寸	大小
sm	h-8 w-8（32px）
default	h-10 w-10（40px）
lg	h-14 w-14（56px）
xl	h-20 w-20（80px）

形状

形状	说明
square	无圆角（默认）
rounded	使用 --brutal-radius 令牌

<script setup>
import { Avatar, AvatarFallback } from 'brutx-ui-vue'
</script>

<template>
    <Avatar size="lg" shape="rounded">
        <AvatarFallback>JD</AvatarFallback>
    </Avatar>
</template>

子组件

组件	说明
Avatar	根容器，提供尺寸、形状、变体和状态上下文
AvatarImage	头像图片，加载失败时自动隐藏
AvatarFallback	回退内容，图片不可见时自动显示

API 参考

Avatar

Avatar — 属性

名称	类型	默认值	说明
variant	"accent" | "default" | "primary" | "secondary" | undefined	"default"	设置头像回退内容的颜色变体。
详情 声明类型 NonNullable<"default" | "primary" | "secondary" | "accent" | null | undefined> | undefined 字面量 "accent" "default" "primary" "secondary" 默认值详情 声明 'default' 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 "default" 来源 Avatar.vue:15 packages/ui/src/components/avatar/Avatar.vue
size	"default" | "lg" | "sm" | "xl" | undefined	"default"	设置头像容器及其内容的尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | "xl" | null | undefined> | undefined 字面量 "default" "lg" "sm" "xl" 默认值详情 声明 'default' 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 "default" 来源 Avatar.vue:16 packages/ui/src/components/avatar/Avatar.vue
shape	"rounded" | "square" | undefined	"square"	设置头像容器为方形或圆角形状。
详情 声明类型 NonNullable<"square" | "rounded" | null | undefined> | undefined 字面量 "rounded" "square" 默认值详情 声明 'square' 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 "square" 来源 Avatar.vue:17 packages/ui/src/components/avatar/Avatar.vue
status	AvatarStatus | undefined	"none"	设置头像右下角的状态指示点；none 时不显示状态点。
详情 声明类型 AvatarStatus | undefined 字面量 "busy" "none" "offline" "online" 关联类型 AvatarStatus 类型定义 — AvatarStatus type AvatarStatus = 'online' | 'offline' | 'busy' | 'none' 默认值详情 声明 'none' 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 "none" 来源 Avatar.vue:18 packages/ui/src/components/avatar/Avatar.vue
lanyard	boolean | undefined	false	显示顶部吊孔装饰；该装饰层从无障碍树中隐藏。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 false 来源 Avatar.vue:20 packages/ui/src/components/avatar/Avatar.vue
class	string | undefined	undefined	追加到头像根容器的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/Avatar.vue 解析值 undefined 来源 Avatar.vue:21 packages/ui/src/components/avatar/Avatar.vue

Avatar — 插槽

名称	签名或类型	说明
#default	{}	组合 AvatarImage 与 AvatarFallback 子组件。
详情 声明类型 {} 来源 Avatar.vue packages/ui/src/components/avatar/Avatar.vue

AvatarFallback

AvatarFallback — 属性

名称	类型	默认值	说明
delayMs	number | undefined	undefined	设置图片加载失败或仍在加载时，回退内容出现前的延迟；省略时立即显示。
详情 声明类型 number | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/AvatarFallback.vue 解析值 undefined 来源 AvatarFallback.vue:10 packages/ui/src/components/avatar/AvatarFallback.vue
class	string | undefined	undefined	追加到回退内容根元素的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/AvatarFallback.vue 解析值 undefined 来源 AvatarFallback.vue:11 packages/ui/src/components/avatar/AvatarFallback.vue
asChild	boolean | undefined	undefined	将根元素语义和属性合并到唯一的默认插槽子元素上；启用时 as 不生效。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/AvatarFallback.vue 解析值 undefined 来源 AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue
as	AsTag | Component | undefined	"span"	指定根节点渲染成的 HTML 标签或 Vue 组件；asChild 优先。
详情 声明类型 AsTag | Component | undefined 字面量 "a" "button" "div" "form" "h2" "h3" "img" "input" "label" "li" "nav" "ol" "p" "span" "svg" "template" "ul" 默认值详情 声明 'span' 来源: packages/ui/src/components/avatar/AvatarFallback.vue 解析值 "span" 来源 AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue

AvatarFallback — 插槽

名称	签名或类型	说明
#default	{}	图片不可用时显示的文字、图标或其他回退内容。
详情 声明类型 {} 来源 AvatarFallback.vue packages/ui/src/components/avatar/AvatarFallback.vue

AvatarImage

AvatarImage — 属性

名称	类型	默认值	说明
src	string | undefined	undefined	头像图片的 URL。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/AvatarImage.vue 解析值 undefined 来源 AvatarImage.vue:7 packages/ui/src/components/avatar/AvatarImage.vue
alt	string | undefined	""	图片的替代文本；默认空字符串将图片作为装饰内容处理。
详情 声明类型 string | undefined 默认值详情 声明 '' 来源: packages/ui/src/components/avatar/AvatarImage.vue 解析值 "" 来源 AvatarImage.vue:8 packages/ui/src/components/avatar/AvatarImage.vue
class	string | undefined	undefined	追加到头像图片元素的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/avatar/AvatarImage.vue 解析值 undefined 来源 AvatarImage.vue:9 packages/ui/src/components/avatar/AvatarImage.vue

可访问性

• ARIA 属性：状态圆点使用 role="status"（live region），其内 sr-only 文本承载状态标签；状态或语言切换时文本更新会被屏幕阅读器播报
• 国际化：状态标签通过 i18n 提供本地化文本：
  • online → "在线"
  • offline → "离线"
  • busy → "忙碌"