NIM SDK 的NIMQChatChannelCategory结构体定义了频道分组。同时，SDK 的NIMQChatChannelManager协议提供管理频道分组的相关方法，助您快速实现对频道的分类管理。

功能介绍

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

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

频道分组可见机制

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

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

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

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

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

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

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

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

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

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

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

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

实现方法

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

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

前提条件

• 已注册onRecvSystemNotification:监听圈组的系统通知。示例代码参见圈组系统通知收发。

  具体与频道分组管理相关的系统通知类型，见本文末尾的相关系统通知。

• 已创建服务器。

实现流程

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

API 调用时序图

sequenceDiagram


服务器所有者 ->> 圈组: addServerRoleMembers
服务器所有者 ->> 圈组: updateServerRole
服务器成员 ->> 圈组: createChannelCategory

示例代码

//*********************  1.将服务器成员加入身份组  *********************//
//服务器id
unsigned long long serverId = 18999;
//身份组id
unsigned long long roleId = 211456;
//需要加入服务器的用户
NSString *accId = @"test1";
NIMQChatAddServerRoleMembersParam *addServerRoleMembersParam = [[NIMQChatAddServerRoleMembersParam alloc] init];
addServerRoleMembersParam.serverId = serverId;
addServerRoleMembersParam.roleId = roleId;
addServerRoleMembersParam.accountArray = @[accId];
[[NIMSDK sharedSDK].qchatRoleManager addServerRoleMembers:addServerRoleMembersParam completion:^(NSError * _Nullable error, NIMQChatAddServerRoleMembersResult * _Nullable result) {
    if (!error) {
        // do something when success
    }
}];
//*********************  2.授予该身份组管理频道权限  *********************//
NIMQChatUpdateServerRoleParam *updateServerRoleParam = [[NIMQChatUpdateServerRoleParam alloc] init];
updateServerRoleParam.roleId = roleId;
updateServerRoleParam.serverId = serverId;
NIMQChatPermissionStatusInfo *permission = [[NIMQChatPermissionStatusInfo alloc] init];
permission.type = NIMQChatPermissionTypeManageChannel;
permission.status = NIMQChatPermissionStatusAllow;
updateServerRoleParam.commands = @[permission];
[[NIMSDK sharedSDK].qchatRoleManager updateServerRole:updateServerRoleParam completion:^(NSError * _Nullable error, NIMQChatServerRole * _Nullable result) {
    if (!error) {
        // do something when success
    }
}];
//*********************  3.创建频道分组  *********************//
NIMQChatCreateChannelCategoryParam *createChannelCategoryParam = [[NIMQChatCreateChannelCategoryParam alloc] init];
createChannelCategoryParam.serverId = serverId;
createChannelCategoryParam.name = @"分组名";
[[NIMSDK sharedSDK].qchatChannelManager createChannelCategory:createChannelCategoryParam completion:^(NSError * _Nullable error, NIMQChatChannelCategory * _Nullable result) {
    if (!error) {
        // do something when success
    }
}];

相关参考

相关系统通知

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

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

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

相关推送配置

• 与频道分组相关的推送配置方法：updatePushNotificationProfile:channelCategory、getUserPushNotificationConfigByChannelCategories

• 具体的推送机制请参见圈组APNs推送

API参考

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