跳到正文

会话模块 ​

会话列表容器,开箱即用的 IM 会话页:内置搜索、未读徽标、置顶 / 免打扰 / 删除(长按或右键)、草稿记忆与下拉刷新,数据由 SDK 自动同步驱动。

会话列表、未读徽标与空聊天区

使用方式 ​

组件以 EmConversationContainer 为名导出。容器依赖 EmUIKitProvider 提供 SDK 实例,需将两者组合使用:

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

function onSelect() {
  // 切换到聊天页,例如把 conversation.id 写入路由
}
</script>

<template>
  <EmUIKitProvider
    app-key="your-app-key"
    :auto-init="true"
    enable-presence
  >
    <div style="height: 100vh; width: 320px;">
      <em-conversation-container
        title="消息"
        unread-mode="count"
        @conversation-select="onSelect"
      />
    </div>
  </EmUIKitProvider>
</template>

会话列表在 SDK 5.x 下由 WebSocket 自动同步:登录成功后会监听 onConversationListSyncDidFinish 并自动填充列表,无需手动拉取。

会话操作 ​

PC 端右键会话项、H5 端长按会话项,即可打开内置操作菜单,执行标记已读、置顶、免打扰或删除会话:

会话置顶、免打扰与删除操作菜单

会话列表项 ​

EmConversationItem 是会话列表的基础展示单元,支持单聊 / 群聊、未读徽标、置顶、免打扰与红点模式:

API ​

ConversationContainer API ​

Props ​

属性类型默认值说明
showSearchbooleantrue是否展示搜索框,默认 true
customActionsConversationAction[]() => []自定义操作项列表,追加到会话项右键菜单/H5 长按 ActionSheet;未提供 handler 的项点击后触发 custom-action 事件
showScrollToTopbooleantrue是否展示滚动置顶按钮,默认 true
timeFormatter(timestamp: number) => string—时间格式化函数,入参为毫秒时间戳(ms),返回展示文本;不传时按当前 locale 用 toLocaleTimeString 兜底
messageFormatter(msg: string, type?: string) => string—消息摘要格式化函数,入参为原始摘要文本与消息类型(当前实现固定传入 'text'),返回展示文本;不传时原样展示
showSenderNamebooleantrue群聊会话摘要是否显示发送者名称前缀,默认 true
emptyTextstring—空列表提示文案,优先于各分栏 tab 的默认空状态文案
unreadMode'count' | 'dot''count'未读数量展示模式:count 显示数字,dot 仅显示红点,默认 'count'
badgePlacement'top-right' | 'bottom-right'—未读 Badge 位置(仅 unreadPlacement=avatar 头像角标时生效):top-right(默认)/ bottom-right
variant'card' | 'compact''card'列表风格变体:card(默认;圆角白卡、无分割线、项间距 4px)/
compact(无圆角、无分割线、零间距的平铺列表)
showAvatarbooleantrue会话项是否展示头像(false = 仅会话信息模式),默认 true
unreadPlacement'inline' | 'avatar''inline'未读徽标归位:inline 信息区行尾(默认)/ avatar 头像右上角角标
showHeaderbooleantrue是否展示头部区域,默认 true
titlestring—Header 标题文本,不传则使用 i18n 默认值
headerAlign'left' | 'center' | 'right''left'Header 内容对齐方式:left | center | right,默认 left
filterFn(keyword: string, item: Conversation) => boolean—自定义搜索过滤函数
bodyStickybooleanfalse#body slot 是否固定不随列表滚动,默认 false
footerStickybooleanfalse#footer slot 是否固定不随列表滚动,默认 false
pullRefreshbooleanfalse是否启用下拉刷新(H5)。true 强制开启;false 或未配置时回落 Provider h5.pullRefresh
(默认 'auto':触屏设备自动开启,见 core useH5Adaptation)
enablePresenceboolean—是否展示单聊头像在线状态;不传则使用 Provider 全局 enablePresence 配置
tabsConversationTabKey[]() => [...DEFAULT_CONVERSATION_TABS]会话分栏 tab 集合,默认全量 ['all', 'unread', 'atMe', 'single', 'group'];
顺序即渲染优先级;传空数组可隐藏 tab 栏。
activeTabConversationTabKey'all'当前激活的分栏 tab(v-model:active-tab)。可受控(绑定 v-model 由外部驱动)也可不受控(默认,组件内部自行维护,开箱即用)
showStatusBannerbooleantrue是否展示连接/同步状态横幅,默认 true
menuItemsConversationHeaderMenuItem[]—Header + 菜单自定义项;不传时使用内置三项(新建会话/添加联系人/创建群组);
传空数组可隐藏菜单入口。

