自定义消息

在使用 Web IMKit 时，如果业务需要发送和展示自定义消息类型，需要先通过 registerMessageType 注册消息类型。注册后，Web IMKit 才能解析该消息，并按灰条消息或气泡消息渲染。

registerMessageType

提示

registerMessageType 接口仅在 kitApp.ready() 之前调用生效。

参数	类型	必填	说明
messageType	String	是	消息类型，由开发者自行定义。请勿以 RC: 开头进行定义，以避免与内置消息类型定义冲突。
options	IRCKitRegisterMessageTypeOpts	是	消息配置项，其详细属性说明如下。

IRCKitRegisterMessageTypeOpts 配置说明

属性	类型	必填	说明
isPersited	Boolean	否	是否存储。 false：消息不进入历史消息列表，Web IMKit 不在消息列表中展示。收到此类消息时，SDK 通过 RCKitEvents.UNSCHEDULED_MESSAGES 事件通知业务处理。 true：消息进入历史消息列表，并可在消息列表中展示。此时需要实现 digest 函数；如果要以消息气泡展示，还需要提供 component。
isCounted	Boolean	否	是否计数，影响接收方收到消息时的未读数计数。
isStatusMessage	Boolean	否	是否为状态消息。状态消息不计数、不存储，且不进入离线补偿，仅限用户在线时接收。
searchProps	Array of String	否	参与消息搜索匹配的消息内容字段名。
digest	Function	否	消息摘要计算函数，用于自定义消息在会话列表（最后一条消息）和消息列表（灰条消息）中的展示。若注册时提供 component，SDK 会在消息列表中优先使用 component 渲染消息。
component	IRCKitCustomMessageComponentOpts	否	消息气泡 UI 渲染组件定义。如果不配置，SDK 会使用 digest 的返回值将消息渲染为灰条消息。

消息显示分类

Web IMKit 中，所有消息按显示需求可以分为三类：

• 通知类消息：通常将 isPersited 设为 false。SDK 内部不展示此类消息，你可以通过监听 RCKitEvents.UNSCHEDULED_MESSAGES 事件自行处理。
• 灰条消息：在消息列表中以灰条形式展示，如群成员变更通知。通常将 isPersited 设为 true，不配置 component，并提供 digest 摘要计算函数。一般情况下，灰条消息不计数，即 isCounted 为 false。
• 气泡消息：在消息列表中以消息气泡形式展示，如文本消息、图片消息。此类消息需要提供 component 组件定义。

注册灰条消息

此处以自定义 'Xyz' 类型消息为例，示例代码如下：

JavaScript

const XyzMessage = kitApp.registerMessageType('Xyz', {
  isCounted: true,
  isPersited: true,
  isStatusMessage: false,
  searchProps: ['content'],
  digest: (message, language) => {
    // message 为消息对象，可以用于读取消息内容
    // language 为当前使用的语言环境，如 `zh_CN`、`en_US` 等
    return '这是一条灰条消息';
  },
});

注册气泡消息

提示

Web IMKit 内部使用 Vue 作为 DOM 组件渲染引擎。因此，定义自定义组件时，组件模板语法与 Vue 模板语法一致。

从 5.42.0 开始，自定义消息组件 props 新增 position 字段，用于区分当前组件渲染在消息列表还是引用预览区域。已实现自定义消息组件的业务，建议适配该字段，避免在引用预览中展示过重或不适合预览的完整消息 UI。

position 取值参考 RCKitMessageComponentRenderPosition：

值	说明
RCKitMessageComponentRenderPosition.MESSAGE_LIST	渲染在消息列表中。
RCKitMessageComponentRenderPosition.QUOTE_INFO	渲染在引用预览区域中。

此处以自定义 'Xyz' 类型消息为例，示例代码如下：

JavaScript

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

const XyzMessage = kitApp.registerMessageType('Xyz', {
  isCounted: true,
  isPersited: true,
  isStatusMessage: false,
  searchProps: ['content'],
  digest: (message, language) => {
    // 对于气泡消息来说，digest 函数的返回值将只被用于会话列表中的最后一条消息展示
    return '[XyzMessage]';
  },
  // 定义气泡消息组件
  component: {
    // 组件标签名称
    tag: 'xyz-message',
    // 组件模板
    template: `<div>{{ data }}</div>`,
    setup(props, ctx) {
      const { message, position } = props;
      const isQuotePreview =
        position === RCKitMessageComponentRenderPosition.QUOTE_INFO;

      return {
        data: isQuotePreview ? '[XyzMessage]' : message.content,
      };
    },
    // 样式表
    styles: [
      `
      div {
        color: red;
      }
    `,
    ],
  },
});

提示

开启消息回应能力后，消息对象可能包含 reactions 数据。自定义消息组件如需展示回应状态，请结合业务展示需求和 RCKitCommand.MESSAGE_REACTION_ENABLED 开关状态处理。

发送自定义消息

通过 sendMessage 接口发送即可。示例代码如下：

JavaScript

// 构建目标会话
const conversation = {
  conversationType: RongIMLib.ConversationType.PRIVATE,
  targetId: 'A',
};
// 构建消息
const msg = new XyzMessage({ content: 'hello' });
// 发送消息
const { code } = await kitApp.sendMessage(conversation, msg);