跳到主要内容

消息未读数

未读消息计数是 IMKit 默认提供的一项功能，可告知用户每个会话中未读消息的数量。未读消息计数显示在会话列表 ConversationListFragment 的会话条目上。每个会话的未读消息数显示在会话图标右上角。如果未读消息数超过 100 条，则会显示为 99+ 。

提示

为了使用未读消息计数功能，您必须首先构建会话列表页面。IMKit 默认未实现底部导航栏。

(width=250)

用法​

IMKit SDK 默认已经实现了一整套会话未读消息数获取和展示逻辑，使用默认会话列表和会话页面时，不需要额外调用会话相关 API。

IMKit 会在用户进入单聊、群聊、系统会话页面时将会话未读数清零。在用户多端登录时，IMKit 会在设备间同步会话的阅读状态，您也可以按业务需求选择关闭该功能，详见下文多端同步阅读状态。

定制化​

如果 IMKit 已有实现无法满足您的需求，可以使用 IMKit 或 IMLib SDK 中相关 API。

获取会话未读数​

IMKit 未直接提供获取会话未读数的 API。如果您有类似以下自定义需求，可以调用 IMLib SDK 相关方法。

  • 获取所有会话未读数（IMLib 方法）
  • 获取指定会话未读数（IMLib 方法）
  • 按会话类型获取未读数（IMLib 方法）

具体的核心类、API 与 使用方法，详见 IMLib 文档 处理会话未读消息数。

提示

IMLib 方法并不提供页面刷新能力，您需要根据业务需求自定义通知机制进行页面刷新。

清除会话未读数​

使用 IMCenter 的 clearMessagesUnreadStatus() 方法清除指定会话的全部未读数，该方法接受一个会话类型枚举值和一个会话 ID。IMKit 会自动刷新会话列表页面的未读展示。

支持的会话类型：

  • 单聊（ConversationType.PRIVATE）
  • 群聊（ConversationType.GROUP）
  • 系统（ConversationType.SYSTEM）
ConversationType conversationType = ConversationType.PRIVATE;
String targetId = " 会话 Id ";

IMCenter.getInstance().clearMessagesUnreadStatus(conversationType, targetId, new ResultCallback<Boolean>() {

    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {

    }
});
提示
  • IMKit 未提供根据时间戳清除未读数的方法，您可以调用 IMLib SDK 提供的方法（ RongIMClient 或 RongCoreClient 的 clearMessagesUnreadStatus 方法）。IMLib 方法并不提供页面刷新能力，您需要根据业务需求自定义通知机制进行页面刷新。

监听会话未读数变化​

IMKit 提供了未读数变化监听机制。您可以设置监听器，监听指定一个或多个会话类型的会话未读数变化事件。

版本 5.6.7 及更早版本​

使用 UnReadMessageManager 的 addObserver 方法设置 IUnReadMessageObserver，传入需要监听的会话类型数组。一旦监听的会话类型的会话未读数发生变化，SDK 会触发 onCountChanged 方法，将总未读消息数通过此监听器回调给应用。

UnReadMessageManager.getInstance().addObserver(conversationTypes,observer);

不需要监听时可以注销已注册的未读消息数变化监听器。

UnReadMessageManager.getInstance().removeObserver(observer);

版本 5.8.0 及以后版本​

在 5.8.0 及以后的版本中，我们引入了 addForeverObserver 和 removeForeverObserve 接口。这些接口通过强引用实现，确保了监听器的持久性。如果您在 Activity或 Fragment 中使用此功能，建议在组件生命周期结束时调用 removeForeverObserver 来移除监听器，以避免潜在的内存泄漏问题。

UnReadMessageManager.getInstance().addForeverObserver(conversationTypes, observer);

不需要监听时可以注销已注册的未读消息数变化监听器。

UnReadMessageManager.getInstance().removeForeverObserver(observer);

请注意，addObserver 和 removeObserver 接口在版本 5.8.0 及以后版本中通过弱引用实现，减少了内存泄漏的风险。

版本 5.6.10​

这个版本存在 UnReadMessageManager 监听失效的问题，建议您升级到版本 5.8.0，并根据接口指南进行操作。

修改已读未读状态图标为文本​

SDK 会话页面中文本消息已读的 UI 默认是一个“对勾”图标，如果希望修改为「已读」或「未读」，可以在消息展示时将 SDK 默认的图标移除。

修改步骤详见知识库文档修改已读未读状态图标为文字提示。

多端同步阅读状态​

提示

如果 SDK 版本 ≦ 5.6.2，不支持多端同步系统会话的已读、未读状态。

在即时通讯业务中，同一用户账号可能在多个设备上登录。仅在开通多设备消息同步服务后，融云会在多个设备之间同步消息数据，但设备上的会话中消息的已读/未读状态仅存储在本地。

