服务器未读数，指圈组服务器下所有频道的总未读数。网易云信 NIM SDK 的QChatServerUnreadInfoChangedEvent类定义了圈组服务器未读信息变更事件。用户在圈组频道内发送或删除消息后，SDK 触发该事件，事件信息包含未读信息QChatServerUnreadInfo。您可调用QChatObserver类的serverUnreadInfoChanged 方法监听该事件。

本文介绍获取服务器未读数并按需清空的实现方法以及相应的示例代码。

前提条件

已登录圈组，并已创建服务器和频道。

实现流程

本节以用户A 与其他用户在同一圈组服务器下的消息交互为例，介绍获取服务器未读数的实现方法。

流程概览

sequenceDiagram


note over NIM SDK: 初始化 SDK 并登录 IM
note over NIM SDK: 注册监听并登录圈组
用户A ->> NIM SDK: 监听服务器未读信息变更事件<br>(serverUnreadInfoChanged)
用户A ->> NIM SDK: 登录
其他用户 ->> NIM SDK: 登录
note over NIM SDK: 成为同一服务器成员
用户A ->> NIM SDK: 创建服务器
用户A ->> NIM SDK: 在服务器内创建多个频道<br>(此处以公开频道为例)
其他用户 ->> NIM SDK: 加入服务器
note over NIM SDK: 订阅
用户A ->> NIM SDK: 订阅服务器下所有频道<br>(subscribeAllChannel)
note over NIM SDK: 管理服务器未读数
其他用户 ->> NIM SDK: 在频道内发送消息/删除消息
NIM SDK ->> 用户A: 服务器未读信息<br>(QChatServerUnreadInfo) 
用户A ->> NIM SDK: 清空服务器未读数<br>(markRead)
NIM SDK ->> 用户A: 未读数清空的结果<br>(QChatServerMarkReadResult)

流程说明

1. 用户A 注册serverUnreadInfoChanged 事件流，监听服务器未读数变化事件（QChatServerUnreadInfoChangedEvent）。

   示例代码如下：

   dartNimCore.instance.qChatObserver.serverUnreadInfoChanged.listen((event) {
     // 获取变更后服务器未读信息列表
     var serverUnreadInfos = event.serverUnreadInfos ?? [];
     //遍历变更的服务器未读信息
     for (var serverUnreadInfo in  serverUnreadInfos) {
     }
   });
   

2. 根据服务器下的频道数量，按如下方法订阅服务器下的所有频道的未读数。订阅后 SDK 获取并缓存各频道的初始未读数。

   • 如果目标服务器下的频道数量不超过 200 个，则用户A 可调用subscribeAllChannel方法一次性订阅服务器下所有的频道的未读数（单次调用最多可传入 10 个 服务器 ID）。
   • 如果目标服务器下的频道数量超过 200 个，则用户 A 需多次调用subscribeChannel方法订阅服务器下所有频道的未读数（单次调用最多可订阅 100 个频道）。
   • 通过subscribeAllChannel订阅频道，单次调用可传入的服务器 ID 数量上限为 10 个。即使多次调用，单个服务器下最多仅能订阅 200 个 频道。如果目标服务器下频道数量大于 200，需改用subscribeChannel方法订阅服务器下所有频道（单次调用最多可订阅 100 个频道）。
   • 获取服务器的精确未读数，必须订阅服务器下的所有频道的未读数。
   
   示例代码如下：
   调用 subscribeAllChannel 的示例

   dartfinal param = QChatSubscribeAllChannelParam(QChatSubscribeType.channelMsg, serverIds);
   NimCore.instance.qChatServerService.subscribeAllChannel(param).then((value) {
     if (value.isSuccess) {
       // 操作成功
       //订阅成功的频道未读信息
       var unreadInfoList = value.data?.unreadInfoList;
       //订阅失败的频道Id列表
       var failedList = value.data?.failedList;
     } else {
       // 操作失败
     }
   });
   

   调用 subscribeChannel 的示例

   dartfinal param = QChatSubscribeChannelParam(type: QChatSubscribeType.channelMsgUnreadCount,
                                           operateType: QChatSubscribeOperateType.sub,
                                           channelIdInfos: channelIdInfos);
   NimCore.instance.qChatChannelService.subscribeChannel(param).then((value) {
     if (value.isSuccess) {
       // 订阅成功
     } else {
       // 订阅失败
     }
   });
   

3. 其他用户发送消息后，SDK 对服务器下所有已订阅频道的未读数进行累加计算。

   未读数累加规则如下：

   • 接到新消息，某个频道未读数 +1 时：
     • 如果累加未读数达到未读数上限（maxCount），则触发QChatServerUnreadInfoChangedEvent，并给出maxCount。
     • 如果累加未读数没有达到maxCount，则触发QChatServerUnreadInfoChangedEvent，并给出累加未读数。
   • 消息被删除，某个频道未读数 - 1 时：
     • 如果累加未读数达到maxCount，则触发QChatServerUnreadInfoChangedEvent，并给出maxCount。
     • 如果累加未读数没有达到maxCount，则触发QChatServerUnreadInfoChangedEvent，并给出累加未读数。

4. SDK 计算完所有已订阅频道的累加未读数（QChatServerUnreadInfo）后，将其返回给用户A。

   服务器累加未读数在达到maxCount后，QChatServerUnreadInfoChangedEvent事件将不会触发。

5. 如需清空该服务器的未读数，可调用markRead方法清空。

   示例代码如下：

   dartfinal param = QChatServerMarkReadParam(serverIds);
   NimCore.instance.qChatServerService.markRead(param).then((value) {
     if (value.isSuccess) {
       // 清空未读数成功的服务器Id列表
       var successServerIds = value.data?.successServerIds;
       //清空未读数失败的服务器Id列表
       var failedServerIds = value.data?.failedServerIds;
     } else {
       // 操作失败
     }
   });
   

API参考