Avatar 头像

Avatar 用于代表人物或对象。VISTA B 直接使用 Element Plus 的 el-avatar，常用场景以默认头像、图片头像和文字头像为主；需要多人聚合时可使用 el-avatar-group。

基础用法

使用 shape 设置圆形或方形头像，使用 size 设置头像尺寸。size 支持 small、default、large，也可以直接传入数字。

circle

square

<el-avatar :size="50" :src="circleUrl" />
<el-avatar shape="square" size="large" :src="squareUrl" />

展示类型

Avatar 支持图片、图标和文字三种展示内容。文字头像适合展示用户名首字，例如“唐雷”显示为“唐”。

图标

图片

唐文字

<el-avatar :icon="UserFilled" />
<el-avatar :src="avatarUrl" />
<el-avatar>唐</el-avatar>

默认头像与文字头像

业务中没有用户头像时，可使用统一的默认头像或姓名首字头像。文字头像建议保持一个汉字或两个英文字母，避免内容溢出。

唐林陈王

<el-avatar :icon="UserFilled" />
<el-avatar>唐</el-avatar>

回退行为

当图片加载失败时会触发 error 事件。返回 true 时会继续展示默认插槽中的回退内容。

error count: 0

<el-avatar :size="60" src="https://empty" @error="errorHandler">
  <img :src="fallbackUrl" alt="Fallback avatar" />
</el-avatar>

适应容器

图片头像可以使用 fit 设置图片在容器中的填充方式，取值与 CSS object-fit 保持一致。

fill

contain

cover

none

scale-down

<el-avatar shape="square" :size="100" fit="cover" :src="url" />

头像组

使用 el-avatar-group 可以展示头像组。开启 collapse-avatars 后，超过数量的头像会被折叠为数字提示。

default

collapse-avatars

+ 4

max-collapse-avatars

+ 2

collapse tooltip

+ 2

<el-avatar-group collapse-avatars :max-collapse-avatars="3">
  <el-avatar v-for="user in users" :key="user.id" :src="user.avatar" />
</el-avatar-group>

API

Avatar 属性

属性	说明	类型	默认值
icon	设置头像图标	string / Component	空
size	头像大小	number / small / default / large	空
shape	头像形状	circle / square	空
src	图片头像的源地址	string	空
src-set	图片头像原生 srcset 属性	string	空
alt	图片头像原生 alt 属性	string	空
fit	图片如何适应容器	fill / contain / cover / none / scale-down	cover

Avatar 事件

事件名	说明	类型
error	图片加载失败时触发	(event: Event) => boolean

Avatar 插槽

插槽	说明
default	自定义头像展示内容

AvatarGroup 属性

属性	说明	类型	默认值
size	控制头像组中的头像大小	number / small / default / large	空
shape	控制头像组中的头像形状	circle / square	空
collapse-avatars	是否折叠头像	boolean	false
collapse-avatars-tooltip	是否在悬停折叠头像时展示所有折叠头像，需同时开启 collapse-avatars	boolean	false
max-collapse-avatars	折叠前最多显示的头像数量，需同时开启 collapse-avatars	number	1
effect	Tooltip 主题	dark / light / string	light
placement	Tooltip 展示位置	enum	top
popper-class	Tooltip 自定义类名	string	空
popper-style	Tooltip 自定义样式	string / object	空
collapse-class	折叠头像的自定义类名	string	空
collapse-style	折叠头像的自定义样式	string / object	空

使用提醒

文字头像建议使用真实姓名首字或固定缩写，并与默认头像策略保持一致。图片头像需要补充 alt，在上传或加载失败时提供回退内容，避免头像区域空白。