uView Pro X

简体中文

English

简体中文

English

主题

Avatar 头像 ​

17:06

说明 ​

在图片、文字与默认头像之间切换的头像组件。传入 src 显示图片，为空或加载失败时退回内置默认头像；传入 text 显示首字符文字头像，配合 bg-color 设置背景。shape 控制正圆或方形，size 支持 large / default / small 或自定义 px。可在右上角叠加性别角标（show-sex）、右下角叠加等级图标（show-level）。

兼容性 ​

平台支持情况
App✅ 支持
H5✅ 支持
微信小程序✅ 支持

示例 ​

基础用法 ​

传入 src 展示图片头像，支持 large/default/mini 及自定义尺寸。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" @click="onClick" />
        <ux-avatar size="large" src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" />
        <ux-avatar size="small" src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" />
    </view>
</template>

<script setup lang="uts">
const onClick = (index: string | number) => {
    uni.showToast({ title: '点击了头像: ' + index, icon: 'none' });
};
</script>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
    flex-wrap: wrap;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

文字头像 ​

传入 text 时显示首字符作为占位，配合 bg-color 自定义背景。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" />
        <ux-avatar text="B" bg-color="#19be6b" size="large" />
        <ux-avatar text="C" bg-color="#fa3534" size="small" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

形状 shape ​

shape="circle" 正圆（默认），shape="square" 小圆角 4px 方形；图片与文字头像各对比一档。

查看源码
vue
<template>
    <!-- shape 两档全演示：circle 正圆（不传即此档） / square 小圆角 4px 方形 -->
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" shape="circle" />
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" shape="square" custom-class="avatar-item" />
        <ux-avatar text="A" bg-color="#2979ff" shape="circle" size="large" custom-class="avatar-item" />
        <ux-avatar text="B" bg-color="#19be6b" shape="square" size="large" custom-class="avatar-item" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

性别角标 show-sex ​

show-sex=true 时右上角显示性别图标，man 为男、woman 为女。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-sex sex-icon="man" />
        <ux-avatar text="B" bg-color="#fa3534" show-sex sex-icon="woman" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

等级图标 show-level ​

show-level=true 时右下角显示等级图标，可自定义背景色。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-level />
        <ux-avatar text="B" bg-color="#fa3534" show-level level-bg-color="#ff9900" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

自定义角标颜色 ​

通过 sex-bg-color / level-bg-color 自定义角标背景色。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar text="A" bg-color="#2979ff" show-sex sex-icon="man" sex-bg-color="#19be6b" />
        <ux-avatar text="B" bg-color="#fa3534" show-level level-bg-color="#2979ff" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

图片裁剪模式 img-mode ​

通过 img-mode 设置图片裁剪模式，aspectFill 为等比填充，scaleToFill 为拉伸铺满。

查看源码
vue
<template>
    <view class="avatar-row">
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" img-mode="aspectFill" />
        <ux-avatar src="https://ik.imagekit.io/anyup/uview-pro/avatar/avatar1.png" img-mode="scaleToFill" size="large" />
    </view>
</template>

<style scoped>
.avatar-row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.avatar-row ux-avatar {
    margin-right: 16px;
}
</style>

API ​

Props ​

属性说明类型默认值版本
customStyle自定义根节点样式string | UTSJSONObject--
customClass自定义根节点样式类string''-
bgColor背景颜色string'transparent'-
src头像路径string''-
size尺寸string | number'default'-
shape头像形状（词表见 types/global.uts 的 Shape）：square-小圆角 4px 方形，circle-正圆；原名 mode'square' | 'circle''circle'-
text文字内容string''-
imgMode图片的裁剪模型ImgMode'aspectFill'-
index标识符string | number''-
sexIcon右上角性别角标string'man'-
levelIcon右下角的等级图标string'level'-
levelBgColor右下角等级图标背景颜色string''-
sexBgColor右上角性别图标的背景颜色string''-
showSex是否显示性别图标booleanfalse-
showLevel是否显示等级图标booleanfalse-

Events ​

事件名说明回调参数版本
click头像被点击index: string | number-

Slots ​

插槽名说明版本
default自定义头像内容，作为未提供 src / text 时的兜底占位-

注意事项 ​

  1. src 为空字符串或图片加载失败（@error）时会退回组件内置的 base64 默认头像；因此即便不传 src / text，组件也会渲染该默认头像，默认插槽（无图无文字的兜底占位）通常不会显示。
  2. text 只取第一个字符作为文字头像，字号随 size 等比缩放（约 0.4 倍，限制在 10–28px）。
  3. 文字头像的文字颜色固定为白色（主题 $u-white-color），背景需通过 bg-color 指定；bg-color 默认 transparent，不传则无背景色。
  4. size 预设 large=60 / default=45 / small=30（px），传数值则按 px 处理且宽高相等。
  5. shape 原名 mode，已更名对齐词表：circle 正圆、square 为 4px 小圆角方形。自定义圆角走 custom-style 仅对文字/背景头像生效，图片头像的圆角写在内层 imgStyle，外层样式覆盖不到。
  6. 性别/等级角标为绝对定位且 right: -7%，会凸出到头像外，依赖根节点 overflow: visible（组件已声明）；show-sex 默认 sex-icon="man"（背景主题色 primary），woman 用 error 色，none 用 warning 色；show-level 默认 warning 色，可用 level-bg-color 覆盖。
  7. img-mode 与 uni image 的 mode 一致，默认 aspectFill；效果达不到需求可尝试 widthFix。
Copyright © 2026 uView Pro X | 鲁ICP备2021040594号-5