Events ​

事件名参数说明
selectid: string, conversation: Conversation会话选中完成(已切换会话、发送已读回执、加载草稿等内部逻辑之后)时触发,负载为会话 id 与会话对象
conversation-clickid: string, conversation: Conversation点击会话项时立即触发(先于内部选中逻辑,供 H5 页面栈导航等使用),负载为会话 id 与会话对象
at-me-clickid: string, conversation: Conversation点击带未清除 @我状态的会话时触发(在 select 之后),负载为会话 id 与会话对象
custom-actionkey: string, conversation: Conversation自定义操作项未提供 handler 时向上触发,负载为操作 key 与会话对象
update:active-tabtab: ConversationTabKey切换分栏 tab 时触发(v-model:active-tab),负载为新的 tab key
reconnect—断网/连接失败横幅被点击时触发,由业务方决定重连策略
header-menu-actionkey: string自定义 Header 菜单项未提供 handler 且非内置 key 时触发,负载为菜单 key
searchkeyword: string搜索关键字变化时触发(去空格后的值,清空时为 ''),可用于埋点或远程搜索

Slots ​

插槽名说明
header—
header-menu—
tabs—
status-banner—
body—
item—
item-name-suffix—
empty—
footer—
new-chat—
add-contact—
create-group—

插槽说明 ​

  • header:自定义头部内容(替代默认标题)
  • empty:空列表状态,接收 keyword 等插槽属性
  • body:列表顶部附加内容,可通过 body-sticky 固定
  • footer:列表底部附加内容,可通过 footer-sticky 固定
  • tabs:完全接管分栏 tab 栏渲染,作用域提供 { tabs, activeTab, selectTab }(ConversationTabsSlotScope)
  • status-banner:自定义连接/同步状态横幅,作用域提供当前横幅状态({ visible, type, loading, title, description, clickable })
  • item:完全接管会话项渲染,作用域提供 { conversation, active, keyboardFocus, select, pin, mute, delete, read, customAction }(ConversationItemSlotScope);不传时默认渲染内置 EmConversationItem
  • header-menu:完全接管 Header + 菜单区域(触发按钮 + 弹出层),作用域提供 { menuItems, open, close };不传时默认渲染内置菜单
  • new-chat / add-contact / create-group:分别接管「新建会话 / 添加联系人 / 创建群组」弹窗渲染,作用域提供 { show, open, close };不传时默认渲染内置弹窗

会话项完全接管 ​

会话列表支持 #item 插槽完全接管会话项渲染(与联系人/群组列表的 #item 惯例一致),作用域提供会话数据、选中/高亮态与内置动作句柄:

vue
<template>
  <em-conversation-container>
    <template #item="{ conversation, active, keyboardFocus, select }">
      <div
        class="my-conv-item"
        :class="{ active }"
        @click="select"
      >
        <span>{{ conversation.name }}</span>
        <span v-if="conversation.unreadCount" class="badge">{{ conversation.unreadCount }}</span>
      </div>
    </template>
  </em-conversation-container>
</template>

Header 菜单定制 ​

Header + 菜单默认提供「新建会话 / 添加联系人 / 创建群组」三项,通过 menu-items prop 注入自定义项(ConversationHeaderMenuItem[]),或 #header-menu 插槽整体接管:

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

// 自定义菜单项:未提供 handler 的项点击触发 header-menu-action 事件
const menuItems: ConversationHeaderMenuItem[] = [
  { key: 'newChat', label: '新建会话', icon: 'bubble/rect/empty' },
  { key: 'joinGroup', label: '加入群组', icon: 'person/plus', handler: (key) => openMyJoinGroup() },
]
</script>

<template>
  <em-conversation-container :menu-items="menuItems" @header-menu-action="onHeaderMenuAction" />
</template>
  • 不传 menu-items:使用内置三项
  • 传空数组:隐藏菜单入口
  • 自定义项命中内置 key(newChat / addContact / createGroup)且未提供 handler 时,仍走内置弹窗
  • 传 #header-menu 插槽:整个菜单区域(触发按钮 + 弹出层)由业务方渲染,作用域提供 { menuItems, open, close }

