本文介绍频道分组的技术原理、创建频道分组的实现方法以及相关示例代码。

技术原理

网易云信 QChat Web SDK 的QChatChannelCategoryInfo结构体定义了频道分组。同时，SDK 的QChatChannelServiceInterface接口提供管理频道分组的相关方法，助您快速实现对频道的分类管理。

频道管理相关方法，基本都需要满足如下两个前提条件才能调用。各方法的具体调用前提，请参见本文的 API参考。

• 频道分组对用户可见，具体机制见下文的频道分组可见机制。
• 拥有管理频道的权限（QChatRoleAuth枚举中的manageChannel）。

频道分组可见机制

• 频道分组对服务器成员的可见机制与频道的类似，分如下两种情况：

  • 如果频道分组为公开频道分组，那么只要用户未被加入频道分组黑名单，频道分组就对其可见。
  • 如果频道分组为私密频道分组，那么用户需被加入频道分组白名单，频道分组才对其可见。

  频道分组黑白名单相关说明，请参见频道分组黑白名单

• 频道分组是否对游客可见，取决于频道分组内是否有频道对游客可见。如果频道分组内有频道对游客可见，则该频道分组对游客也可见。频道是否对游客可见由visitorMode决定，可在创建频道和修改频道时设置，具体见频道管理。

  如果频道的visitorMode为跟随模式，且同步模式（syncMode）为“与频道分组同步”，则当该频道所属的频道分组的查看模式（viewMode）变更后，该频道对游客的可见性也将变更。例如，在这种情况下，频道分组的查看模式由公开变为私密，则此时该频道对游客从“可见”变为“不可见”。

频道分组与频道的关联逻辑

频道管理相关方法（如createChannel)的入参包含categoryId和syncMode。在调用 createChannel时传入categoryId可将频道加入某个频道分组；通过设置syncMode，可实现频道数据与频道分组数据的同步，具体同步的数据包括查看模式（私密或公开）、黑白名单和身份组权限。

参数	类型	说明
categoryId	long	频道需加入或所在的频道分组 ID。设置为 0 表示频道没有频道分组。设置为频道分组 ID 表示归属某个频道分组
syncMode	number	频道同步模式 传1同步 传0不同步 不传默认不同步 如果频道查看模式、黑白名单、身份组权限等被修改，自动改为不同步

归属于单个频道分组的频道数量上限为 50。

频道分组与服务器的关联逻辑

定义了服务器的serverInfo类中包含categoryNumber参数，该参数表示服务器内频道分组的数量。

服务器内频道分组数量上限为 100。

频道分组与系统通知的关联逻辑

频道分组相关事件的系统通知为 SDK 内置系统通知，在ESystemMessageType枚举内定义。具体类型及相关的触发和接收条件见下表。

系统通知类型	触发条件	接收条件
channelCategoryCreate	频道分组成功创建时	服务器创建者和所有者：在线 其他成员：服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000，需在线且订阅服务器
channelCategoryRemove	频道分组被删除时	删除者和服务器所有者：在线 其他成员：服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000，需在线且订阅服务器
channelCategoryUpdate	频道分组信息被修改时	修改者和服务器所有者：在线 其他成员：服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000，需在线且订阅服务器
channelCategoryUpdateWhiteBlackIdentify	频道分组黑白名单身份组被修改时	修改者、服务器所有者和身份组成员（身份组成员限制 100 人）：在线 其他成员：服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000，需在线且订阅服务器
channelCategoryUpdateWhiteBlackIdentifyUser	频道分组黑白名单成员被修改时	修改者、服务器所有者和被加入/移出黑白名单的用户：在线 其他成员：服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000，需在线且订阅服务器

2,000 人阈值可联系商务经理调整。

实现方法

本节以服务器所有者和服务器成员的交互为例，介绍服务器成员创建频道分组的实现流程。

• 服务器所有者拥有全局权限，可以在创建服务器后直接调用createChannelCategory方法创建频道分组。
• 用户创建频道分组后， 可对频道分组做更新、删除、修改和查询等操作，相关可调用的方法请参见本文的API 参考。

前提条件

• 已接入圈组，并已创建圈组服务器和身份组。
• 已创建 云信 IM 账号，作为下文中服务器所有者和服务器成员的云信 IM 账号。

实现流程

1. 服务器所有者调用addMembersToServerRole方法，将服务器成员加入身份组。
2. 服务器所有者调用updateServerRole方法，授予该身份组管理角色的权限（manageChannel）。
3. 服务器成员调用createChannelCategory方法创建频道分组。

API 调用时序图

示例代码

服务器所有者，授予身份组权限：

// 服务器Id
const serverId = "YOUR_SERVER_ID";
// 服务器身份组Id
const roleId = "YOUR_ROLE_ID";
// 将某人加入服务器身份组
await qchat.qchatRole.addMembersToServerRole({
    serverId,
    roleId,
    accids: []
})
// 授予身份证管理频道权限
await qchat.qchatRole.updateServerRole({
    serverId,
    roleId,
    auths:{"manageChannel":"allow"}
})

某服务器成员，创建频道：

// serverId 可以从 getServersByPage 中获取，或者是刚加入某 server 时，从系统通知中获取
// 同时可以调用 checkPermission 查询自己是否有manageChannel权限
const serverId = "YOUR_SERVER_ID";
await qchat.qchatChannel.createChannelCategory({
  serverId,
  name: "test",
  viewMode: 1    
})

API参考

API	调用前提	说明
createChannelCategory	用户拥有管理频道的权限	创建频道分组
removeChannelCategory	频道分组对用户可见，且用户拥有管理频道的权限	删除频道分组
updateChannelCategory	频道分组对用户可见，且用户拥有管理频道的权限	修改频道分组信息
getChannelCategoriesPage	频道分组对用户可见，且用户拥有管理频道的权限	查询服务器下的频道分组列表
getChannelCategoryChannelsPage	频道分组对用户可见，且用户拥有管理频道的权限	分页查询频道分组下频道列表
getChannelCategoriesByID	无	根据频道分组的 ID 查询频道分组