smqjh-refuel/.agent/skills/wot-ui/references/avatar.md

---

url: 'https://wot-ui.cn/component/avatar.md'

Avatar 头像

用来代表用户或事物，支持图片、文本或图标展示。

基础用法

头像支持三种类型：图片、文本、图标。

const avatarURL = 'https://wot-ui.cn/assets/panda.jpg'

<wd-avatar :src="avatarURL" />
<wd-avatar text="U" />
<wd-avatar icon="user" />

头像形状

使用 shape 属性设置头像形状，支持 round（圆形）和 square（方形），默认为 round。

<wd-avatar :src="avatarURL" shape="square" />
<wd-avatar :src="avatarURL" shape="round" />

头像尺寸

支持预设尺寸：large、medium、normal、small，默认为 normal。也可以传入数字或带单位的字符串（如 40px、100rpx）自定义尺寸。

<!-- 预设尺寸 -->
<wd-avatar :src="avatarURL" size="large" />
<wd-avatar :src="avatarURL" size="medium" />
<wd-avatar :src="avatarURL" size="normal" />
<wd-avatar :src="avatarURL" size="small" />

<!-- 自定义尺寸 -->
<wd-avatar :src="avatarURL" :size="80" />
<wd-avatar :src="avatarURL" size="60px" />
<wd-avatar :src="avatarURL" size="100rpx" />

自定义颜色

使用 bg-color 和 color 属性自定义背景色和文字颜色。

<wd-avatar bg-color="#DC143C" color="#fff" text="W" />
<wd-avatar bg-color="#228B22" color="#fff" text="O" />
<wd-avatar bg-color="#1E90FF" color="#fff" text="T" />
<wd-avatar bg-color="#EEEEEE" color="#7B8198" icon="user" />

带徽记的头像

结合 Badge 组件展示徽记。

<wd-badge modelValue="10" type="primary">
  <wd-avatar :src="avatarURL" shape="square" />
</wd-badge>
<wd-badge modelValue="20" type="danger">
  <wd-avatar :src="avatarURL" shape="square" />
</wd-badge>
<wd-badge is-dot>
  <wd-avatar :src="avatarURL" shape="square" />
</wd-badge>
<wd-badge is-dot>
  <wd-avatar text="A" shape="square" bg-color="#1E90FF" />
</wd-badge>

自定义内容

使用默认插槽自定义头像内容。

<wd-avatar>
  <view class="custom-content">VIP</view>
</wd-avatar>
<wd-avatar>
  <wd-icon name="star-on" size="24px" color="#f0883a" />
</wd-avatar>

可点击

通过监听 click 事件实现点击功能。

<wd-avatar :src="avatarURL" @click="handleClick" />
<wd-avatar text="点我" bg-color="#1E90FF" @click="handleClick" />

import { useToast } from '@/uni_modules/wot-design-uni'

const toast = useToast()

const handleClick = () => {
  toast.show('点击头像')
}

头像组

使用 wd-avatar-group 组件可以展示一组头像。

基础用法

<wd-avatar-group>
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
</wd-avatar-group>

最大数量

使用 max-count 属性限制显示的头像数量，超出部分会以 +N 形式展示。

<wd-avatar-group :max-count="3">
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
  <wd-avatar text="C" bg-color="#DC143C" />
</wd-avatar-group>

叠层方向

使用 cascading 属性设置叠层方向，支持 left-up（左侧叠在上层）和 right-up（右侧叠在上层）。

<wd-avatar-group cascading="left-up" :max-count="4">
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
  <wd-avatar text="C" bg-color="#DC143C" />
</wd-avatar-group>

<wd-avatar-group cascading="right-up" :max-count="4">
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
  <wd-avatar text="C" bg-color="#DC143C" />
</wd-avatar-group>

统一尺寸和形状

使用 size 和 shape 属性统一设置头像组中所有头像的尺寸和形状。使用 max-count 限制显示数量，超出部分会显示折叠头像。通过 collapse-avatar 可自定义折叠头像的文本内容。

<!-- 统一尺寸 -->
<wd-avatar-group size="large" :max-count="3">
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
</wd-avatar-group>

<!-- 统一形状，自定义折叠文本 -->
<wd-avatar-group shape="square" :max-count="3" :collapse-avatar="'+N'">
  <wd-avatar :src="avatarURL" />
  <wd-avatar icon="star-on" />
  <wd-avatar text="A" bg-color="#1E90FF" />
  <wd-avatar text="B" bg-color="#228B22" />
</wd-avatar-group>

Avatar Attributes

参数	说明	类型	可选值	默认值	最低版本
src	图片地址	string	-	-	1.14.0
text	文本内容	string	-	-	1.14.0
icon	图标名称，使用 wd-icon 组件	string	-	-	1.14.0
size	头像尺寸，支持预设尺寸或带单位的字符串	string	number	large / medium / normal / small	normal
shape	头像形状	string	round / square	round	1.14.0
bg-color	背景颜色	string	-	-	1.14.0
color	文字颜色	string	-	-	1.14.0
alt	图片加载失败时的占位文本	string	-	-	1.14.0
mode	图片填充模式，同 uni-app image 组件的 mode	string	-	aspectFill	1.14.0

Avatar Events

事件名称	说明	参数	最低版本
click	点击头像时触发	-	1.14.0
error	图片加载失败时触发	event	1.14.0

Avatar Slots

名称	说明	最低版本
default	自定义头像内容	1.14.0

Avatar 外部样式类

类名	说明	最低版本
custom-class	根节点样式	1.14.0
custom-style	根节点样式	1.14.0

AvatarGroup Attributes

参数	说明	类型	可选值	默认值	最低版本
max-count	最大显示数量	number	-	-	1.14.0
cascading	叠层方向	string	left-up / right-up	-	1.14.0
shape	统一设置头像形状	string	round / square	round	1.14.0
size	统一设置头像尺寸	string	number	large / medium / normal / small	normal
collapse-avatar	超出最大数量时折叠头像显示的内容	string	-	-	1.14.0

AvatarGroup Slots

名称	说明	最低版本
default	头像列表，放置 wd-avatar 组件	1.14.0

AvatarGroup 外部样式类

类名	说明	最低版本
custom-class	根节点样式	1.14.0
custom-style	根节点样式	1.14.0