xtf-avatar-group

组件说明

xtf-avatar-group 是头像组组件，用于以堆叠、展开或波浪布局展示多个头像。支持最大显示数量限制与溢出计数、自定义溢出样式、点击交互和插槽定制，适用于团队列表、参与者展示和评论区等场景。

基础用法

1. 最简示例

通过 items 传入头像数据数组，默认以堆叠布局展示：

vue

<template>
  <xtf-avatar-group :items="items" />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { name: '张三' },
        { name: '李四' },
        { name: '王五' },
        { name: '赵六' },
        { name: '钱七' },
        { name: '孙八' }
      ]
    }
  }
}
</script>

2. 最大数量与溢出计数

通过 max 限制最大显示数量，超出部分自动显示 +N 溢出计数：

vue

<template>
  <xtf-avatar-group :items="items" :max="3" @more-click="onMoreClick" />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { name: '张三' },
        { name: '李四' },
        { name: '王五' },
        { name: '赵六' },
        { name: '钱七' },
        { name: '孙八' }
      ]
    }
  },
  methods: {
    onMoreClick({ restCount, hiddenItems }) {
      uni.showToast({ title: '还有 ' + restCount + ' 人', icon: 'none' })
    }
  }
}
</script>

3. 布局变体

通过 layout 切换三种布局：'stack'（堆叠）、'spread'（展开）、'wave'（波浪）：

vue

<template>
  <view>
    <xtf-text level="caption" color="secondary">堆叠</xtf-text>
    <xtf-avatar-group :items="items" layout="stack" size="md" />

    <xtf-text level="caption" color="secondary" style="margin-top: 24rpx">展开</xtf-text>
    <xtf-avatar-group :items="items" layout="spread" size="md" />

    <xtf-text level="caption" color="secondary" style="margin-top: 24rpx">波浪</xtf-text>
    <xtf-avatar-group :items="items" layout="wave" size="md" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      items: [
        { name: '张三' },
        { name: '李四' },
        { name: '王五' },
        { name: '赵六' },
        { name: '钱七' }
      ]
    }
  }
}
</script>

4. 溢出样式定制

通过 moreType / moreVariant / moreTheme / moreShape 定制溢出项的视觉风格：

vue

<template>
  <view>
    <xtf-text level="caption" color="secondary">文字溢出（默认）</xtf-text>
    <xtf-avatar-group :items="items" :max="3" more-type="text" more-variant="solid" />

    <xtf-text level="caption" color="secondary" style="margin-top: 24rpx">柔和溢出</xtf-text>
    <xtf-avatar-group :items="items" :max="3" more-type="text" more-variant="soft" />

    <xtf-text level="caption" color="secondary" style="margin-top: 24rpx">头像溢出</xtf-text>
    <xtf-avatar-group :items="items" :max="3" more-type="avatar" more-theme="secondary" />

    <xtf-text level="caption" color="secondary" style="margin-top: 24rpx">玻璃溢出</xtf-text>
    <xtf-avatar-group :items="items" :max="3" more-type="text" more-variant="glass" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      items: [
        { name: '张三' },
        { name: '李四' },
        { name: '王五' },
        { name: '赵六' },
        { name: '钱七' },
        { name: '孙八' }
      ]
    }
  }
}
</script>

5. 光环与交互

通过 ring 为所有头像添加光环，通过 clickable 启用点击交互，通过 overlap 调整堆叠重叠量：

vue

<template>
  <xtf-avatar-group
    :items="items"
    :max="4"
    size="lg"
    ring
    clickable
    :overlap="20"
    @item-click="onItemClick"
    @more-click="onMoreClick"
  />
</template>

