跳到正文

消息列表 MessageList ​

消息列表组件,聊天模块的消息渲染区:虚拟滚动列表、各类型消息气泡(文本 / 图片 / 语音 / 视频 / 文件 / 位置 / 合并)、时间戳与头像控制、消息发送状态(经典 / 数字胶囊)与多选模式。数据由 useChat() 从消息 store 读取,配置通过 config.messageList 传入。

使用方式 ​

组件以 EmMessageList 为名导出。需在 EmUIKitProvider 内使用(useChat() 依赖 Provider 上下文):

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

<template>
  <EmUIKitProvider app-key="your-app-key" :auto-init="true">
    <div style="height: 600px; border: 1px solid #e5e7eb; border-radius: 8px;">
      <EmMessageList
        :config="{
          messageList: {
            showAvatar: true,
            showTime: 'hover',
            bubbleShape: 'round',
          },
        }"
      />
    </div>
  </EmUIKitProvider>
</template>

通常不需要单独使用 EmMessageList —— 聊天模块 的 EmChatContainer 已经内置了消息列表、输入区与消息操作。单独使用 EmMessageList 适用于深度定制聊天页布局(如自定义输入区)的场景。

单条气泡能力演练场 ​

下面针对单条消息气泡 EmMessageBubbleWrapper 演示多选态 / 引用卡片 / 状态组合 / 群已读圆圈四类能力(演示数据为 mock,不依赖登录态):

配置项速览 ​

config.messageList 常用视觉配置:

  • layout:'conversation' | 'left',默认 'conversation' —— 对话式左右分列 / 全部靠左对齐
  • showAvatar:boolean,默认 true —— 是否显示发送者头像(自己与对方的统一开关)
  • showSelfAvatar:boolean,默认 true —— 是否显示「自己」的头像;仅 showAvatar 开启时生效,设为 false 可隐藏自己的头像而对方照常显示(微信/QQ 式「隐藏我的头像」)
  • showTime:boolean | 'always' | 'hover',默认 false —— 时间戳显示策略
  • bubbleShape:'round' | 'square',默认 'round' —— 气泡圆角档位(16px / 8px)
  • bubbleStyle:'filled' | 'plain',默认 'filled' —— 中性气泡(对方)带底色 / 无底色纯文字
  • voiceUnreadDot:boolean,默认 true —— 对方语音消息未播放红点(仅本会话实时收到的语音显示,点击播放后消失;历史/漫游消息与刷新后不显示)
  • avatarSize:number,默认 36 —— 头像尺寸(px)
  • presence:boolean,默认 false —— 消息头像在线状态点(微信/QQ 式消息流默认不带状态点;开启后仅对方头像展示,且需 Provider 全局 enablePresence 链路可用)
  • messageGap:number,默认 12 —— 消息间距(px)
  • messagePadding:number,默认 16 —— 列表内边距(px)
  • messageStatus:MessageStatusConfig —— 状态风格 / 排列 / 位置 / 文本

完整配置(含历史加载、置顶条、搜索、@我定位等)见 聊天模块 的 ChatConfig API 表格。

时间戳策略建议 ​

showTime 控制时间戳展示,推荐按场景选择:

策略配置适用场景
始终显示showTime: 'always'客服、审计等对时间敏感的场景
悬停显示showTime: 'hover'桌面端常规聊天,减少界面噪音
不显示showTime: false极简模式或业务侧自行渲染时间轴

内部默认规则(当 showTime 开启时):

  • 同一天内,相邻消息间隔 ≥ 5 分钟显示一次时间戳。
  • 跨天、跨会话首条消息强制显示时间戳。
  • 时间戳格式跟随 locale(中文「14:32」、英文「2:32 PM」等)。

业务侧若需要更细粒度控制(如间隔 3 分钟、显示完整日期),可通过 #message-time 插槽或 messageTimeFormatter 自定义。

API ​

MessageList API ​

Props ​

属性类型默认值说明
configChatConfig—消息列表配置(仅消费 config.messageList 子树:布局 / 头像 / 时间戳 / 气泡形状 / 消息状态等)

config ​

聊天页面全局配置

