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

使用方式
组件以 EmConversationContainer 为名导出。容器依赖 EmUIKitProvider 提供 SDK 实例,需将两者组合使用:
<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
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| showSearch | boolean | true | 是否展示搜索框,默认 true |
| customActions | ConversationAction[] | () => [] | 自定义操作项列表,追加到会话项右键菜单/H5 长按 ActionSheet;未提供 handler 的项点击后触发 custom-action 事件 |
| showScrollToTop | boolean | true | 是否展示滚动置顶按钮,默认 true |
| timeFormatter | (timestamp: number) => string | — | 时间格式化函数,入参为毫秒时间戳(ms),返回展示文本;不传时按当前 locale 用 toLocaleTimeString 兜底 |
| messageFormatter | (msg: string, type?: string) => string | — | 消息摘要格式化函数,入参为原始摘要文本与消息类型(当前实现固定传入 'text'),返回展示文本;不传时原样展示 |
| showSenderName | boolean | true | 群聊会话摘要是否显示发送者名称前缀,默认 true |
| emptyText | string | — | 空列表提示文案,优先于各分栏 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(无圆角、无分割线、零间距的平铺列表) |
| showAvatar | boolean | true | 会话项是否展示头像(false = 仅会话信息模式),默认 true |
| unreadPlacement | 'inline' | 'avatar' | 'inline' | 未读徽标归位:inline 信息区行尾(默认)/ avatar 头像右上角角标 |
| showHeader | boolean | true | 是否展示头部区域,默认 true |
| title | string | — | Header 标题文本,不传则使用 i18n 默认值 |
| headerAlign | 'left' | 'center' | 'right' | 'left' | Header 内容对齐方式:left | center | right,默认 left |
| filterFn | (keyword: string, item: Conversation) => boolean | — | 自定义搜索过滤函数 |
| bodySticky | boolean | false | #body slot 是否固定不随列表滚动,默认 false |
| footerSticky | boolean | false | #footer slot 是否固定不随列表滚动,默认 false |
| pullRefresh | boolean | false | 是否启用下拉刷新(H5)。true 强制开启;false 或未配置时回落 Provider h5.pullRefresh (默认 'auto':触屏设备自动开启,见 core useH5Adaptation) |
| enablePresence | boolean | — | 是否展示单聊头像在线状态;不传则使用 Provider 全局 enablePresence 配置 |
| tabs | ConversationTabKey[] | () => [...DEFAULT_CONVERSATION_TABS] | 会话分栏 tab 集合,默认全量 ['all', 'unread', 'atMe', 'single', 'group']; 顺序即渲染优先级;传空数组可隐藏 tab 栏。 |
| activeTab | ConversationTabKey | 'all' | 当前激活的分栏 tab(v-model:active-tab)。可受控(绑定 v-model 由外部驱动)也可不受控(默认,组件内部自行维护,开箱即用) |
| showStatusBanner | boolean | true | 是否展示连接/同步状态横幅,默认 true |
| menuItems | ConversationHeaderMenuItem[] | — | Header + 菜单自定义项;不传时使用内置三项(新建会话/添加联系人/创建群组);传空数组可隐藏菜单入口。 |
Events
| 事件名 | 参数 | 说明 |
|---|---|---|
select | id: string, conversation: Conversation | 会话选中完成(已切换会话、发送已读回执、加载草稿等内部逻辑之后)时触发,负载为会话 id 与会话对象 |
conversation-click | id: string, conversation: Conversation | 点击会话项时立即触发(先于内部选中逻辑,供 H5 页面栈导航等使用),负载为会话 id 与会话对象 |
at-me-click | id: string, conversation: Conversation | 点击带未清除 @我状态的会话时触发(在 select 之后),负载为会话 id 与会话对象 |
custom-action | key: string, conversation: Conversation | 自定义操作项未提供 handler 时向上触发,负载为操作 key 与会话对象 |
update:active-tab | tab: ConversationTabKey | 切换分栏 tab 时触发(v-model:active-tab),负载为新的 tab key |
reconnect | — | 断网/连接失败横幅被点击时触发,由业务方决定重连策略 |
header-menu-action | key: string | 自定义 Header 菜单项未提供 handler 且非内置 key 时触发,负载为菜单 key |
search | keyword: 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);不传时默认渲染内置EmConversationItemheader-menu:完全接管 Header+菜单区域(触发按钮 + 弹出层),作用域提供{ menuItems, open, close };不传时默认渲染内置菜单new-chat/add-contact/create-group:分别接管「新建会话 / 添加联系人 / 创建群组」弹窗渲染,作用域提供{ show, open, close };不传时默认渲染内置弹窗
会话项完全接管
会话列表支持 #item 插槽完全接管会话项渲染(与联系人/群组列表的 #item 惯例一致),作用域提供会话数据、选中/高亮态与内置动作句柄:
<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 插槽整体接管:
<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 插槽分别接管三个弹窗:
<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 栏渲染走内置样式:
<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:
<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、编辑器快照和附件摘要不跨刷新持久化。
