Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
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”悬停时展示被收起的头像