事件监听

Web IMKit 通过事件机制向业务代码暴露 UI 交互、消息发送前处理、输入框状态变化等能力。你可以监听事件获取数据，也可以在部分事件中阻断默认行为或返回处理结果，用自定义交互替换 SDK 内置 UI。

所有的对外事件类型定义，可通过 Web IMKit 对外常量 RCKitEvents 获取。

JavaScript

import { RCKitEvents } from '@rongcloud/im-kit';

添加事件监听

代码示例

JavaScript

// 以 RCKitEvents.ALERT_EVENT 事件举例
kitApp.addEventListener(RCKitEvents.ALERT_EVENT, (evt) => {
  // evt 为 RCKitEvent 对象，包含事件的类型、数据等信息
  const { data } = evt;
  console.log('收到警告提示信息：', data);
});

参数

名称	类型	是否必需	说明
eventType	String	是	事件类型，可通过 RCKitEvents 常量获取
listener	Function	是	事件监听器，接收一个 RCKitEvent 对象作为参数
thisObj	Object	否	事件监听器 this 指向

RCKitEvent 对象

所有事件监听器的回调函数，均接收一个 RCKitEvent 类或其子类对象作为参数，该对象包含了事件的类型、数据等信息。

阻断默认行为

RCKitEvent 提供 preventDefault 方法，用于阻断 Web IMKit 默认行为。

以 RCKitEvents.ALERT_EVENT 事件为例，当 Web IMKit 派发此事件时，你可以通过 RCKitEvent 对象获取警告提示信息，并调用 preventDefault 阻断 SDK 默认弹窗，改用业务自定义弹窗展示。

JavaScript

const listener = (evt) => {
  const { data } = evt;
  // 阻断 SDK 默认行为，SDK 内部将不再弹窗告警
  evt.preventDefault();
  // 使用业务自定义弹窗展示提示信息
  alert(data);
};

kitApp.addEventListener(RCKitEvents.ALERT_EVENT, listener);

发送结果

部分事件需要将处理结果返回给 Web IMKit，以便 SDK 继续执行后续流程。此时，可以通过 RCKitEvent 对象的 sendResult 方法返回结果。

以 RCKitEvents.CONFIRM_EVENT 事件为例，Web IMKit 默认会弹出内置确认弹窗，并接收一个布尔值作为用户选择结果。

你可以拦截该事件，展示自定义确认弹窗，并通过 sendResult 将用户选择结果返回给 Web IMKit。

JavaScript

const listener = (evt) => {
  const { data } = evt;
  // 阻断 SDK 默认行为，避免 SDK 使用内置 UI 弹窗
  evt.preventDefault();
  // 使用业务自定义确认弹窗
  confirm(data, (result) => {
    // 将用户的确认结果返回给 SDK
    evt.sendResult(result);
  });
};

kitApp.addEventListener(RCKitEvents.CONFIRM_EVENT, listener);

sendResult 仅接受第一次调用时传入的参数作为处理结果，后续调用将被忽略。

提示

并非所有事件都支持阻断默认行为或通过 sendResult 返回处理结果。请以事件列表中的说明为准。

移除事件监听

示例

JavaScript

kitApp.removeEventListener(RCKitEvents.ALERT_EVENT, listener);

参数说明

名称	类型	是否必需	说明
eventType	String	是	事件类型，可通过 RCKitEvents 常量获取
listener	Function	是	事件监听器，接收一个 RCKitEvent 对象作为参数
thisObj	Object	否	事件监听器 this 指向

输入框事件

从 5.42.0 开始，Web IMKit 支持监听输入框聚焦、失焦和内容变化事件。三个事件携带的数据结构一致，均为 { value: string }。其中，value 表示事件触发时输入框中的文本内容。

JavaScript

kitApp.addEventListener(RCKitEvents.INPUT_TEXTAREA_CHANGE, (evt) => {
  console.log('当前输入内容：', evt.data.value);
});

事件	触发时机
RCKitEvents.INPUT_TEXTAREA_FOCUS	输入框获得焦点时触发。
RCKitEvents.INPUT_TEXTAREA_BLUR	输入框失去焦点时触发。
RCKitEvents.INPUT_TEXTAREA_CHANGE	用户输入导致内容变化时触发。

消息发送前事件

从 5.42.0 开始，Web IMKit 在发送消息前派发 RCKitEvents.BEFORE_SEND_MESSAGE 事件。你可以在事件回调中同步修改本次发送的 message 或 options，适用于补充消息扩展字段、统一注入发送配置等场景。

JavaScript

kitApp.addEventListener(RCKitEvents.BEFORE_SEND_MESSAGE, (evt) => {
  evt.data.message.content.extra = JSON.stringify({
    source: 'crm',
  });
});

事件数据结构如下：