IMKit SDK 已默认实现了会话多端阅读状态同步功能，在一端发起同步后，其他端可接收通知，按要求同步阅读状态。您可以按业务需求决定是否使用该功能，该功能默认开启。

RongConfigCenter.conversationConfig().setEnableMultiDeviceSync(true);

主动同步消息未读状态​

IMKit SDK 默认在进入会话页面后会清理会话消息的未读状态。如需在未进入会话页面时同步未读状态，需要 App 主动同步消息未读状态。

IMCenter 提供 syncConversationReadStatus 方法，可在多端登录时，通知其它终端同步某个会话的消息未读状态。该方法同时按时间戳清除本端会话中传入时间之前的所有消息的未读状态。会话列表页面的会话未读数也会同步刷新。

IMCenter.getInstance().syncConversationReadStatus(conversationType, targetId, timestamp, callback);
参数类型说明
conversationTypeConversationType会话类型
targetIdString会话 ID
timestampString该会话中已读的最后一条消息的发送时间戳
callbackRongIMClient.OperationCallback回调接口
ConversationType conversationType = ConversationType.PRIVATE;
String targetId = " 会话 Id ";
String timestamp = "12222222";

IMCenter.getInstance().syncConversationReadStatus(conversationType, targetId, timestamp, new RongIMClient.OperationCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(RongIMClient.ErrorCode errorCode) {
    }
});

监听消息未读状态同步数据​

提示

IMKit 内置的会话列表页面已通过该监听实现了未读状态的同步逻辑，当其它端的消息变为已读时，本端通过监听会清除对应会话的消息未读数，您不需要额外处理。

IMCenter 中提供了 SyncConversationReadStatusListener 监听器。客户端设置该监听器后，才能接收来自其他同步的阅读状态数据。

IMCenter.getInstance().addSyncConversationReadStatusListener(listener);

在接收到阅读状态同步数据后，会触发监听器的以下方法。SDK 会将指定会话中早于等于 syncConversationReadStatus 传入时间戳的消息均置为已读：

onSyncConversationReadStatus(Conversation.ConversationType type, String targetId)
参数类型说明
conversationTypeConversationType会话类型
targetIdString会话 ID

未读消息气泡提醒​

IMKit 支持在会话页面中显示未读消息气泡提醒。

(width=250)

是否显示未读消息数提醒​

如果会话的未读消息数已超过 10，可在进入会话页面后在右下角显示提醒气泡，例如「99+」。用户点击提醒气泡后，页面会跳转到最开始的未读消息。

未读消息数提醒组件默认不显示，您可以调用如下方法打开此功能：

// 设置显示未读消息数目
RongIM.getInstance().enableUnreadMessageIcon(true);
// 或者使用以下方法
RongConfigCenter.conversationConfig().setShowHistoryMessageBar(true);

未读消息气泡在未读消息大于 10 条 即可展示，超过 99 条显示为 "99+ 条新消息"。控件样式可以在 rc_conversation_fragment.xml 中进行调整，具体控件为 rc_new_message_number。

启用未读消息数提醒后，默认未读消息气泡在未读消息大于 10 条 时展示。您可以配置未读消息为多少条时才展示气泡。

RongConfigCenter.conversationConfig().setConversationShowUnreadMessageCount(10);

是否显示未读 @ 消息数提醒​

当一个群聊会话收到大量消息（超过一个屏幕能显示的内容），且收到的消息中有 @ 消息时，进入会话页面后，会话页面右上角会提示未读 @ 消息数。用户点击该提醒按钮，会跳转到最早的未读 @ 消息处，同时未读 @ 消息数量减 1。再次点击，未读 @ 消息数量会根据当前屏幕内看到的个数相应减少。

新消息提醒组件默认不显示，您可以调用如下方法打开此功能：

// 设置显示未读 @ 消息数提醒
RongConfigCenter.conversationConfig().setShowNewMentionMessageBar(true);

是否显示新消息提醒​

如果用户在查看会话页面中的历史消息，且当前视图未显示会话最新消息，此时如果收到新消息，会话页面右下角可显示新消息气泡提醒，例如「15 条新消息」。用户点击提醒按钮，会滚动到会话最新消息处。

新消息提醒组件默认不显示，您可以调用如下方法打开此功能：

// 设置显示新消息提醒
RongIM.getInstance().enableNewComingMessageIcon(true);
// 或者使用以下方法
RongConfigCenter.conversationConfig().setShowHistoryMessageBar(true);

新消息气泡在新消息数量大于 1 条 即可展示，超过 99 条 显示为 99+。控件的样式可以在 layout/rc_fr_messagelist.xml 中进行调整。

最后于 更新