跳到主要内容

消息未读数

未读消息计数是 IMKit 默认提供的一项功能，可告知用户每个会话中未读消息的数量。

未读消息计数显示在会话列表 会话组件-Component（ConversationComponent） 的会话条目上。每个会话的未读消息数显示在会话图标右上角。如果未读消息数超过 100 条，则会显示为 99+ 。

提示

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

(width=250)

用法​

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

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

定制化​

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

获取会话未读数​

获取单个会话的未读数​

示例代码​

TypeScript
let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

RongIM.getInstance().conversationService().getUnreadCount(conId).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取未读数失败
    return;
  }
  if (!result.data) {
    // 未读数为 null
    return;
  }
  let unreadCount = result.data as number;
});

参数说明​

参数名类型详细说明
conIdConversationIdentifier会话标识，包含会话类型与会话的 targetId

按会话类型列表获取未读数，可以选择是否包含免打扰​

示例代码​

TypeScript
let typeList = new List<ConversationType>();
typeList.add(ConversationType.Private);
typeList.add(ConversationType.Group);

let isContainBlocked = false;

RongIM.getInstance().conversationService().getUnreadCountByTypes(conTypeList, isContainBlocked).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取未读数失败
    return;
  }
  if (!result.data) {
    // 未读数为 null
    return;
  }
  let unreadCount = result.data as number;
});

参数说明​

参数名类型详细说明
typeListList需要查询的会话类型列表
isContainBlockedboolean是否包含被屏蔽会话的未读数

IMKit 未直接提供获取多个或者所有会话未读数的 API。如果您有类似自定义需求，可以调用 IMLib SDK 相关方法：获取所有会话未读数与获取多个会话的未读消息数

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

提示

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

清除会话未读数​

IMKit 支持清除指定会话的未读数，清除完毕后会自动刷新会话列表页面的未读展示。 支持的会话类型：

  • 单聊（ConversationType.PRIVATE）
  • 群聊（ConversationType.GROUP）
  • 系统（ConversationType.SYSTEM）

清除指定会话的未读数​

您可以使用 IMEngine 的 clearMessagesUnreadStatus() 方法清除指定会话的全部未读数，该方法接受一个会话标识 ConversationIdentifier 对象。

TypeScript
let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

IMEngine.getInstance().clearMessagesUnreadStatus(conId).then(result => {
  if (EngineError.Success !== result.code) {
    // 清空未读数失败
    return;
  }
  / 清空未读数成功
})

清除指定会话指定时间戳前的未读数​

您可以使用 IMEngine 的 clearMessagesUnreadStatus() 方法清除指定会话的全部未读数，该方法接受一个会话标识 ConversationIdentifier 对象与时间戳。

TypeScript
let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "TestTargetId"; // 按需填写实际的会话 id

let time = Date.now();

IMEngine.getInstance().clearMessagesUnreadStatusByTime(conId, time).then(result => {
  if (EngineError.Success !== result.code) {
    // 清空未读数失败
    return;
  }
  // 清空未读数成功
})

监听会话未读数变化​

IMKit 目前暂不支持监听未读数变化。

多端同步阅读状态​

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

IMKit SDK 已默认实现了会话多端阅读状态同步功能，在一端发起同步后，其他端可接收通知，按要求同步阅读状态。该功能默认开启，目前暂不支持关闭。

主动同步消息未读状态​

IMKit SDK 默认在进入会话页面后会清理会话消息的未读状态。如需在未进入会话页面时同步未读状态，需要 App 主动同步消息未读状态。其他端调用该方法将某个会话同步已读之后， 鸿蒙会触发 SyncConversationReadStatusListener 回调。

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

TypeScript
let conId = new ConversationIdentifier();
conId.conversationType = ConversationType.Private;
conId.targetId = "会话 Id";

// 会话中已读的最后一条消息的发送时间戳，此处用了当前时间
let time = Date.now();

IMEngine.getInstance().syncConversationReadStatus(conId,time).then(result => {
  if (EngineError.Success !== result.code) {
    // 同步已读失败
    return;
  }
  // 同步已读成功
});

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

提示

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

IMEngine 中提供了 SyncConversationReadStatusListener 监听器。客户端设置该监听器后，才能接收来自其他同步的阅读状态数据。在接收到阅读状态同步数据后，会触发监听器的 onSyncConversationReadStatus 方法。SDK 会将指定会话中早于等于 syncConversationReadStatus 传入时间戳的消息均置为已读：

示例代码​

TypeScript
let listener : SyncConversationReadStatusListener = {                                        
  onSyncConversationReadStatus: (conId: ConversationIdentifier, timestamp: number): void => {
   // 该会话的 timestamp 之前的消息未读已清空                                                              
  }                                                                                          
}                                                                                            
IMEngine.getInstance().addSyncConversationReadStatusListener(listener);

参数说明​

参数类型说明
conIdConversationIdentifier会话标识
timestampnumber已读的毫秒时间戳，该时间戳前的消息已读

未读消息气泡提醒​

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

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

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

默认未读消息气泡在未读消息大于 10 条 时展示。目前暂不支持关闭，暂不支持自定义样式。

是否显示新消息提醒​

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

新消息提醒组件默认默认显示，在新消息数量大于 1 条 即可展示，超过 99 条 显示为 99+。目前暂不支持关闭，暂不支持自定义样式。

最后于 更新