弹窗接管 ​

接入方接自己的选人器 / 好友体系 / 企业通讯录时,可通过 #new-chat / #add-contact / #create-group 插槽分别接管三个弹窗:

vue
<template>
  <em-conversation-container>
    <!-- 接管「新建会话」弹窗:点击 + 菜单的新建会话时打开业务自己的选人器 -->
    <template #new-chat="{ show, open, close }">
      <MyPicker v-model:show="show" @confirm="onPick">…</MyPicker>
    </template>
  </em-conversation-container>
</template>

作用域提供 show(当前是否显示)、open(打开)、close(关闭)三个句柄,业务可完全控制弹窗渲染与开关。

会话分栏 ​

会话列表内置「全部 / 未读 / @我 / 单聊 / 群组」五种分栏 tab,按需展示会话。

半接管:通过 props 控制 ​

把 tabs / active-tab 绑定到组件上,tab 栏渲染走内置样式:

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

// 业务只有单聊/群聊,不区分更多类型
const { tabs, activeTab } = useConversationTabs({ tabs: ['single', 'group'] })
</script>

<template>
  <em-conversation-container v-model:active-tab="activeTab" :tabs="tabs" />
</template>
  • tabs 为空数组时隐藏 tab 栏
  • 顺序即渲染优先级,例如 ['group', 'single'] 会把群组排到前面
  • activeTab 支持 v-model:active-tab 双向绑定,可在业务侧同步切换状态

完全接管:通过 #tabs 插槽自绘 ​

传入 #tabs 插槽后,tab 栏完全由业务方渲染,作用域提供 tabs / activeTab / selectTab:

vue
<template>
  <em-conversation-container
    v-model:active-tab="activeTab"
    :tabs="tabs"
  >
    <template #tabs="{ tabs: tabList, activeTab: current, selectTab }">
      <div class="my-tabs">
        <button
          v-for="tab in tabList"
          :key="tab"
          :class="{ active: tab === current }"
          @click="selectTab(tab)"
        >
          {{ tabLabel(tab) }}
        </button>
      </div>
    </template>
  </em-conversation-container>
</template>

类型与常量 ​

  • ConversationTabKey:'all' | 'unread' | 'atMe' | 'single' | 'group'
  • DEFAULT_CONVERSATION_TABS:默认 tab 集合常量(顺序即渲染优先级)
  • ConversationTabsSlotScope:#tabs 插槽作用域类型 { tabs, activeTab, selectTab }
  • useConversationTabs(options):分栏状态 hook,返回 { tabs, activeTab, selectTab, isActive }

状态横幅 ​

断网、连接中或同步中时,搜索栏下方会展示内置状态横幅(默认开启,show-status-banner 可关闭),优先级从高到低为:被踢下线 > 断网 > 连接中 > 会话同步 > 消息同步:

  • 被踢下线:error 样式,不可点击重连——账号被踢 / 失效是账号态终态(SDK 不再自动重连),点击不会触发 reconnect 事件;文案按被踢错误码差异化(@easemob-community/uikit-sdk-contract 的 KICK_ERROR_CODE):
    • 206 多端互踢:「当前账号已在其他设备登录」
    • 214 设备超限:「登录设备数超过限制,当前设备已下线」
    • 216 修改密码:「账号密码已修改,请重新登录」
    • 其他(如 207 注销 / 217 被踢):「当前账号已被迫下线,请重新登录」
  • 断网:error 样式,可点击,点击触发 reconnect 事件,由业务方决定重连策略
  • 连接中:warning 样式 + loading 图标(曾连接过则展示「重连中」)
  • 会话/消息同步中:info 样式

需要自定义横幅时使用 #status-banner 插槽,接收当前状态(visible / type / loading / title / description / clickable)自行渲染;内置横幅基于 StatusBanner 组件 实现。

进阶 ​

  • 会话项右侧操作(置顶 / 免打扰 / 删除)通过长按(H5)或右键(PC)触发,菜单行为由组件内置。
  • 草稿功能开启后,重新进入会话会自动恢复输入框内容。
  • PC 复合消息模式在页面内保留图文/视频/文件及顺序,并在会话列表显示 [图片]文字 等有序摘要。
  • draftStorage=local/session 在刷新页面后仍只恢复文本;本地 File、编辑器快照和附件摘要不跨刷新持久化。