跳到主要内容

逐条消息已读功能

重要提示
  • 需要开通单群聊消息云存储服务后，才能使用此功能。
  • IMKit 逐条消息已读功能自 SDK 26.1.0 版本起支持。
  • 自 2025.11.25 起，新建的 AppKey 且 SDK 版本 ≥ 26.1.0 时，默认开启逐条消息已读功能，单群聊已读回执功能将失效。
  • 如果您希望使用原来的单群聊已读回执功能，请提交工单申请切换。
  • 逐条消息已读功能依赖历史消息云存储能力，使用前请确认当前 App Key 已开通单群聊消息云端存储服务。您可以在控制台 IM 服务的服务购买页面为当前使用的 App Key 开启服务。如果使用生产环境的 App Key，请注意仅 IM 旗舰版或 IM 尊享版可开通该服务。
  • 群成员超过 3000 人时，不支持群聊逐条消息已读功能。

IMKit 内置页面中已默认实现逐条消息已读功能。当接收端查看到某条消息时，会发送这条消息的已读回执，发送端则会收到这条消息的已读回执回调，同时刷新消息已读标记图标，例如绿色的对勾图标。

逐条消息已读功能的回执发送逻辑：进入单群聊会话页面后，当某条接收的消息在屏幕中展示后，才会触发这条消息的已读回执的发送。

已读回执显示开关​

逐条消息已读功能开通后，IMKit 客户端的回执显示功能默认开启，在单聊和群聊中默认会展示消息回执。

您可以修改支持的会话类型。可以将逐条消息已读功能的回执显示配置为仅在单聊中支持，群聊中将不显示逐条消息已读功能的回执；传入空数组表示关闭逐条消息已读功能的回执显示。

TypeScript
let config = RongIM.getInstance().conversationService().getConversationConfig()
config.setSupportReadReceiptConversationType([ConversationType.Private])
RongIM.getInstance().conversationService().setConversationConfig(config)

单聊已读回执​

在单聊会话中，发送方会实时收到消息的已读状态更新。在 IMKit 内置页面中，单聊已读状态显示在两处：

  1. 会话列表页面：会话列表的每条会话会显示会话中的最后一条消息的预览。如果单聊会话最后一条消息是自己发送的消息，那么会展示已读回执状态的图标。

    • 如果最后一条消息未被对方阅读，默认展示灰色的圆圈图标。
    • 如果最后一条消息被对方阅读，默认展示绿色的对勾图标。

  2. 消息列表页面：在发送方的单聊会话页面，消息的左下角会显示对勾图标，表示对方已读；如果显示灰色圆圈图标，则表示对方未读。

会话列表页面
图 1：会话列表页面
消息列表页面
图 2：消息列表页面

群聊已读回执​

在群聊会话中，发送方会实时收到消息的已读状态更新。在 IMKit 内置页面中，群聊已读状态显示在消息列表页面，消息的左下角会显示消息已读状态。

消息阅读情况说明：

  • 无人阅读时，显示灰色圆圈图标；
  • 部分人阅读时，显示绿色饼状图图标，代表已读人数与总人数的占比情况；
  • 所有人已读时，显示绿色对勾图标。

已读回执详情页面​

点击消息左下角已读状态按钮，即可进入已读回执详情页面。单聊会话页面不可点击。

自定义已读回执按钮点击事件​

您可以通过 addMessageClickListener 添加已读回执按钮的自定义点击事件。

TypeScript
let msgClickListener: MessageClickListener = {
    onReadReceiptStateClick(message, context, event) {
      // 自定义处理
    }
  };
  RongIM.getInstance().conversationService().addMessageClickListener(msgClickListener);

页面定制化​

在实现自定义已读回执按钮点击事件 onReadReceiptStateClick 方法时，您可以在该方法中编写跳转逻辑，将用户引导至自定义页面。在自定义页面内，可直接引用 SDK 内置的 ReadReceiptDetailsComponent 组件，以展示已读和未读成员列表，实现回执详情的标准展示效果。