字段	类型	说明
conversation	IConversationOption	本次发送目标会话。
message	BaseMessage	本次发送的消息体。
options	ISendMessageOptions	本次发送配置。

important

BEFORE_SEND_MESSAGE 仅支持同步修改 message 或 options，不支持异步拦截，也不支持取消发送。

消息回应详情事件

从 5.42.0 开始，Web IMKit 新增 RCKitEvents.REACTIONS_DETAIL_EVENT 事件。该事件在用户点击消息回应详情入口时触发，事件数据包含当前消息和回应 ID。你可以监听该事件，展示业务自定义的回应详情面板。

JavaScript

kitApp.addEventListener(RCKitEvents.REACTIONS_DETAIL_EVENT, (evt) => {
  console.log('消息：', evt.data.message);
  console.log('回应 ID：', evt.data.reactionId);
});

事件列表

RCKitEvents 常量定义了 Web IMKit 对外提供的事件类型。

派发模式说明：

• 0：默认模式。优先向业务代码派发；业务代码调用 preventDefault 后，事件不再继续传递给 SDK 内部。
• 1：同时向业务代码和 SDK 内部派发，不受业务拦截影响，也不接收业务返回结果。
• 2：仅向业务代码派发，SDK 内部不处理。

事件	事件携带数据类型	派发模式	说明
ALERT_EVENT	String	0	SDK 提示信息
CONFIRM_EVENT	String	0	SDK 确认提示弹窗事件。该监听可接收业务返回结果，结果类型为 Boolean。
DELETE_MESSAGE_MODAL_EVENT	IRCKitModalDeleteMessage	0	消息撤回或删除确认弹窗。该监听可接收业务返回结果，结果类型为 IRCKitModalDeleteMessageResult。
MEDIA_MESSAGE_MODAL_EVENT	IRCKitCachedMessage	0	媒体消息弹框事件
COMBINE_MESSAGE_MODAL_EVENT	IRCKitCachedMessage	0	合并转发消息弹框事件
FORWARDING_EVENT	RCKitModalForwardingType	0	消息转发弹框事件。该监听可接收业务返回结果，结果类型为 [RCKitModalForwardingResult][RCKitModalForwardingResult]。
TAKE_PHOTO_MODAL_EVENT	-	0	拍照弹框事件
UNSCHEDULED_MESSAGES	IAReceivedMessage[]	0	接收到 SDK 内部无法处理的消息，业务可通过监听该事件获取消息
CONVERSATION_EXTENSION_CLICK	IRCKitConversationExtensionClick	0	会话面板业务扩展功能按钮点击事件
BEFORE_SYSTEM_CONVERSATION_OPEN	IRCKitCachedConversation	2	系统会话打开前事件，业务可通过监听该事件自定义系统会话打开方式
CONVERSATION_MENU_ITEM_CLICK	IRCKitConversationMenuItemClick	0	会话菜单项点击事件
INPUT_MENU_ITEM_CLICK	IRCKitInputMenuItemClick	2	输入框菜单点击事件
INPUT_TEXTAREA_FOCUS	InputTextareaEventData	1	输入框聚焦事件，携带当前输入内容
INPUT_TEXTAREA_BLUR	InputTextareaEventData	1	输入框失焦事件，携带当前输入内容
INPUT_TEXTAREA_CHANGE	InputTextareaEventData	1	输入框内容变化事件，携带当前输入内容
BEFORE_SEND_MESSAGE	BeforeSendMessageEventData	1	消息发送前事件，仅支持同步修改 message 或 options，不支持异步拦截或取消发送
REACTIONS_DETAIL_EVENT	{ message: IRCKitCachedMessage; reactionId: string }	1	消息回应详情事件，用于打开指定消息的回应详情
CONVERSATION_SELECTED	{ conversation: IRCKitCachedConversation | null; focusInput?: boolean }	1	选中会话变更事件
CONVERSATION_ICON_CLICK	IRCKitConversationIconClick	2	消息列表头像点击事件
CONVERSATION_NAVI_CLICK	IRCKitCachedConversation	2	会话详情标题栏头像点击事件
MESSAGES_DELETED	IRCKitDeleteMessageData	1	消息删除事件
MESSAGE_MENU_ITEM_CLICK	IRCKitMessageMenuItemClick	0	消息菜单点击事件
MESSAGE_LINK_CLICK	IRCKitMessageLinkClick	0	文本消息中链接点击事件
DOWNLOAD_LINK_EVENT	IRCKitCachedMessage	0	媒体消息点击下载事件
FILE_SEND_FAILED_EVENT	File[]	0	文件发送失败事件，一般是由于文件超出尺寸限制或为空文件导致
TOAST_EVENT	{ message: string; showIcon?: boolean }	0	提示框显示事件