Avatar 头像
显示用户头像,可以是图片、图标或文字。多个头像可以用 NsAvatarGroup 排成一组。
引入
import { NsAvatar, NsAvatarGroup } from '@ns/ui'
基础用法
src 传图片地址。没有 src、icon、label 时显示一个默认的人像图标。
<script setup lang="ts">
import { NsAvatar, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace wrap>
<NsAvatar src="/images/user.png" alt="张三" />
<NsAvatar />
</NsSpace>
</template>
图标和文字
icon 显示图标,label 显示文字。label 会转成大写并整串显示,建议只传 1 到 2 个字。默认插槽可以放自定义内容,只在没有 src、icon、label 时显示。
<script setup lang="ts">
import { NsAvatar, NsIcon, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsAvatar icon="user" />
<NsAvatar icon="users" bg-color="#13c2c2" />
<NsAvatar icon="star" bg-color="#faad14" />
<NsAvatar icon="setting" bg-color="#722ed1" />
</NsSpace>
<NsSpace wrap>
<NsAvatar label="张" bg-color="#1890ff" />
<NsAvatar label="李四" bg-color="#52c41a" />
<NsAvatar label="ns" bg-color="#fa541c" />
<NsAvatar>U</NsAvatar>
<NsAvatar bg-color="#eb2f96">
<NsIcon name="heart" />
</NsAvatar>
</NsSpace>
</NsSpace>
</template>
显示的优先级:图片 > 备用图 > icon > label > 默认插槽(默认插槽不写时是人像图标)。
尺寸和形状
size 可以是 large(40px)、default(32px)、small(24px),也可以直接传像素数字。传数字时,文字和图标的字号按尺寸的 0.4 倍缩放。size 不写时跟随头像组,再跟随 NsConfigProvider,都没设置时是 default。
shape 有 circle(圆形,默认)和 square(圆角方形)两种。方形的圆角跟着尺寸走:large 8px、default 6px、small 4px,数字尺寸 6px。
下面每一行是一种形状,从左到右是 large、default、small 和数字 48、64:
<script setup lang="ts">
import { NsAvatar, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap align="center">
<span class="row-label">circle</span>
<NsAvatar icon="user" size="large" />
<NsAvatar icon="user" />
<NsAvatar icon="user" size="small" />
<NsAvatar label="字" :size="48" />
<NsAvatar src="/images/user.png" alt="张三" :size="64" />
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">square</span>
<NsAvatar icon="user" shape="square" size="large" />
<NsAvatar icon="user" shape="square" />
<NsAvatar icon="user" shape="square" size="small" />
<NsAvatar label="字" shape="square" :size="48" />
<NsAvatar src="/images/user.png" alt="张三" shape="square" :size="64" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
图片填充方式
fit 对应图片的 object-fit,默认 cover。下面用一张 3:1 的宽图放进 64px 的方形头像里对比 5 种取值:
fill:拉伸铺满,图片变形。contain:完整显示,上下留出背景色。cover:铺满并保持比例,左右裁掉。none:按原始尺寸显示,只能看到中间一小块。scale-down:取none和contain里较小的一个,这张图比头像大,所以和contain一样。
<script setup lang="ts">
import { NsAvatar, NsSpace } from '@ns/ui'
import type { AvatarFit } from '@ns/ui'
const fits: AvatarFit[] = ['fill', 'contain', 'cover', 'none', 'scale-down']
</script>
<template>
<NsSpace wrap size="large">
<NsSpace v-for="fit in fits" :key="fit" direction="vertical" align="center">
<NsAvatar src="/images/wide.png" :fit="fit" shape="square" :size="64" />
<span class="caption">{{ fit }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
加载失败和备用图
主图加载失败时,有 fallback-src 就改用备用图;备用图也失败(或没有备用图)时,依次显示 icon、label、默认插槽。每张图失败时都会触发一次 error 事件。改了 src 或 fallback-src 后会重新加载。
<script setup lang="ts">
import { ref } from 'vue'
import { NsAvatar, NsSpace } from '@ns/ui'
const errorCount = ref(0)
</script>
<template>
<NsSpace wrap align="center">
<NsAvatar src="/broken.png" fallback-src="/images/default-user.png" @error="errorCount++" />
<NsAvatar src="/broken.png" icon="user" />
<NsAvatar src="/broken.png" label="李" bg-color="#1890ff" />
<NsAvatar src="/broken.png" />
<span>失败 {{ errorCount }} 次</span>
</NsSpace>
</template>
图片加载成功时触发 load。点按钮在一个能加载的地址和一个失败的地址之间切换,看事件和显示内容的变化:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAvatar, NsButton, NsSpace } from '@ns/ui'
const good = '/images/avatar.jpg'
const src = ref(good)
const status = ref('加载中')
const toggle = () => {
src.value = src.value === good ? '/broken.png' : good
status.value = '加载中'
}
</script>
<template>
<NsSpace wrap align="center">
<NsAvatar
:src="src"
label="王"
bg-color="#52c41a"
size="large"
@load="status = '触发了 load,显示图片'"
@error="status = '触发了 error,改为显示 label'"
/>
<NsButton size="small" @click="toggle">换地址</NsButton>
</NsSpace>
<p style="margin-top: 12px">当前地址:{{ src }},{{ status }}</p>
</template>
背景色和边框
bg-color 设置背景色,不写时是占位文字的灰色。border 传 true 时是 2px 实线、颜色跟随页面背景色(--ns-bg-color),放在有底色的地方才看得出来;也可以传对象自定义样式、宽度和颜色,对象里写 show: false 时不显示边框。
<script setup lang="ts">
import { NsAvatar, NsSpace } from '@ns/ui'
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsAvatar label="A" />
<NsAvatar label="A" bg-color="#ff4d4f" />
<NsAvatar label="B" bg-color="#1890ff" />
<NsAvatar icon="user" bg-color="#52c41a" />
</NsSpace>
<div class="tinted">
<NsSpace wrap>
<NsAvatar icon="user" />
<NsAvatar icon="user" border />
<NsAvatar icon="user" :border="{ show: false }" />
</NsSpace>
</div>
</NsSpace>
</template>
<style scoped>
.tinted {
padding: var(--ns-spacing-3);
background-color: var(--ns-fill-color);
border-radius: var(--ns-border-radius);
}
</style>
边框对象的 style 有 solid、dashed、dotted、double、none 五种,width 默认 2(像素),color 默认 var(--ns-bg-color):
<script setup lang="ts">
import { NsAvatar, NsSpace } from '@ns/ui'
import type { AvatarBorderStyle } from '@ns/ui'
const borderStyles: AvatarBorderStyle[] = ['solid', 'dashed', 'dotted', 'double', 'none']
</script>
<template>
<NsSpace wrap size="large">
<NsSpace v-for="item in borderStyles" :key="item" direction="vertical" align="center">
<NsAvatar label="B" size="large" :border="{ style: item, width: 4, color: '#1890ff' }" />
<span class="caption">{{ item }}</span>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.caption {
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
头像组
把多个 NsAvatar 放进 NsAvatarGroup。默认重叠排列,每个头像向左压 8px,并带一圈背景色描边;:overlap="false" 时并排。可以用 v-for 渲染头像,图片、图标、文字可以混着放。
<script setup lang="ts">
import { NsAvatar, NsAvatarGroup, NsSpace } from '@ns/ui'
const users = [
{ id: 1, name: '张' },
{ id: 2, name: '李' },
{ id: 3, name: '王' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsAvatarGroup>
<NsAvatar v-for="u in users" :key="u.id" :label="u.name" />
</NsAvatarGroup>
<NsAvatarGroup :overlap="false">
<NsAvatar v-for="u in users" :key="u.id" :label="u.name" />
</NsAvatarGroup>
</NsSpace>
<NsAvatarGroup>
<NsAvatar src="/images/user.png" alt="张三" />
<NsAvatar icon="user" bg-color="#13c2c2" />
<NsAvatar label="李" bg-color="#1890ff" />
<NsAvatar label="王" bg-color="#52c41a" />
<NsAvatar />
</NsAvatarGroup>
</NsSpace>
</template>
最大数量
max 限制显示的头像数,多出来的合并成一个“+N”。“+N”可以点击,也可以用 Tab 键聚焦后按回车或空格,都会触发 excess-click。下面点“+N”展开全部头像:
<script setup lang="ts">
import { ref } from 'vue'
import { NsAvatar, NsAvatarGroup, NsButton, NsSpace } from '@ns/ui'
const users = ['张', '李', '王', '赵', '钱', '孙', '周']
const max = ref<number | undefined>(3)
const showAll = () => {
max.value = undefined
}
</script>
<template>
<NsSpace wrap align="center">
<NsAvatarGroup :max="max" @excess-click="showAll">
<NsAvatar v-for="name in users" :key="name" :label="name" />
</NsAvatarGroup>
<NsButton v-if="max === undefined" size="small" @click="max = 3">收起</NsButton>
</NsSpace>
<p style="margin-top: 12px">
{{ max === undefined ? '已展开全部成员' : `只显示前 ${max} 个,点“+N”展开` }}
</p>
</template>
组的默认属性
头像组上的 size、shape、bg-color、border 是组内头像的默认值:头像自己没写时用组的值,自己写了就用自己的。“+N”也使用这几个值。
<script setup lang="ts">
import { NsAvatar, NsAvatarGroup, NsSpace } from '@ns/ui'
const users = ['张', '李', '王', '赵', '钱']
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap align="center">
<span class="row-label">large</span>
<NsAvatarGroup size="large" :max="3" bg-color="#1890ff">
<NsAvatar v-for="name in users" :key="name" :label="name" />
</NsAvatarGroup>
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">default</span>
<NsAvatarGroup :max="3" bg-color="#1890ff">
<NsAvatar v-for="name in users" :key="name" :label="name" />
</NsAvatarGroup>
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">small</span>
<NsAvatarGroup size="small" :max="3" bg-color="#1890ff">
<NsAvatar v-for="name in users" :key="name" :label="name" />
</NsAvatarGroup>
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">square</span>
<NsAvatarGroup shape="square" :max="3" bg-color="#52c41a" :overlap="false">
<NsAvatar v-for="name in users" :key="name" :label="name" />
</NsAvatarGroup>
</NsSpace>
<NsSpace wrap align="center">
<span class="row-label">自己优先</span>
<NsAvatarGroup size="small" shape="square">
<NsAvatar label="张" />
<!-- 这个头像是 large、圆形 -->
<NsAvatar label="李" size="large" shape="circle" />
<NsAvatar label="王" bg-color="#fa541c" />
</NsAvatarGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
NsAvatar Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| src | string | - | 图片地址 |
| fallbackSrc | string | - | 主图加载失败时使用的备用图片地址 |
| icon | string | - | 图标名,没有图片或图片都加载失败时显示 |
| label | string | - | 文字,没有图片和图标时显示。会转成大写 |
| size | 'large' | 'default' | 'small' | number | 'default' | 尺寸,数字的单位是像素。不写时用头像组的 size,再跟随 NsConfigProvider 的 size,都没有时是 'default' |
| shape | 'circle' | 'square' | 'circle' | 形状。不写时用头像组的 shape,再没有就是 'circle' |
| fit | 'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | 'cover' | 图片的填充方式 |
| alt | string | - | 图片的替代文字 |
| bgColor | string | - | 背景色。不写时用头像组的 bgColor |
| border | AvatarBorder | boolean | - | 边框。true 是 2px 实线、背景色描边;不写时用头像组的 border |
NsAvatar Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| load | (event: Event) | 图片(主图或备用图)加载成功时触发 |
| error | (event: Event) | 图片加载失败时触发,主图和备用图失败时各触发一次 |
NsAvatar Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 没有 src、icon、label,或者图片都加载失败又没有 icon、label 时显示。默认是人像图标 |
NsAvatarGroup Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| max | number | - | 最多显示的头像数,多出来的合并成“+N”。不写时全部显示 |
| overlap | boolean | true | 是否重叠排列 |
| size | 'large' | 'default' | 'small' | number | - | 组内头像自己没写 size 时使用的尺寸,也用于“+N” |
| shape | 'circle' | 'square' | - | 组内头像自己没写 shape 时使用的形状,也用于“+N” |
| bgColor | string | - | 组内头像自己没写 bgColor 时使用的背景色,也用于“+N” |
| border | AvatarBorder | boolean | - | 组内头像自己没写 border 时使用的边框,也用于“+N” |
NsAvatarGroup Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| excess-click | (event: MouseEvent) | 点击“+N”,或者聚焦“+N”后按回车、空格时触发 |
NsAvatarGroup Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsAvatar,可以用 v-for、v-if、<template>。不是 NsAvatar 的内容会被过滤掉,不显示 |
类型
import type {
AvatarProps,
AvatarEmits,
AvatarSize,
AvatarShape,
AvatarFit,
AvatarBorder,
AvatarBorderStyle,
AvatarGroupProps,
AvatarGroupEmits
} from '@ns/ui'
type AvatarSize = 'large' | 'default' | 'small' | number
type AvatarShape = 'circle' | 'square'
type AvatarFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
type AvatarBorderStyle = 'solid' | 'dashed' | 'dotted' | 'double' | 'none'
interface AvatarBorder {
show?: boolean // 是否显示,默认 true
style?: AvatarBorderStyle // 默认 'solid'
width?: number // 像素,默认 2
color?: string // 默认 'var(--ns-bg-color)'
}
interface AvatarProps {
src?: string
fallbackSrc?: string
icon?: string
label?: string
size?: AvatarSize
shape?: AvatarShape
fit?: AvatarFit
alt?: string
bgColor?: string
border?: AvatarBorder | boolean
}
interface AvatarGroupProps {
max?: number
overlap?: boolean
size?: AvatarSize
shape?: AvatarShape
bgColor?: string
border?: AvatarBorder | boolean
}
另外还导出了注入用的 AVATAR_GROUP_INJECTION_KEY,自己写和 NsAvatarGroup 配合的子组件时才用得到。
注意事项
NsAvatar要直接放在NsAvatarGroup的默认插槽里(可以隔着v-for、v-if和<template>)。包在自己写的组件里再放进来,会被当成“不是头像”过滤掉。- 头像组上的
size、shape、bgColor、border只是默认值,头像自己写了就以头像为准。 label会整串转成大写,放不下的部分会被裁掉,建议只传 1 到 2 个字。- 备用图加载成功后会一直显示备用图,不会再去重试主图;要重试就换一个
src。 border默认的描边色是var(--ns-bg-color),在暗色主题下跟着变成深色。放在有底色的容器里时,可以传对象指定颜色。
优化点
- [ ] 支持头像和徽章组合
- [ ] 支持加载中的状态
- [ ] 支持懒加载
- [ ] 支持
srcset - [ ] “+N”悬停时展示被收起的头像