Android
频道分组
更新时间： 2022/12/27 17:25:13
网易云信即时通讯 NIM Android SDK 的QChatChannelCategory结构体定义了频道分组。同时，SDK 的QChatChannelService接口提供管理频道分组的相关方法，助您快速实现对频道的分类管理。
功能介绍
频道管理相关方法，基本都需要满足如下两个前提条件才能调用。各方法的具体调用前提，请参见本文的 API参考。
- 频道分组对用户可见，具体机制见下文的频道分组可见机制。
- 拥有管理频道的权限（
QChatRoleResource枚举中的MANAGE_CHANNEL）。
频道分组可见机制
-
频道分组对服务器成员的可见机制与频道的类似，分如下两种情况：
- 如果频道分组为公开频道分组，那么只要用户未被加入频道分组黑名单，频道分组就对其可见。
- 如果频道分组为私密频道分组，那么用户需被加入频道分组白名单，频道分组才对其可见。
频道分组黑白名单相关说明，请参见频道分组黑白名单。
-
频道分组是否对游客可见，取决于频道分组内是否有频道对游客可见。如果频道分组内有频道对游客可见，则该频道分组对游客也可见。频道是否对游客可见由
visitorMode决定，可在创建频道和修改频道时设置，具体见频道管理。如果频道的
visitorMode为跟随模式，且同步模式（syncMode）为“与频道分组同步”，则当该频道所属的频道分组的查看模式（viewMode）变更后，该频道对游客的可见性也将变更。例如，在这种情况下，频道分组的查看模式由公开变为私密，则此时该频道对游客从“可见”变为“不可见”。
与频道的关联逻辑
频道管理相关方法（如createChannel）的入参包含categoryId和syncMode。在调用createChannel时传入 categoryId 可将频道加入某个频道分组；通过设置syncMode，可实现频道数据与频道分组数据的同步。具体同步的数据包括查看模式（私密或公开）、黑白名单和身份组权限。
参数 |
类型 |
说明 |
|---|---|---|
categoryId |
long | 频道需加入或所在的频道分组 ID。设置为 0 表示频道没有频道分组。设置为频道分组 ID 表示归属某个频道分组 |
syncMode |
QChatChannelSyncMode |
频道同步模式。传1同步，传0不同步，不传默认不同步。如果频道查看模式、黑白名单、身份组权限等被修改，自动改为不同步 |
归属于单个频道分组的频道数量上限为 50。
与服务器的关联逻辑
QChatServer结构体包含categoryNumber参数，该参数表示服务器内频道分组的数量。QChatServer结构体定义了服务器。
服务器内频道分组数量上限为 100。
实现方法
本节以服务器所有者（即创建者）和服务器成员的交互为例，介绍服务器成员创建频道分组的实现流程。
- 服务器所有者拥有全局权限，可以在创建服务器后直接调用
createChannelCategory方法创建频道分组。 - 用户创建频道分组后， 可对频道分组做更新、删除、修改和查询等操作，相关可调用的方法请参见本文的API 参考。
前提条件
-
已注册
observeReceiveSystemNotification监听圈组的系统通知。示例代码参见圈组系统通知收发。具体与频道分组管理相关的系统通知类型，见本文末尾的相关系统通知。
-
已创建服务器。
实现流程
- 服务器所有者调用
addMembersToServerRole方法将服务器成员加入身份组。 - 服务器所有者调用
updateServerRole方法授权该身份组管理频道的权限。 - 服务器成员调用
createChannelCategory方法创建频道分组。
API 调用时序图
示例代码
//************************1.将服务器成员加入身份组************************/
//服务器Id
long serviceId = 2114708;
//服务器身份组Id
long roleId = 21343;
//需要加入服务器的成员账户
String accid = "test1";
List<String> accidList = new ArrayList<>();
accidList.add(accid);
QChatAddMembersToServerRoleParam addMembersToServerRoleParam = new QChatAddMembersToServerRoleParam(serviceId,roleId,accidList);
NIMClient.getService(QChatRoleService.class).addMembersToServerRole(addMembersToServerRoleParam).setCallback(
new RequestCallback<QChatAddMembersToServerRoleResult>() {
@Override
public void onSuccess(QChatAddMembersToServerRoleResult result) {
List<String> failedAccids = result.getFailedAccids();
//如果失败列表中成员accid，表示成功了
if(!failedAccids.contains(accid)){
//成功的UI操作
}
}
@Override
public void onFailed(int code) {
}
@Override
public void onException(Throwable exception) {
}
});
//************************2.授予该身份组管理频道权限************************/
//如果该身份组没有管理频道权限，则授予该身份组管理频道权限
QChatUpdateServerRoleParam updateServerRoleParam = new QChatUpdateServerRoleParam(serviceId,roleId);
//开启管理频道权限
Map<QChatRoleResource, QChatRoleOption> resourceAuths = new HashMap<>();
resourceAuths.put(QChatRoleResource.MANAGE_CHANNEL,QChatRoleOption.ALLOW);
updateServerRoleParam.setResourceAuths(resourceAuths);
NIMClient.getService(QChatRoleService.class).updateServerRole(updateServerRoleParam).setCallback(
new RequestCallback<QChatUpdateServerRoleResult>() {
@Override
public void onSuccess(QChatUpdateServerRoleResult result) {
// 返回更新后的服务器身份组
QChatServerRole role = result.getRole();
}
@Override
public void onFailed(int code) {
}
@Override
public void onException(Throwable exception) {
}
});
//************************3.创建频道分组************************/
QChatCreateChannelCategoryParam categoryParam = new QChatCreateChannelCategoryParam(serviceId);
categoryParam.setName("频道分组名称");
categoryParam.setCustom("频道分组自定义扩展字段");
//设置频道查看模式
categoryParam.setViewMode(QChatChannelMode.PUBLIC);
NIMClient.getService(QChatChannelService.class).createChannelCategory(categoryParam).setCallback(
new RequestCallback<QChatCreateChannelCategoryResult>() {
@Override
public void onSuccess(QChatCreateChannelCategoryResult result) {
//返回创建好的频道分组
QChatChannelCategory category = result.getCategory();
}
@Override
public void onFailed(int code) {
}
@Override
public void onException(Throwable exception) {
}
});
相关参考
相关系统通知
频道分组相关事件的系统通知为 SDK 内置系统通知，在QChatSystemNotificationType枚举内定义。具体类型及相关的触发和接收条件见下表。
系统通知类型 |
触发条件 |
接收条件 |
|---|---|---|
CHANNEL_CATEGORY_CREATE(21) |
频道分组成功创建时 |
|
CHANNEL_CATEGORY_REMOVE(22) |
频道分组被删除时 |
|
CHANNEL_CATEGORY_UPDATE(23) |
频道分组信息被修改时 |
|
2,000 人阈值可联系商务经理调整。
相关推送配置
-
与频道分组相关的推送配置方法：
updateUserChannelCategoryPushConfig、getUserChannelCategoryPushConfigs -
圈组的详细推送功能说明请参见推送管理
API参考
API |
调用前提 |
说明 |
|---|---|---|
createChannelCategory |
用户拥有管理频道的权限 | 创建频道分组 |
deleteChannelCategory |
频道分组对用户可见，且用户拥有管理频道的权限 | 删除频道分组 |
updateChannelCategory |
频道分组对用户可见，且用户拥有管理频道的权限 | 修改频道分组信息 |
getChannelCategories |
无 | 查询频道分组 |
getChannelCategoriesByPage |
频道分组对用户可见，且用户拥有管理频道的权限 | 分页查询服务器下的频道分组列表 |
getChannelsInCategoryByPage |
频道分组对用户可见，且用户拥有管理频道的权限 | 分页查询频道分组下频道列表 |
