帮你快速理解、总结文档立即下载
文档中心>即时通信 IM>无 UI 集成>消息相关>消息引用>Web&小程序&uni-app

Web&小程序&uni-app

最近更新时间：2026-09-04 16:24:32
我的收藏

本页目录：

功能描述

说明：
消息引用功能在 V4.4.0 及以上版本支持。
消息引用用于在发送一条新消息时，关联一条历史消息，并在接收方的消息气泡上展示引用气泡，点击引用气泡可定位并跳转到被引用的原消息。
一个完整的消息引用功能通常包含三个环节：
发送引用消息：在待发送的消息体上写入被引用消息的信息（quoteInfo），再发送。
展示引用气泡：接收 / 拉取到消息后，根据 quoteInfo 在消息气泡上方展示被引用消息的预览。
点击跳转：点击引用气泡，定位并滚动到被引用的原消息；本地没有则从云端跳拉。

接口说明

quoteInfo 数据结构

参数
类型
描述
msgID
string
被引用消息的 ID。
messageTime
number
被引用消息的时间，单聊（C2C） 跳转定位时作为锚点。
messageSequence
number
被引用消息的序列号，群聊（GROUP） 跳转定位时作为锚点。

创建引用消息

接口
chat.createQuoteMessage(message, quotedMessage)
参数
参数
类型
必填
描述
message
Message
是
待发送的消息实例。
quotedMessage
Message
是
被引用的消息实例。
// 1. 创建消息实例
let message = chat.createTextMessage({
  to: 'user1',
  conversationType: TencentCloudChat.TYPES.CONV_C2C,
  payload: {
    text: 'Hello world!'
  },
});

// 2. 创建引用消息，quotedMessage 为被引用消息
let quoteMessage = chat.createQuoteMessage(message, quotedMessage);

// 3. 发送消息
let promise = chat.sendMessage(quoteMessage);
promise.then(function(imResponse) {
  // 发送成功
  console.log(imResponse);
}).catch(function(imError) {
  // 发送失败
  console.warn('sendMessage error:', imError);
});

最佳实践

接收 / 拉取到的消息若携带 quoteInfo 且不为空，即为引用消息。UI 层根据 quoteInfo 找到原消息后，在消息气泡上方展示引用气泡。点击引用气泡时，需要定位并跳转到被引用的原消息。

展示引用气泡

拉取历史消息后，如果历史消息包含引用消息，这时候需要展示被引用消息的内容，业务侧需要从本地消息列表或者服务端消息列表去拉取消息才能展示。
本地有消息
// 1. 获取被引用消息 ID
const { msgID, messageTime, messageSequence } = message.quoteInfo;

// 2. 查找本地消息
let quotedMessage = chat.findMessage(msgID);
本地没有消息
// 1. 如果 quotedMessage 为空，需要从远端拉取消息
const isGroup = conversationID.startsWith('GROUP');

// 2. 群聊用 sequence 定位，单聊用 time 定位
const anchor = isGroup
  ? { conversationID, sequence: messageSequence }
  : { conversationID, time: messageTime };

// 3. 向上拉更旧的 15 条
const messageList = await chat.getMessageListHopping({
  ...anchor,
  count: 15,
});

// 4. 从服务端 getMessageListHopping 返回的消息列表查询被引用消息
let quotedMessage = messageList.find((message) => message.ID === msgID);


点击引用气泡跳转到原消息

点击引用气泡时，需要定位并跳转到被引用的原消息。根据原消息是否在本地消息列表中，处理逻辑分为以下两种场景。
本地已有被引用消息，直接跳转
// 1. 获取被引用消息 ID
const { msgID, messageTime, messageSequence } = message.quoteInfo;

// 2. 查找本地消息
let quotedMessage = chat.findMessage(msgID);

if (quotedMessage) {
  // scrollToMessage(quotedMessage) 业务侧实现滚动到被引用消息逻辑
}
本地没有被引用消息需要续拉历史消息才支持跳转
// 1. 获取被引用消息 ID
const { msgID, messageTime, messageSequence } = message.quoteInfo;

// 2. 查找本地消息
let quotedMessage = chat.findMessage(msgID);

if (!quotedMessage) {
  // 1. 如果 quotedMessage 为空，需要从远端拉取消息
  const isGroup = conversationID.startsWith('GROUP');

  // 2. 群聊用 sequence 定位，单聊用 time 定位
  const anchor = isGroup
    ? { conversationID, sequence: messageSequence }
    : { conversationID, time: messageTime };

  // 3. 向上拉更旧的 15 条
  const messageList = await chat.getMessageListHopping({
    ...anchor,
    count: 15,
  });

  // 4. 从服务端 getMessageListHopping 返回的消息列表查询被引用消息
  let quotedMessage = messageList.find((message) => message.ID === msgID);

  // scrollToMessage(quotedMessage) 业务侧实现滚动到被引用消息逻辑
}

被引用消息被撤回 / 删除的处理

被引用的原消息可能在引用后被撤回或删除。Message 实例提供两个状态字段用于判断：
字段
类型
描述
isRevoked
boolean
消息是否已被撤回。
isDeleted
boolean
消息是否已被删除。
业务侧在 展示引用气泡 和 点击跳转 两个环节都需要先判断被引用消息的状态：
若 isRevoked 为 true，引用气泡应展示引用的消息已被撤回，点击不再跳转。
若 isDeleted 为 true，引用气泡应展示引用的消息已被删除，点击不再跳转。
中国站