Avatar 头像
用于展示用户头像信息,支持图片、文字、图标,以及头像组等多种形态。
基础用法
通过 src 设置图片地址,通过 alt 设置首字母缩写,或通过默认插槽传入自定义内容:

王赵N不同尺寸
提供 xs / sm / md / lg / xl 五种预设尺寸,也支持传入数字自定义大小:






形状
通过 shape 设置头像形状:circle(圆形)、square(方形)、rounded(圆角方形):



自定义背景色
通过 color 属性设置头像背景色,适用于文字头像:
ABCDEF
边框头像
设置 bordered 属性在头像周围添加白色边框,常用于头像组中区分重叠的头像:

N图片填充模式
通过 fit 属性设置图片填充方式,等同于 CSS object-fit 属性:
cover
contain
fill
none在线状态指示器
通过 show-indicator 显示在线状态点,indicator-status 设置状态:online / offline / busy / away,indicator-position 设置位置:
在线
离线
忙碌
离开指示器位置
通过 indicator-position 设置指示器位置:top-right / top-left / bottom-right / bottom-left:
右上
左上
左下
右下头像组
使用 NAvatarGroup 组合多个头像,支持设置最大显示数量和方向:
默认头像组

王赵孙不同尺寸

C结合徽标
搭配 NBadge 组件展示未读消息数等信息:
5
99N组合用法
在卡片等容器中使用头像,构建用户信息展示:

张三
前端工程师 · 在线
热爱开源,专注于 Vue 生态和组件库开发。
Avatar Props
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | — | 图片地址 |
alt | string | — | 图片替代文本,也用于生成首字母缩写(支持双字名如"张三"→"张三"两字首字母) |
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | 'md' | 尺寸 |
shape | 'circle' | 'square' | 'rounded' | 'circle' | 形状 |
round | boolean | true | 是否为圆形(兼容旧版本,推荐使用 shape) |
fit | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | 'cover' | 图片填充模式,等同于 CSS object-fit |
color | string | — | 自定义背景色 |
bordered | boolean | false | 是否显示边框 |
fallback | string | — | 图片加载失败时的备用地址 |
show-indicator | boolean | false | 是否显示在线状态指示器 |
indicator-status | 'online' | 'offline' | 'busy' | 'away' | 'online' | 指示器状态 |
indicator-position | 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'bottom-right' | 指示器位置 |
Avatar Events
| 事件名 | 参数 | 说明 |
|---|---|---|
load | (e: Event) | 图片加载成功时触发 |
error | (e: Event) | 图片加载失败时触发 |
Avatar Slots
| 插槽名 | 说明 |
|---|---|
default | 自定义头像内容(图片加载失败或无 src 时显示) |
AvatarGroup Props
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number | 'md' | 统一设置组内头像尺寸 |
shape | 'circle' | 'square' | 'rounded' | 'circle' | 统一设置组内头像形状 |
color | string | — | 统一设置组内文本头像背景色 |
bordered | boolean | true | 是否显示边框(头像组默认开启) |
max | number | Infinity | 最大显示头像数量 |
direction | 'left' | 'right' | 'left' | 头像排列方向 |
closable | boolean | false | 是否可关闭 |