跳到正文

群组模块 ​

群组列表容器,开箱即用的「我的群组」列表页:内置搜索、排序 / 分组、字母导航、成员数展示、选择模式(单选 / 多选)与触底加载,点击行为可完全交给外部接管。

使用方式 ​

组件以 EmGroupListContainer 为名导出。需在 EmUIKitProvider 内使用:

vue
<script setup lang="ts">
import { EmUIKitProvider } from '@easemob-community/uikit-im'

function onGroupClick() {
  // 跳转群详情或进入群聊
}
</script>

<template>
  <EmUIKitProvider
    app-key="your-app-key"
    :auto-init="true"
  >
    <div style="height: 100vh; width: 360px;">
      <em-group-list-container
        title="我的群组"
        group-by="alphabet"
        @click="onGroupClick"
      />
    </div>
  </EmUIKitProvider>
</template>

Provider 需开启群组能力(enable-group,默认开启)才会自动拉取已加入群组;group-by="alphabet" 可开启按拼音首字母分组。

群组列表项 ​

EmGroupItem 是群组列表的基础展示单元,支持成员数、副标题、头像形状与选择模式:

API ​

GroupContainer API ​

Props ​

属性类型默认值说明
showHeaderbooleantrue是否展示头部区域,默认 true
titlestring—Header 标题文本,不传则使用 i18n 默认值
headerAlign'left' | 'center' | 'right''left'Header 内容对齐方式:left | center | right,默认 left
showCountbooleanfalse是否在标题旁展示数量徽标 (n),默认 false
showSearchbooleantrue是否展示搜索框,默认 true
showScrollToTopbooleantrue是否展示滚动置顶按钮,默认 true
emptyTextstring—空列表提示文字
filterFnGroupFilterFn—自定义搜索过滤函数
sortByGroupSortBy'none'排序方式,默认 'none'(保持 store 顺序)
groupByGroupGroupBy'none'分组方式,默认 'none'(平铺)
showGroupHeaderbooleantrue是否展示分组标题,默认 true(仅 groupBy !== 'none' 时)
showAlphabetNavbooleantrue是否展示字母导航,默认 true(仅 groupBy === 'alphabet' 时)
selectModeGroupSelectMode'none'选择模式
selectedIdsstring[]—已选中 id 列表(受控,配合 update:selectedIds 实现 v-model)
maxSelectednumber—最大可选数量(multiple 模式生效)
disabledFnGroupDisabledFn—disabled 判定
subtitleFnGroupSubtitleFn—副标题提取函数
showAvatarbooleantrue是否展示群头像,默认 true
showMemberCountbooleantrue是否展示成员数,默认 true
avatarSizenumber—头像尺寸(px),覆盖 itemSize 推断
avatarShapeAvatarShapeundefined头像形状,默认 rounded
itemSizeGroupItemSize'normal'Item 紧凑度,默认 'normal'
loadingbooleanfalse是否处于加载态
hasMorebooleantrue是否还有更多数据可加载,默认 true
loadMoreThresholdnumber60触底距离阈值(px),默认 60
enableLoadMorebooleantrue启用触底加载
noMoreTextstring—自定义"没有更多"提示文案
bodyStickybooleanfalse#body slot 是否固定不随列表滚动
footerStickybooleanfalse#footer slot 是否固定不随列表滚动
searchComponentComponent—自定义搜索组件(完全接管搜索逻辑与UI),传入后 showSearch 失效
clickBehaviorGroupListClickBehavior'default'列表项点击行为模式,默认 'default'

Events ​

事件名参数说明
selectgroup: Group列表项被选中时触发(clickBehavior 为 'event-only' 时不触发),负载为群组对象
clickgroup: Group点击列表项时触发(不受 clickBehavior 影响,始终发出),负载为群组对象
contextmenuevent: MouseEvent, group: Group右键点击列表项时触发,负载为原生右键事件 MouseEvent 与群组对象
group-jumpkey: string通过字母导航跳转到分组后触发,负载为分组 key
update:selectedIdsids: string[]选中集合变化时触发(配合 selectedIds 实现 v-model:selectedIds),负载为新的 id 数组
max-exceedmax: number选中数量超过 maxSelected 上限时触发(内部回退到上次合法选中),负载为上限值
load-more—滚动接近底部且满足加载条件时触发;外部加载完成后需调用 expose 的 releaseLoadMoreLock 释放锁
searchkeyword: string搜索关键词变化时触发,负载为去除首尾空格后的关键词

Slots ​

插槽名说明
header—
search—
body—
loading—
empty—
group-header—
item—
loading-more—
no-more—
footer—
watermark—

插槽说明 ​

  • header:自定义头部内容
  • body / footer:列表顶部 / 底部附加内容
  • loading / loading-more / no-more:加载中 / 加载更多 / 没有更多状态
  • empty:空列表状态
  • group-header:分组标题自定义
  • item:群组列表项自定义
  • search:搜索框区域自定义

实例方法 ​

  • scrollToGroup(key):滚动到指定分组

相关链接 ​

  • 群管理:群管理入口、禁言 / 黑白名单 / 共享文件 / 入群申请、群公告、群成员列表与群详情卡片