频道未读数管理 - IM 即时通讯（增强版）

IM 即时通讯（增强版）

开发者中心

更新时间： 2023/11/16 10:31:15

如果您的应用 UI 上需要展示频道未读数，可参考本文介绍的方法/事件获取频道内的消息未读信息并管理其变化。

游客接收到的消息无已读未读逻辑。不支持对游客展示消息的未读数。

技术原理

网易云信 IM SDK 的 QCHAT_BROWSER_SDK 下的QChatChannelServiceInterface 模块提供 UnreadInfo 属性，该属性内包含未读信息相关参数，具体见下表。

参数	类型	说明
`serverId`	string	频道所属的服务器的 ID
`channelId`	string	频道的 ID
`unreadCount`	number	频道内的消息未读数
`mentionedCount`	number	频道内@消息的未读数
`ackTimestamp`	number	（可选）已读时间戳（Unix 时间戳），该时间戳对应的消息和早于该时间戳的消息都为已读消息
`maxCount`	number	（可选）最大消息未读数
`lastMsgTime`	number	（可选）最后一条消息的时间戳（Unix 时间戳）

您可调用多个方法获取该属性，具体方法参见本文的实现频道未读数持续监听和实现频道未读数的直接获取。

前提条件

已完成圈组初始化及登录。

使用限制

频道未读数管理存在如下与未读数相关的限制：

所有未读消息（包括@消息）的消息阈值默认为 99 条。
@消息的未读数的有效期，默认为 7 天，即默认存储 7 天。

若需要扩展上限，可在控制台配置圈组子功能项（未读的@消息数-周期 和 所有未读消息（包括@）的消息计数-阈值），具体请参考开通和配置圈组功能。

实现频道未读数持续监听

本文通过以下 UI 简图的场景为例，说明如何完成频道 1 未读数的监听、未读数的清零以及清零后的持续监听。

WebElite未读管理示例.png

步骤1: 监听未读数

您需要订阅 频道 1 的未读数才能实现监听。完成如下两个子步骤后，当有新的消息下发到频道 1 ，SDK 将触发未读数变化监听事件 unreadInfo 并上报给您。

订阅的频道仅在当前登录期间有效（因网络波动导致的断线自动重连除外）。如您调用 destroy 或 logout 方法刷新页面或登出后，需要重新订阅。

进入服务器 1 后，调用 getChannelsByPage 方法刷新频道列表，得到频道 1、频道 2、频道 3 和 频道 4。

调用 subscribeChannel 方法订阅频道 1。调用该方法时入参配置如下：

参数	说明
`channels`	频道 ID：传入您需要订阅的频道 ID，以及该频道所属的服务器的 ID。格式为 `{ channelId: string; serverId: string }[]`。
`opeType`	操作类型：传入 `1` 订阅指定的频道。
`type`	订阅类型：传入 `2` 订阅频道的未读数。

入参配置示例代码如下：

{
  "type": 2,
  "opeType": 1,
  "channels": [
    {
      "serverId": "1426749",
      "channelId": "1344541"
    },
    {
      "serverId": "1426749",
      "channelId": "1344541"
    },
    {
      "serverId": "1426749",
      "channelId": "1344541"
    },
    {
      "serverId": "1426749",
      "channelId": "1344541"
    }
  ]
}

步骤2：清除未读数

以下说明以清除频道 1 的未读数为例，介绍在完成步骤1: 监听未读数后，如何清除频道未读数以及清除后对未读数进行持续监听。

进入频道 1 后，记住您应用中“代表该频道的属性” （这里以在圈组 Web Demo 基础上的集成为例，该开发场景下该属性为 currentChannel）。
调用 markMessageRead 方法，调用时传 time 参数为已读的最新消息的时间戳（Unix 时间戳），进行未读数的清零操作。

未读数清零时，SDK 触发 unreadInfo事件，该事件包含的未读数参数unreadCount 为 0。
- 针对同一个频道（channelId），调用 markMessageRead 方法存在频控限制，200 ms 内只能调用一次。
- 如果调用markMessageRead时传time参数为0，会将频道内所有消息标记为未读。
示例代码如下：
```
// mark all message unread
await qchat.qchatMsg.markMessageRead({
  "serverId": "132305",
  "channelId": "67291",
  "time": 0
})

// mark all message read
await qchat.qchatMsg.markMessageRead({
  "serverId": "132305",
  "channelId": "67291",
  "time": new Date().getTime()
})
```
根据您的应用逻辑做出判断和处理：当currentChannel与unreadInfo事件里的channelId相同时，每当频道 1 有新消息接收时，仍旧会触发unreadInfo事件。

实现频道未读数的直接获取

如果您不想订阅某个频道，而只想获取该频道当前的未读数，完成以下操作即可。

确保您已在当前频道中。

直接调用 getChannelUnreadInfos 查询当前频道未读信息。

示例代码：

const qchat = new QChat({...})
qchat.qchatChannel.getChannelUnreadInfos({"channels": [
    {
      "serverId": "YOUR_SEVERID",
      "channelId": "YOUR_CHANNELID"
    }
  ]})

该方法单次最多查询频道数量为 100。