属性类型默认值说明
enableDraftboolean—是否启用草稿功能(切换会话时自动保存/恢复输入内容),默认 true;PC 复合模式在页面内保留图文/视频/文件快照 / Whether drafts are saved and restored on conversation switch; PC multi-body drafts retain attachments for the page lifetime
hooksChatSendHooks—消息发送拦截钩子
headerHeader 配置—Header 配置
drawer抽屉配置 / Drawer configuration—抽屉配置 / Drawer configuration
messageList消息列表配置—消息列表配置
messageAction消息操作配置—消息操作配置
groupReadReceipt群已读回执配置—群已读回执配置
groupMember群成员列表配置—群成员列表配置
groupManagement群管理功能配置—群管理功能配置
input输入框配置—输入框配置
lastMessageTextResolverLastMessageTextResolver—会话列表最新一条消息文案解析器;custom 消息等场景可由业务自定义预览内容
textMessage文本消息配置—文本消息配置

config.hooks ​

消息发送拦截钩子

属性类型默认值说明
beforeSend(message: Partial<UiMessage>) => boolean | Promise<boolean>—发送前拦截,返回 false 则阻止发送
afterSend(message: UiMessage) => void—发送成功后的回调

config.header ​

Header 配置

属性类型默认值说明
visibleboolean—是否显示 header,默认 true
alignHeaderAlign—标题对齐方式,默认 'center';对单聊/群聊同时生效
showAvatarboolean—是否显示头像,默认 false
showMemberCountboolean—是否显示群成员数后缀,默认 true;仅群聊生效
showDrawerEntryboolean—是否显示抽屉入口按钮(聊天信息),默认 true
clickOpenDrawerboolean—点击 header(标题/副标题区域)是否展开会话详情抽屉,默认 true;
头像(名片弹窗)与右侧按钮(搜索/抽屉入口)的点击不受影响。
Whether clicking the header (title/subtitle area) opens the conversation-details
drawer. Default true. Avatar (profile card) and action buttons are not affected.
showSearchEntryboolean—是否显示 header 搜索消息按钮,默认 false(搜索入口归口会话详情抽屉的 Message Search 行;
仅在 messageList.search.enabled 为 true 时生效,开启后 header 恢复显示搜索按钮)。
Whether to show the message-search button in the header. Default false — the search entry
lives in the conversation-details drawer; takes effect only when message search is enabled.
subtitle'auto' | 'presence' | 'sign' | 'none'—单聊副标题档位(标题下方区域),默认 'auto';仅单聊生效:
auto(在线状态 + 个性签名,缺哪个显示哪个)/ presence(仅在线状态)/ sign(仅签名)/
none(整个副标题区连同「正在输入」提示一起关闭)。
对方正在输入时优先占据此区域;可被 #header-subtitle 插槽整体接管。
Subtitle level under the title for single chats. Default 'auto'.

config.drawer ​

抽屉配置 / Drawer configuration

属性类型默认值说明
mode'overlay' | 'push'—展示模式,默认 'push':'push' 占位挤压聊天区,抽屉以独立平面区域参与布局
(圆角跟随 --uikit-components-radius);'overlay' 完全遮挡聊天区。
移动端(viewport < 768)两种模式一律回落为满铺全屏(独立页面观感)。
Display mode. Default 'push' (takes layout space and squeezes the chat area as an
independent flat region); 'overlay' covers the chat area. On mobile (<768px) both fall back to fullscreen.
widthnumber—抽屉宽度(px),默认 320;push 与 overlay 模式均生效,全屏模式忽略 / Drawer width in px. Default 320; ignored in fullscreen
closeOnClickOutsideboolean—是否点击抽屉外部(聊天区 / 其他空白处)自动关闭,默认 true;仅 push 模式生效
(overlay 模式由遮罩点击关闭,语义归口 closeOnClickOverlay),全屏模式忽略。
Whether clicking outside the drawer (chat area / blank areas) closes it. Default true;
only applies in 'push' mode (overlay mode closes via the mask click), ignored in fullscreen.
avatarClickViewProfileboolean—抽屉预览区点击头像是否打开用户名片(单聊对方头像 / 群聊成员宫格头像),默认 true;
关闭后群聊宫格头像点击回落为「查看全部成员」。
Whether clicking an avatar in the drawer preview area (peer avatar in single chats,
member grid avatars in group chats) opens the user profile card. Default true;
when false, group grid avatar clicks fall back to "view all members".