<script>
export default {
  data() {
    return {
      items: [
        { name: '张三', status: 'online' },
        { name: '李四', status: 'busy' },
        { name: '王五' },
        { name: '赵六', status: 'away' },
        { name: '钱七' },
        { name: '孙八' }
      ]
    }
  },
  methods: {
    onItemClick({ item, index }) {
      uni.showToast({ title: '点击了: ' + item.name, icon: 'none' })
    },
    onMoreClick({ restCount }) {
      uni.showToast({ title: '还有 ' + restCount + ' 人', icon: 'none' })
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`items`	`Array`	`[]`	头像数据数组，每项字段见下方子表	核心数据源
`size`	`String \| Number`	`'md'`	头像尺寸，支持预设 `'xs'` / `'sm'` / `'md'` / `'lg'` / `'xl'` / `'hero'` 或数值（rpx）	控制头像大小
`shape`	`String`	`'circle'`	头像形状：`'circle'` / `'rounded'` / `'rect'` / `'hexagon'` / `'squircle'`	统一设置形状
`theme`	`String`	`''`	预设主题色，传递给内部 `xtf-avatar`	统一设置主题色
`ring`	`Boolean`	`false`	是否为所有头像显示光环	突出显示头像
`ringColor`	`String`	`''`	自定义光环颜色	自定义光环色
`max`	`String \| Number`	`5`	最大显示数量，超出显示溢出计数	控制显示数量
`overlap`	`String \| Number`	`14`	堆叠重叠量（rpx），数值越大重叠越多	调整堆叠间距
`layout`	`String`	`'stack'`	布局方式：`'stack'` 堆叠 / `'spread'` 展开 / `'wave'` 波浪	适配不同展示风格
`align`	`String`	`'start'`	对齐方式：`'start'` / `'center'` / `'end'`	控制水平对齐
`reverse`	`Boolean`	`false`	是否反转排列顺序	从右到左展示
`wrap`	`Boolean`	`false`	是否换行展示	头像数量较多时
`morePosition`	`String`	`'end'`	溢出项位置：`'end'` 末尾 / `'start'` 开头	控制溢出位置
`clickable`	`Boolean`	`false`	是否可点击，启用后头像有上浮反馈	头像可交互场景
`hoverable`	`Boolean`	`true`	是否有悬浮交互效果	关闭悬浮动效
`fallbackIcon`	`String`	`'person'`	回退图标名，传递给内部 `xtf-avatar`	自定义回退图标
`moreText`	`String`	`''`	自定义溢出文案，默认为 `+N`	自定义溢出文案
`moreType`	`String`	`'text'`	溢出项类型：`'text'` 文字 / `'avatar'` 头像样式	溢出展示方式
`moreShape`	`String`	`'circle'`	溢出头像形状，`moreType='avatar'` 时生效	溢出头像形状
`moreTheme`	`String`	`'inverse'`	溢出头像主题色，`moreType='avatar'` 时生效	溢出头像颜色
`moreVariant`	`String`	`'solid'`	溢出文字样式：`'solid'` 实心 / `'soft'` 柔和 / `'glass'` 玻璃 / `'outline'` 描边	溢出视觉风格
`moreRing`	`Boolean`	`false`	溢出头像是否显示光环	溢出头像光环
`moreRingColor`	`String`	`''`	溢出头像自定义光环颜色	溢出光环色
`moreClickable`	`Boolean`	`true`	溢出项是否可点击	关闭溢出点击
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object \| Array`	`''`	自定义样式	动态样式覆盖

`items` 数组每项支持的字段

字段	类型	默认值	说明
`src`	`String`	`''`	头像图片地址
`name`	`String`	`''`	用户名，用于提取首字母和哈希渐变色
`text`	`String`	`''`	自定义回退文字
`shape`	`String`	继承组 `shape`	单项形状，可覆盖组的统一设置
`size`	`String \| Number`	继承组 `size`	单项尺寸，可覆盖组的统一设置
`theme`	`String`	继承组 `theme`	单项主题色，可覆盖组的统一设置
`status`	`String`	`''`	状态指示点：`'online'` / `'busy'` / `'away'` / `'offline'`
`ring`	`Boolean`	继承组 `ring`	单项是否显示光环
`ringColor`	`String`	继承组 `ringColor`	单项自定义光环颜色
`glow`	`Boolean`	`false`	单项是否发光
`clickable`	`Boolean`	继承组 `clickable`	单项是否可点击
`fallbackIcon`	`String`	继承组 `fallbackIcon`	单项回退图标
`id` / `key`	`String`	—	唯一标识，用于列表渲染的 key

事件

事件名称	触发时机	回调参数	参数说明
`item-click`	点击头像项时触发（需 `clickable` 为 `true`）	`(payload: { item: Object, index: Number, event })`	`item` 为点击项数据，`index` 为原始索引，`event` 为原生事件
`more-click`	点击溢出项时触发（需 `moreClickable` 为 `true`）	`(payload: { restCount: Number, items: Array, hiddenItems: Array, event })`	`restCount` 为溢出数量，`hiddenItems` 为隐藏项数组

事件使用示例

vue

<template>
  <xtf-avatar-group
    :items="members"
    :max="2"
    clickable
    @item-click="onItemClick"
    @more-click="onMoreClick"
  />
</template>

<script>
export default {
  data() {
    return { members: [{ name: '张三' }, { name: '李四' }, { name: '王五' }] }
  },
  methods: {
    onItemClick({ item, index }) {
      console.log('点击成员', item, index)
    },
    onMoreClick({ restCount, hiddenItems }) {
      console.log('其余成员', restCount, hiddenItems)
    }
  }
}
</script>

插槽

插槽名	作用域参数	说明
`item`	`{ item, index }`	替换单个头像。
`more`	`{ restCount, items, label }`	替换溢出项。

vue

<template>
  <xtf-avatar-group :items="members" :max="2">
    <template #more="{ label }"><xtf-badge standalone :text="label" theme="info" /></template>
  </xtf-avatar-group>
</template>

<script>
export default {
  data() {
    return { members: [{ name: '张三' }, { name: '李四' }, { name: '王五' }] }
  }
}
</script>

主题说明

溢出文字背景使用 var(--xtf-avatar-more-bg)，文字色使用 var(--xtf-avatar-more-text)
溢出边框色使用 var(--xtf-avatar-border)
soft 变体背景使用 var(--xtf-color-surface-muted)，文字色使用 var(--xtf-color-text-secondary)
glass 变体背景使用 var(--xtf-color-glass)，边框色使用 var(--xtf-card-border)
outline 变体背景透明，文字色使用 var(--xtf-color-text)
头像阴影使用 var(--xtf-shadow-soft)
交互悬浮使用 var(--xtf-motion-base) + var(--xtf-motion-spring) 动画

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

xtf-avatar-group ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 最大数量与溢出计数 ​

3. 布局变体 ​

4. 溢出样式定制 ​

5. 光环与交互 ​

全部属性 ​

items 数组每项支持的字段 ​

事件 ​

事件使用示例 ​

插槽 ​

主题说明 ​