Avatar

Avatar 组件用于表示一个用户，并显示头像图片、姓名缩写或回退图标。

安装

npm

npm add @heroui-vue/avatar

pnpm

pnpm add @heroui-vue/avatar

yarn

yarn add @heroui-vue/avatar

bun

bun add @heroui-vue/avatar

NOTE

如果你使用的是全局安装，可以跳过这一步。

导入

HeroUI Vue 当前导出 2 个头像相关组件：

• Avatar：用于展示单个头像的主组件。
• AvatarGroup：用于组合展示多个头像的容器组件。

HeroUI Vue 暂时没有独立导出 AvatarIcon 组件。你可以使用内置回退图标，或通过 icon 自定义。

按需导入

import { Avatar, AvatarGroup } from '@heroui-vue/avatar'

全局导入

import { Avatar, AvatarGroup } from 'heroui-vue'

用法

预览源代码

JJJ

尺寸

预览源代码

禁用

预览源代码

JJJ

边框

预览源代码

圆角

预览源代码

颜色

预览源代码

Avatar 回退内容

当头像 src 加载失败时，有 2 种回退方式：

• 如果传了 name，会根据名字生成缩写。
• 如果没有 name，会显示默认头像图标。

如果没有传 showFallback，则不会显示回退内容。

预览源代码

自定义回退内容

你也可以在 src 加载失败时提供自定义回退内容。

预览源代码

自定义实现

如果你需要更底层地自定义 Avatar 行为，HeroUI Vue 当前把 useAvatar 作为内部组合式工具，暂未作为稳定公共 API 暴露。

自定义姓名缩写逻辑

HeroUI React 支持用 getInitials 自定义缩写逻辑。HeroUI Vue 暂未暴露该属性；当前默认会从 name 中最多取前两个单词的首字母。

Avatar Group

预览源代码

Group Disabled

预览源代码

Group Max Count

你可以通过 max 属性限制 AvatarGroup 显示的头像数量。

预览源代码

+3

Group Total Count

你可以通过 total 属性指定头像总数。

预览源代码

+7

Group Custom count

HeroUI React 的 renderCount 支持渲染函数。HeroUI Vue 当前的 renderCount 是布尔开关，用于显示/隐藏内置计数徽标。

预览源代码

Group Grid

给 AvatarGroup 传入 isGrid 后，头像会以网格布局展示。

预览源代码

+2

Group Custom Implementation

如果你需要更底层地自定义头像组，HeroUI React 提供了 useAvatarGroup 和 AvatarGroupProvider。HeroUI Vue 目前尚未暴露对应公共 API。

插槽

• base：Avatar 外层容器，包含焦点环、定位和整体外观样式。
• img：Avatar 内的图片元素，包含透明度过渡和尺寸样式。
• fallback：图片加载失败或未提供时的回退内容容器。
• name：图片缺失/失败时显示的姓名缩写内容。
• icon：Avatar 回退状态下的图标容器。

自定义 Avatar 样式

你可以通过 classNames 自定义 Avatar 各个部位的样式。

预览源代码

Data Attributes

Avatar 在 base 元素上有这些数据属性：

• data-hover：头像处于 hover 状态时。
• data-focus：头像获得焦点时。
• data-focus-visible：键盘导航导致焦点可见时。

API

Avatar 属性

名称	类型	默认值	描述
src	string	-	要显示的图片地址。
color	"default" | "primary" | "secondary" | "success" | "warning" | "danger"	"default"	设置头像背景色。
radius	"none" | "sm" | "md" | "lg" | "full"	"full"	设置头像圆角。
size	"sm" | "md" | "lg"	"md"	设置头像尺寸。
name	string	-	图片缺失或加载失败时显示姓名缩写。
icon	any	-	在头像回退状态中显示自定义图标。
fallback	any	-	图片加载失败时显示的自定义回退内容。
isBordered	boolean	false	是否显示头像边框。
isDisabled	boolean	false	是否禁用头像并应用禁用样式。
isFocusable	boolean	false	是否支持键盘聚焦。
showFallback	boolean	false	图片加载失败时是否显示回退图标/缩写。
imgProps	ImgHTMLAttributes	-	透传给内部图片元素的属性。
classNames	Partial<Record<"base" | "img" | "fallback" | "name" | "icon", string>>	-	Avatar 各插槽的自定义类名。

Avatar Group 属性

名称	类型	默认值	描述
max	number	-	可见头像的最大数量。
total	number	-	控制不可见头像数量。
isGrid	boolean	false	是否以网格布局展示头像。
renderCount	boolean	true	是否渲染内置计数徽标。
classNames	Partial<Record<"base" | "count", string>>	-	头像组插槽自定义类名。