跳到主要内容
版本：5.X

消息扩展

消息扩展功能可以对已发送的消息增加、修改、删除扩展信息。

消息扩展功能可为消息增加基于 Key/Value 的状态标识。消息的扩展信息可在发送前、后设置或更新，可用于实现消息评论、礼物领取、订单状态变化等业务需求。

一条消息是否可携带或可设置扩展信息，由发送消息时的可扩展（canIncludeExpansion）属性决定，发送后无法修改该属性。因此消息发送前需要将消息设置为可扩展，才能对该条消息进行扩展信息添加、删除等操作。

单条消息单次最多可设置 20 个扩展信息 KV 对，总计不可超过 300 个扩展信息 KV 对。在并发情况下如出现设置超过 300 个的情况，超出部分会被丢弃删除。

消息扩展（Key、Value 扩展信息）会被存储。如已开通历史消息云存储功能，从服务端获取的历史消息也会携带已设置的扩展信息。

提示

消息扩展仅支持单聊、群聊、超级群会话类型。不支持聊天室和系统会话。

实现思路​

以订单状态变化为例，可通过消息扩展改变消息显示状态。以订单确认为例：

  1. 当用户购买指定产品下单后，商家需要向用户发送订单确认信息。可在发送消息时，将 canIncludeExpansion 属性设置为可扩展，同时设置用于标识订单状态的 Key 和 Value。例如，在用户未确认前，可用一对 Key/Value 表示该订单状态为「未确认」。
  2. 用户点击确认（或其他确认操作）该订单消息后，订单消息状态需要变更为「已确认」。此时，可通过 updateMessageExpansion 更新此条消息的扩展信息，标识为已确认状态，同时更改本地显示的消息样式。
  3. 发送方通过消息扩展状态监听，获取指定消息的状态变化，根据最新扩展信息显示最新的订单状态。

消息评论、礼物领取可参照以上实现思路：

  • 礼物领取：可通过消息扩展改变消息显示状态实现。例如，向用户发送礼物，默认为未领取状态，用户点击后可设置消息扩展为已领取状态。
  • 消息评论：可通过设置原始消息扩展信息的方式添加评论信息。

打开消息的可扩展属性（仅发送前）​

发送新消息前，可通过 SendMessage 的 options.canIncludeExpansion 属性打开或关闭该条消息的可扩展属性。必须在发送消息前设置该属性。

您还可以在发送消息前设置扩展信息数据 options.expansion。下例中发送的消息会携带 expansion 属性中的扩展信息数据。

// 定义消息投送目标会话, 这里定义一个群组类型会话
const conversation = { conversationType: RongIMLib.ConversationType.GROUP, targetId: '<目标 Id>' }
// 实例化待发送消息，RongIMLib.TextMessage 为内置文本型消息
const message = new RongIMLib.TextMessage({ content: '文本内容' })
// 配置属性
const options = {
  // 打开消息的可扩展属性
  canIncludeExpansion: true,
  expansion: { key1: 'tom', key2: 'jerry' }
}

RongIMLib.sendMessage(conversation, message, options).then(res => {
  if (res.code === RongIMLib.ErrorCode.SUCCESS) {
    // 消息发送成功，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送成功。
    console.log('消息发送成功', res.data)
  } else {
    // 消息发送失败，可以根据返回结果中的 messageId 字段将列表中的该消息状态改为发送失败。
    console.log('消息发送失败', res.code, res.msg)
  }
})

针对 Electron 平台，可能存在 App 先在本地插入消息，再发送本地已插入的消息的业务场景（例如 App 业务要求在发送前审核消息内容）。如需使用消息扩展功能，请注意以下事项：

  • 插入消息时，需要设置 canIncludeExpansion 属性。插入成功后不支持再修改可扩展属性开关的状态。
  • 发送时，需要从成功插入的消息中（IAReceivedMessage）获取本地消息 ID（messageId）。发送成功后，SDK 会根据 SendMessage 的 options.expansion 中的扩展数据刷新本地数据库中消息的扩展数据。

更新消息扩展信息​

调用 updateMessageExpansion 设置、更新消息扩展信息。对端可通过监听收到扩展数据更新。

  • 仅支持单聊、群聊会话类型，不支持聊天室类型。
  • 每次设置消息扩展将会产生内置通知消息，频繁设置扩展会产生大量消息。
  • 仅当发送消息时指定 canIncludeExpansion 值为 true，才可对消息进行拓展
RongIMLib.updateMessageExpansion({ key1: 'val1', key2: 'val2' }, message).then(res => {
  if (res.code === 0) {
    console.log(res.code, '更新成功')
  } else {
    console.log(res.code, res.msg)
  }
})
参数类型说明
expansionMap要更新的消息扩展信息键值对，类型是 HashMap。
  • Key 支持大小写英文字母、数字、 特殊字符+ = - _ 的组合方式，不支持汉字。最大 32 个字符。
  • （SDK < 5.3.0）Value 最大 64 个字符
  • （SDK ≧ 5.3.0）Value 最大 4096 个字符
messageIAReceivedMessage通过接收在线消息或拉取历史消息从 IMLib 取得的消息实例。

删除消息扩展信息​

调用 removeMessageExpansionForKey 删除消息扩展信息。

RongIMLib.removeMessageExpansionForKey(['key1', 'key2'], messsage).then(res => {
  if (res.code === 0) {
    console.log(res.code, '删除成功')
  } else {
    console.log(res.code, res.msg)
  }
})
参数类型说明
keyArrayList消息扩展信息中待删除的 key 的列表，类型是 ArrayList。
messageIAReceivedMessage通过接收在线消息或拉取历史消息从 IMLib 取得的消息实例

监听消息扩展通知​

可通过监听 Events.EXPANSION 事件来捕获消息的拓展信息变更通知

RongIMLib.addEventListener(RongIMLib.Events.EXPANSION, ({ updatedExpansion, deletedExpansion }) => {
  console.log('拓展信息更新：'， updatedExpansion);
  console.log('拓展信息删除：'， deletedExpansion);
})
最后于 更新