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

消息扩展

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

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

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

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

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

提示

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

实现思路​

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

  1. 用户下单后，商家向用户发送订单确认消息，发送时设置 canIncludeExpansion: true，并在 expansion 中添加表示订单状态的 Key/Value，例如 orderStatus: "未确认"。
  2. 用户确认订单后，客户端调用 updateMessageExpansion 方法，更新该条消息的扩展信息，将 orderStatus 更新为 "已确认"，同时更新本地消息样式。
  3. 发送方可通过监听扩展信息变更事件，实时获取该消息的状态变动，更新界面展示。

类似地，可实现：

  • 礼物领取：消息初始扩展状态为未领取，用户点击领取后，更新扩展信息标识为已领取，实时变更消息样式。
  • 消息评论：通过为原始消息设置或追加扩展信息，记录评论内容或状态。

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

发送消息前，可通过 sendMessage 方法中的 options.canIncludeExpansion 属性开启消息扩展功能。需在发送前设定，发送后无法更改。

同时，可通过 options.expansion 参数，直接为消息附加初始扩展信息。

示例代码​

typescript
// 定义消息投送目标会话, 这里定义一个群组类型会话
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 属性，插入后不可再修改该状态。
  • 发送时，需使用插入消息返回的 messageId，调用 sendMessage 并在 options.expansion 中传入扩展信息。发送成功后，SDK 会同步更新本地数据库中的扩展数据。

更新消息扩展信息​

调用 updateMessageExpansion 方法，更新指定消息的扩展信息。对端客户端可通过监听扩展变更事件获取实时更新。

提示
  • 仅支持单聊、群聊类型会话。
  • 每次更新扩展信息，都会产生内置通知消息，频繁调用可能影响性能。
  • 仅对发送时 canIncludeExpansion: true 的消息生效。

接口​

JavaScript
RongIMLib.updateMessageExpansion(expansion, message)

参数说明​

参数类型必填说明
expansionRecord<string, string>是待更新的扩展信息键值对。
  • Key 仅支持英文字母、数字、+ = - _，最大 32 字符。
  • （SDK < 5.3.0）Value 最大 64 字符。
  • （SDK ≥ 5.3.0）Value 最大 4096 字符。
messageIAReceivedMessage是待更新的消息对象，通过在线消息或历史消息获取

示例代码​

JavaScript
RongIMLib.updateMessageExpansion({ key1: 'val1', key2: 'val2' }, message).then(res => {
  if (res.code === 0) {
    console.log(res.code, '更新成功')
  } else {
    console.log(res.code, res.msg)
  }
})

删除消息扩展信息​

调用 removeMessageExpansionForKey方法，删除指定 Key 的扩展信息。

接口​

JavaScript
RongIMLib.removeMessageExpansionForKey(keys, message)

参数说明​

参数类型必填说明
keysstring[]是待删除的扩展信息 Key 数组
messageIAReceivedMessage是待操作的消息对象

示例代码​

JavaScript
RongIMLib.removeMessageExpansionForKey(['key1', 'key2'], messsage).then(res => {
  if (res.code === 0) {
    console.log(res.code, '删除成功')
  } else {
    console.log(res.code, res.msg)
  }
})

监听消息扩展通知​

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

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