IM 即时通讯(增强版)
Web
开发指南

频道分组

更新时间: 2023/06/27 19:13:25

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

技术原理

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

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

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

频道分组可见机制

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

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

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

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

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

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

频道管理相关方法(如createChannel)的入参包含categoryIdsyncMode。在调用 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 调用时序图

uml diagram

示例代码

服务器所有者,授予身份组权限:

// 服务器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 查询频道分组
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 频道分组可见机制
  • 频道分组与频道的关联逻辑
  • 频道分组与服务器的关联逻辑
  • 频道分组与系统通知的关联逻辑
  • 实现方法
  • 前提条件
  • 实现流程
  • API 调用时序图
  • 示例代码
  • API参考