xtf-avatar

组件说明

xtf-avatar 是头像组件，用于展示用户头像、占位文字或图标。支持图片加载失败自动回退为文字/图标，内置姓名首字母提取、哈希渐变色、状态指示点、光环和发光等丰富视觉效果，适用于通讯录、用户列表、评论区和个人中心等场景。

基础用法

1. 图片头像

通过 src 传入图片地址，size 控制尺寸：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center">
    <xtf-avatar src="https://picsum.photos/200/200?random=1" size="xs" />
    <xtf-avatar src="https://picsum.photos/200/200?random=2" size="sm" />
    <xtf-avatar src="https://picsum.photos/200/200?random=3" size="md" />
    <xtf-avatar src="https://picsum.photos/200/200?random=4" size="lg" />
    <xtf-avatar src="https://picsum.photos/200/200?random=5" size="xl" />
  </view>
</template>

2. 文字头像与姓名提取

不传 src 时，组件根据 name 或 text 自动提取首字母/汉字作为回退文字，并根据名字哈希生成渐变色：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center">
    <xtf-avatar name="张三" size="lg" />
    <xtf-avatar name="李四" size="lg" />
    <xtf-avatar name="王五" size="lg" />
    <xtf-avatar text="AB" size="lg" />
    <xtf-avatar text="CD" size="lg" />
  </view>
</template>

3. 主题色与自定义颜色

通过 theme 使用预设主题色，或通过 color / gradientEndColor / textColor 自定义渐变与文字颜色：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center">
    <xtf-avatar text="P" size="lg" theme="primary" />
    <xtf-avatar text="S" size="lg" theme="success" />
    <xtf-avatar text="W" size="lg" theme="warning" />
    <xtf-avatar text="D" size="lg" theme="danger" />
    <xtf-avatar text="I" size="lg" theme="info" />
    <xtf-avatar text="C" size="lg" color="#8B5CF6" gradient-end-color="#EC4899" />
  </view>
</template>

4. 形状与状态指示

通过 shape 切换形状（circle / rounded / rect / hexagon / squircle），通过 status 显示在线状态指示点：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center">
    <xtf-avatar
      src="https://picsum.photos/200/200?random=10"
      size="lg"
      shape="circle"
      status="online"
    />
    <xtf-avatar
      src="https://picsum.photos/200/200?random=11"
      size="lg"
      shape="rounded"
      status="busy"
    />
    <xtf-avatar
      src="https://picsum.photos/200/200?random=12"
      size="lg"
      shape="rect"
      status="away"
    />
    <xtf-avatar
      src="https://picsum.photos/200/200?random=13"
      size="lg"
      shape="hexagon"
      status="offline"
    />
    <xtf-avatar src="https://picsum.photos/200/200?random=14" size="lg" shape="squircle" />
  </view>
</template>

5. 光环与发光效果

通过 ring 显示渐变光环边框，通过 glow 添加阴影发光效果，通过 clickable 使头像可点击：

vue

<template>
  <view style="display: flex; gap: 24rpx; align-items: center">
    <xtf-avatar name="张三" size="xl" ring />
    <xtf-avatar name="李四" size="xl" ring ring-color="#8B5CF6" />
    <xtf-avatar name="王五" size="xl" glow />
    <xtf-avatar name="赵六" size="xl" ring glow clickable @click="onClick" />
  </view>
</template>

<script>
export default {
  methods: {
    onClick() {
      uni.showToast({ title: '点击了头像', icon: 'none' })
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`src`	`String`	`''`	头像图片地址，为空时显示文字/图标回退	设置图片头像
`name`	`String`	`''`	用户名，用于自动提取首字母和哈希渐变色	文字头像场景
`text`	`String`	`''`	自定义回退文字，优先级高于 `name` 的自动提取	精确控制回退文案
`shape`	`String`	`'circle'`	头像形状：`'circle'` / `'rounded'` / `'rect'` / `'hexagon'` / `'squircle'`，也兼容 `'square'` 等同 `'rect'`	适配不同设计风格
`size`	`String \| Number`	`''`	头像尺寸，支持预设 `'xs'` / `'sm'` / `'md'` / `'lg'` / `'xl'` / `'hero'` 或数值（rpx）	控制头像大小
`theme`	`String`	`''`	预设主题色：`'primary'` / `'success'` / `'warning'` / `'danger'` / `'info'` / `'secondary'` / `'inverse'`	快速设置渐变色
`color`	`String`	`''`	自定义渐变起始色，设置后 `theme` 失效	精确控制颜色
`gradientEndColor`	`String`	`''`	自定义渐变结束色，配合 `color` 使用	精确控制渐变
`textColor`	`String`	`''`	自定义回退文字颜色	精确控制文字色
`status`	`String`	`''`	状态指示点：`'online'` / `'busy'` / `'away'` / `'offline'`	展示用户在线状态
`ring`	`Boolean`	`false`	是否显示渐变光环边框	突出显示头像
`ringColor`	`String`	`''`	自定义光环颜色，默认跟随主题渐变	自定义光环色
`glow`	`Boolean`	`false`	是否显示发光阴影效果	增强视觉层次
`clickable`	`Boolean`	`false`	是否可点击，启用后点击有缩放反馈并触发 `click` 事件	头像可交互场景
`mode`	`String`	`'aspectFill'`	图片填充模式，对应 uni-app image 的 `mode` 属性	控制图片裁切方式
`objectFit`	`String`	`''`	图片填充模式别名，优先级高于 `mode`	兼容不同写法
`srcSet`	`String`	`''`	图片 srcset 属性，用于多分辨率适配	高清屏适配
`fallbackIcon`	`String`	`'person'`	图片加载失败且无文字时的回退图标名	自定义回退图标
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

预设尺寸对照

预设值	实际尺寸
`'xs'`	`40rpx`
`'sm'`	`48rpx`
`'md'`	`64rpx`
`'lg'`	`80rpx`
`'xl'`	`128rpx`
`'hero'`	`180rpx`

事件

事件名称	触发时机	回调参数	参数说明
`click`	点击头像时触发（需 `clickable` 为 `true`）	`(event)`	原生点击事件对象
`error`	图片加载失败时触发	`(src: String)`	失败的图片地址
`load`	图片加载成功时触发	`(event)`	原生 load 事件对象

事件使用示例

vue

<template>
  <xtf-avatar src="/static/avatar.png" clickable @click="onClick" @load="onLoad" @error="onError" />
</template>

<script>
export default {
  methods: {
    onClick(event) {
      console.log('点击头像', event)
    },
    onLoad(event) {
      console.log('头像加载完成', event)
    },
    onError(src) {
      console.log('头像加载失败', src)
    }
  }
}
</script>

主题说明

头像边框使用 var(--xtf-avatar-border)
回退文字字体使用 var(--xtf-font-font-family-title)，字重 var(--xtf-font-font-weight-bold)
状态指示点边框色使用 var(--xtf-avatar-status-border)
online 状态发光使用 var(--xtf-avatar-status-online-glow)
busy 状态脉冲动画使用 var(--xtf-avatar-pulse-start) / var(--xtf-avatar-pulse-end)
光环默认渐变跟随 theme 或哈希色，可通过 ringColor 覆盖
发光阴影使用 var(--xtf-shadow-card)

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-avatar ​

组件说明 ​

基础用法 ​

1. 图片头像 ​

2. 文字头像与姓名提取 ​

3. 主题色与自定义颜色 ​

4. 形状与状态指示 ​

5. 光环与发光效果 ​

全部属性 ​

预设尺寸对照 ​

事件 ​

事件使用示例 ​

主题说明 ​