config.messageList ​

消息列表配置

属性类型默认值说明
layoutMessageLayout—消息布局模式,默认 'conversation'
showAvatarboolean—是否显示头像(自己与对方的统一开关),默认 true
showSelfAvatarboolean—是否显示「自己」的头像,默认 true;仅在 showAvatar 为 true 时生效。
设为 false 可隐藏自己的头像而对方头像照常显示(微信/QQ 式「隐藏我的头像」)。
showTimeTimeDisplayStrategy—时间显示策略,默认 false(不显示),可设置为 true / 'always' / 'hover'
bubbleShapeBubbleShape—气泡形状(圆角档位:'round' = 16px / 'square' = 8px),默认 'round' / Bubble corner preset, default 'round' (16px); 'square' is 8px
bubbleStyle'filled' | 'plain'—中性气泡(对方)样式:'filled' 带底色(默认)/ 'plain' 无底色纯文字。
Neutral bubble (peer side) style: 'filled' with background (default) or 'plain' text-only without background.
voiceUnreadDotboolean—对方语音消息未播放红点:默认 true(本会话实时收到的语音未点击时,气泡外侧垂直居中显示红点,点击后隐藏;
历史/漫游消息无播放状态,永不显示,刷新页面即复位)。
单条消息级覆盖:在消息项插槽(如 #message-voice)内对 INJECTION_KEY.VOICE_UNREAD_DOT 深一层 provide。
Whether to show an unread red dot on peer voice messages (default true; runtime-only, resets on refresh).
Per-message override: provide INJECTION_KEY.VOICE_UNREAD_DOT one level deeper inside item slots.
avatarSizenumber—头像尺寸(px),默认 36
presenceboolean—消息头像在线状态点:默认 false(不展示;微信/QQ 式消息流头像不带状态点)。
开启后仅对方头像展示状态点,且需 Provider 全局 enablePresence 链路可用。
Whether to show presence dots on message avatars. Default false; only peer
avatars show the dot, gated by the global enablePresence feature.
avatarClickViewProfileboolean—左键点击消息头像是否打开用户名片,默认 true;右键菜单(查看资料/@提及)不受此开关影响
messageGapnumber—消息项之间的间距(px),默认 12
messagePaddingnumber—消息列表内边距(px),默认 16
groupIntervalnumber—时间分组间隔(毫秒),默认 5 分钟
virtualScrollThresholdnumber—虚拟滚动阈值,超过该消息数启用虚拟滚动,默认 100
loadHistory加载历史消息配置—加载历史消息配置
maxMessageCountnumber—单个会话最大消息存储数,超出时从旧消息开始裁剪,默认 300
pinnedBar置顶横幅配置—置顶横幅配置
groupAnnouncementBar群公告横幅配置 / Group announcement banner configuration—群公告横幅配置 / Group announcement banner configuration
search消息搜索配置(居中 Modal 形态,支持关键词高亮与消息类型筛选)—消息搜索配置(居中 Modal 形态,支持关键词高亮与消息类型筛选)
autoLocateAtMeboolean—切换会话时是否自动定位到首条@我的消息,默认 true
messageStatusMessageStatusConfig—消息发送状态展示配置
quote引用展示配置—引用展示配置

config.messageList.loadHistory ​

加载历史消息配置

属性类型默认值说明
enableboolean—是否启用历史消息加载,默认 true
modeLoadHistoryMode—加载模式,默认 'auto'(自动适配端型)

config.messageList.pinnedBar ​

置顶横幅配置

属性类型默认值说明
visibleboolean—是否显示顶部置顶条,默认 true
maxPreviewLengthnumber—预览文本最大长度,默认 30

config.messageList.groupAnnouncementBar ​

群公告横幅配置 / Group announcement banner configuration

属性类型默认值说明
visibleboolean—是否显示聊天页顶部群公告横幅,默认 true;不影响抽屉中的群公告 / Whether to show the announcement banner at the top of the chat page. Default true; does not affect the drawer announcement

消息搜索配置(居中 Modal 形态,支持关键词高亮与消息类型筛选)

属性类型默认值说明
enabledboolean—是否启用消息搜索入口,默认 false
enableServerSearchboolean—是否启用 SDK 服务端消息搜索(websdk2 searchMessages),默认 false(仅搜索本地已加载消息);开启后出现「当前会话/全部会话」作用域切换
pageSizenumber—每页条数,默认 20

config.messageList.messageStatus ​

消息状态展示配置

属性类型默认值说明
showTextboolean—是否显示状态文本,默认 false(仅展示 icon)
textMapPartial<Record<MessageStatusValue, string>>—状态文本映射,未指定时从 locale 读取默认文案
iconMapPartial<Record<MessageStatusValue, string>>—状态图标映射,未指定时使用默认图标
direction'horizontal' | 'vertical'—文本与图标的排列方向,默认 'horizontal'
position'below' | 'inline'—状态相对消息气泡的位置,默认 'inline'(气泡末尾、与气泡底部对齐);'below' 为气泡下方 / Position relative to the bubble, default 'inline' (at bubble end, bottom-aligned)
styleMessageStatusStyle—消息状态图标风格。
- classic(默认):沿用 check / doneAll 经典双勾映射;
- capsule:数字胶囊风格,未读=空心圆/实心圆点,已读=圆+对勾。
readIconDisplay'latest' | 'all'—单聊己方「已读」状态图标的展示策略,默认 'latest';仅单聊生效。
- latest:连续已读只在最新一条已读消息上展示已读 icon(仿抖音移动端);
- all:每条已读消息都展示已读 icon。
Display strategy for the read icon on self messages in single chats. Default 'latest'.

config.messageList.quote ​

引用展示配置

属性类型默认值说明
showAvatarboolean—引用卡片是否展示原消息发送人头像,默认 false。
Whether the quote card shows the original sender's avatar. Default false.

config.messageAction ​

消息操作配置

属性类型默认值说明
enableQuoteboolean—启用引用,默认 true
enableCopyboolean—启用复制,默认 true(文本消息与含文本段的复合消息生效)
enableDownloadboolean—启用下载,默认 true(仅文件消息生效)
enableDeleteboolean—启用删除,默认 true
enableRecallboolean—启用撤回,默认 true
enableRecallOtherboolean—启用撤回他人消息,默认 true(仅群主/管理员在群聊中生效)
enableEditboolean—启用编辑,默认 true(仅 isSelf 且文本消息生效)
enableForwardboolean—启用转发,默认 true
enableMultiSelectboolean—启用多选,默认 true
enableTranslateboolean—启用翻译,默认 true(仅文本消息生效)
enableVoiceToTextboolean—启用语音转文字,默认 true(仅带 url 的语音消息生效)
enablePinboolean—启用置顶/取消置顶,默认 true
recallDisableDurationnumber—撤回禁用时长(毫秒),超过该时长后无法撤回,默认 2 分钟(120000)
translateTargetLangstring—翻译目标语言,例如 'zh-Hans'、'en'。不设置时根据 UIKIT 当前 locale 自动选择(zh-CN→zh-Hans,en→en,其他默认 en)
gridActionTypesMessageActionType[]—H5 长按操作面板(ActionSheet)的高频操作集合:命中的操作类型收拢到顶部图标网格区,
其余保持整行列表;默认 ['quote', 'copy', 'forward', 'download']。传 [] 关闭网格分区。

config.groupReadReceipt ​

群已读回执配置

属性类型默认值说明
enabledboolean—是否启用群已读回执,默认 false
maxGroupSizenumber—群人数上限,默认 200(超过此人数不发已读回执)

config.groupMember ​

群成员列表配置

属性类型默认值说明
allowChat'all' | 'contact' | 'none'—是否允许对成员发起单聊,默认 'all'

config.groupManagement ​

群管理功能配置

属性类型默认值说明
displayMode'drawer' | 'modal'—二级页面展示方式:drawer(抽屉)或 modal(居中弹窗),默认 drawer
showMuteAllboolean—是否展示全员禁言开关,默认 true
showMuteListboolean—是否展示禁言列表入口,默认 true
showBlocklistboolean—是否展示黑名单入口,默认 true
showAllowlistboolean—是否展示白名单入口,默认 true
showSharedFilesboolean—是否展示共享文件入口,默认 true
showJoinRequestsboolean—是否展示入群申请入口,默认 true

config.input ​

输入框配置

属性类型默认值说明
modeInputMode—输入框模式,默认 'simple'
styleInputStyle—输入框工具栏位置,默认 'toolbar-top'(工具栏在上、输入框在下);'toolbar-bottom' 为工具栏在下、输入框在上
features功能开关—功能开关
autoFocusboolean—是否自动聚焦输入框,默认 false
focusBorderColorstring—聚焦边框色。默认保持容器边框色(聚焦高亮由主色 20% 外环 --uikit-input-focus-ring 承担);显式传入时聚焦态边框改用该色
caretColorstring—光标颜色,不设置则跟随主题色(--uikit-primary) / Caret color, defaults to the theme primary color
selectionColorstring—文本选中背景色,不设置则使用主题选中色(--uikit-selection-bg,跟随主题色)
maxLengthnumber—最大输入长度,0 或不设置表示无限制
mention提及配置(@)—提及配置(@)
enableTypingboolean—是否启用输入状态提示(对方正在输入...),默认 true
showSendButtonboolean—是否显示发送按钮。显式 true/false 优先;未配置(undefined)时按端型取默认:
PC 隐藏(回车发送,对齐桌面 IM 形态),移动端显示(触屏无回车键)。
Whether to show the send button. Explicit true/false wins; when unset,
defaults by device type — hidden on PC (Enter to send), shown on mobile.
resizableboolean—是否允许拖拽调整输入区高度(仅 PC,手柄在输入卡片上缘;simple 模式默认高 132px),默认 true / Whether the input area height can be resized by dragging (PC only), default true
expandableboolean—是否显示「展开输入框」角标(仅 PC,卡片右上角;点击后输入区升至 212px,再次点击或 Esc 恢复默认;拖拽超过 212px 时角标自动呈现恢复态),默认 true / Whether to show the expand-input corner toggle (PC only), default true
pasteImagePreviewboolean—PC simple 粘贴图片预览,默认 true;非复合模式弹确认窗,复合模式加入文字下方待发送区;false 禁止粘贴图片但不影响主动选图 / PC simple pasted-image preview, default true; uses a modal in normal mode or the attachment tray in multi-body mode; false disables pasted images but not image picking
stickerPacksEmojiStickerPack[]—表情包(sticker/GIF)配置,默认 [] 不展示表情包 tab;以图片消息发送并打 ext.isSticker 标记,按表情渲染、不启用图片预览 / Sticker packs shown as extra tabs in the emoji picker
stickerExtStickerExtResolver—追加业务 sticker ext;UIKit 不约定业务编码或文案 / Append business-specific sticker ext without defining codes or labels
emojiEmoji 面板配置 / Emoji picker config—Emoji 面板配置 / Emoji picker config

config.input.features ​

功能开关

属性类型默认值说明
emojiboolean—Emoji,默认 true
imageboolean—图片,默认 true
fileboolean—文件,默认 true
voiceboolean—语音,默认 true
videoboolean—视频,默认 true
multiBodyboolean—PC simple/rich 整框复合消息(multi_body)模式,默认 false;还需 adapter 上报 multiBodyMessage 能力,H5 不提供复合编辑入口 / PC simple/rich integrated multi-body mode, default false; also requires adapter capability; H5 has no composite editor
translationboolean—翻译入口,默认 false;仅渲染按钮,点击经 translation-click 事件交由宿主接入 / Translation entry, default false; only renders the button, click is surfaced via the translation-click event for the host to handle
contactCardboolean—名片发送入口,默认 false;仅渲染按钮,点击经 contact-card-click 事件交由宿主接入 / Contact card entry, default false; only renders the button, click is surfaced via the contact-card-click event for the host to handle
mentionboolean—提及功能(@),默认 true

config.input.mention ​

提及配置(@)

属性类型默认值说明
contactsMentionContact[]—联系人列表(也可从外部通过 chat-container 灌入)
onlyInGroupboolean—是否仅在群聊中启用,默认 true

config.input.emoji ​

Emoji 面板配置 / Emoji picker config

属性类型默认值说明
recentboolean—是否启用「常用」最近使用区(置于表情视图顶部),默认 true;关闭后不展示常用区也不再记录 / Whether to enable the recent-emoji section at the top of the emoji view, default true
recentCountnumber—常用列表长度(保留最近使用个数),默认 5 / Number of recently-used emojis kept, default 5
tabsPositionEmojiTabsPosition—tab 位置:顶部/底部/左侧/右侧,默认 'bottom' / Tabs position: top/bottom/left/right, default 'bottom'
stickerHoverboolean—sticker 悬停时切换展示 gif(需提供 thumbUrl 预览图),默认 true / Swap to the gif on hover when thumbUrl is present, default true
emojiIconstring—「Emoji」视图 tab 预览小图 URL(可选,展示图片而非文字)/ Optional icon for the "Emoji" view tab, shown as an image preview instead of text

config.textMessage ​

文本消息配置

属性类型默认值说明
enableLinkifyboolean—是否启用 URL 识别为可点击链接,默认 true
onLinkClick(url: string) => boolean | string | void—链接点击拦截器
- 返回 false:阻止跳转
- 返回 string:跳转到返回值指定的地址
- 返回 void / undefined / true:默认行为(跳转原始 URL)
enableMentionHighlightboolean—是否启用 @提及高亮识别,默认 true
onMentionClick(userId: string) => void—提及点击回调(@)
locateOnMentionClickboolean—点击消息中的 @名字时,是否在消息列表内滚动定位到该用户最近一条消息(默认 true)。
仅当未配置 onMentionClick 时生效;定位同时仍会对外触发 at-me-click 事件。
/ Whether clicking an @mention scrolls to and highlights the mentioned user's latest message in the list (default true).
Only applies when onMentionClick is not configured; the at-me-click event is still emitted alongside.

Events ​

事件名参数说明
reeditmessage: UiMessage点击自己撤回消息上的"重新编辑"按钮时触发,参数为目标消息 / Emitted when the "re-edit" button of a self-recalled message is clicked, with the target message
recall-failederror: any, message: UiMessage消息撤回失败时触发,参数为错误对象与目标消息 / Emitted when recalling a message fails, with the error and the target message
editmessage: UiMessage点击消息操作菜单中的"编辑"时触发(仅文本且未撤回的消息),参数为目标消息 / Emitted when "Edit" in the message action menu is clicked (text, non-recalled only), with the target message
forwardmessages: UiMessage[]点击消息操作菜单中的"转发"时触发,参数为待转发的消息数组(当前为单条)/ Emitted when "Forward" in the message action menu is clicked, with the messages to forward (currently a single item)
mention-clickuserId: string点击消息中的 @提及(@mention)时触发,参数为被提及的用户 ID / Emitted when an @mention in a message is clicked, with the mentioned user ID
location-clickbody: LocationMessageBody, message: UiMessage点击位置(location)消息时触发,参数为位置消息体与对应消息 / Emitted when a location message is clicked, with the location body and the message
custom-message-actionaction: string, payload: any, message: UiMessage点击自定义消息(custom)上的操作按钮时触发,参数为操作标识、载荷与对应消息 / Emitted when an action button on a custom message is clicked, with the action key, payload and the message
avatar-view-profileuserId: string, anchor: HTMLElement右键消息头像选择"查看资料"时触发,参数为消息发送者 ID 与头像锚点元素 / Emitted when "View profile" is chosen from the avatar context menu, with the sender ID and avatar anchor element
avatar-clickuserId: string, anchor: HTMLElement左键点击消息头像时触发,参数为消息发送者 ID 与头像锚点元素 / Emitted when a message avatar is left-clicked, with the sender ID and avatar anchor element
avatar-mentionpayload: { userId: string, name: string }右键消息头像选择"@提及"时触发,参数为发送者 ID 与展示名 / Emitted when "@mention" is chosen from the avatar context menu, with the sender ID and display name

Slots ​

插槽名说明
history-tip—