频道黑白名单用于管控频道对服务器成员是否可见。圈组支持选择服务器成员加入黑名单或白名单，或者选择身份组将身份组所有成员批量加入黑名单或白名单。

被加入黑白名单的用户，即为黑白名单成员；被加入黑名单或白名单的身份组，即为黑白名单身份组。

功能介绍

频道可见性的管控属于圈组消息流转中的一环，管控方式根据频道的查看模式存在区分，具体如下：

频道查看模式	可见性管控
公开	通过频道黑名单进行管控，频道对黑名单中的服务器成员不可见，即这些成员无法访问该频道，其他服务器成员均可访问该频道
私密	通过频道白名单进行管控，频道对白名单中的服务器成员可见，即这些成员可访问该频道，其他服务器成员均无法访问该频道

前提条件

• 已注册onReceiveSystemNotification事件流，监听系统通知的接收。示例代码参见接收圈组内置系统通知。

  具体与黑白名单相关的系统通知类型，见本文末尾的相关系统通知。

• 已创建频道。

实现方法

管理黑白名单成员

更新频道黑白名单成员

用户可调用updateChannelBlackWhiteMembers方法更新频道的黑白名单，将服务器成员加入或移出黑白名单，从而管控服务器成员是否可访问频道。

• 调用该方法需拥有管理黑白名单的权限（QChatRoleResource.manageBlackWhiteList）。

• 单个频道的黑白名单成员人数上限，默认为 1000。

  可在云信控制台配置该数量上限，配置路径：在云信控制台选择应用，进入IM 专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > 公开私密频道的黑白名单成员数。

示例代码如下：

dart// 将accids中的这些账户添加到黑名单中
final param = QChatUpdateChannelBlackWhiteMembersParam(
  serverId: serverId,
  channelId: channelId,
  type: QChatChannelBlackWhiteType.black,
  operateType: QChatChannelBlackWhiteOperateType.add,
  toAccids: accIds);
NimCore.instance.qChatChannelService.updateChannelBlackWhiteMembers(param).then((value) {
  if (value.isSuccess) {
    // 更新Channel黑白名单成员成功
  } else {
    // 更新Channel黑白名单成员失败
  }
});

分页查询频道黑白名单成员

调用getChannelBlackWhiteMembersByPage方法，可分页查询频道黑白名单。调用时需要传入查询的 serverId、channelId、黑白名单类型、查询锚点时间戳timeTag 和查询数量限制limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.manageBlackWhiteList）。

示例代码如下：

dart// 查处频道黑名单中的成员列表
final param = QChatGetChannelBlackWhiteMembersByPageParam(
  serverId: serverId,
  channelId: channelId,
  timeTag: DateTime.now().millisecond,
  type: QChatChannelBlackWhiteType.black);
NimCore.instance.qChatChannelService.getChannelBlackWhiteMembersByPage(param).then((value) {
  if (value.isSuccess) {
    // 查询成功,返回频道黑名单中成员列表
    var members = value.data?.memberList;
    // 下一页的起始时间戳
    var nextTimeTag = value.data?.nextTimeTag;
    // 是否还有下一页
    var hasMore = value.data?.hasMore;
  } else {
    // 查询失败
  }
});

批量查询频道黑白名单成员

调用getExistingChannelBlackWhiteMembers方法可根据传入的用户账号（accid）列表查询其中已被加入的黑白名单的用户。

单次调用最多可传入 100 个 accid。

示例代码如下：

dart//查询频道中存在的黑名单成员
final accidList = getQueryAccids();
final param = QChatGetExistingChannelBlackWhiteMembersParam(
  serverId: serverId,
  channelId: channelId,
  type: QChatChannelBlackWhiteType.black,
  accids: accidList);
NimCore.instance.qChatChannelService.getExistingChannelBlackWhiteMembers(param).then((value) {
  if (value.isSuccess) {
    // 查询到的在黑名单中的成员
    var memberList = value.data?.memberList;
  } else {
    // 查询失败
  }
});

管理黑白名单身份组

更新频道黑白名单身份组

调用updateChannelBlackWhiteRoles方法可选择身份组将所选身份组的成员批量加入或移出频道黑白名单，加入黑白名单的身份组即为黑白名单身份组。调用时需要传入服务器 ID（serverId）、频道 ID（channelId）、黑白名单类型、黑白名单操作类型和身份组 ID （roleId）。

• 调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.manageBlackWhiteList）。

• 单个频道可设置的黑白名单身份组的数量上限，默认为 20。

  可在云信控制台配置该数量上限

  在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > channel公开私密频道的黑白名单身份组对象数即可配置。
  

示例代码如下：

dartfinal param = QChatUpdateChannelBlackWhiteRolesParam(
  serverId: serverId,
  channelId: channelId,
  type: QChatChannelBlackWhiteType.black,
  roleId: roleId,
  operateType: QChatChannelBlackWhiteOperateType.add);
NimCore.instance.qChatChannelService.updateChannelBlackWhiteRoles(param).then((value) {
  if (value.isSuccess) {
    // 更新Channel黑白名单身份组成功
  } else {
    // 更新Channel黑白名单身份组失败
  }
});

分页查询黑白名单身份组列表

调用getChannelBlackWhiteRolesByPage方法可分页查询频道的黑白名单身份组列表。 调用时需要传入服务器 ID、频道 ID、黑白名单类型、查询锚点时间戳 timeTag 和查询数量限制 limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.manageBlackWhiteList）。

示例代码如下：

dart// 查处频道黑名单中的身份组列表 
final param = QChatGetChannelBlackWhiteRolesByPageParam(
  serverId: serverId,
  channelId: channelId,
  type: QChatChannelBlackWhiteType.black,
  timeTag: DateTime.now().millisecond);
NimCore.instance.qChatChannelService.getChannelBlackWhiteRolesByPage(param).then((value) {
  if (value.isSuccess) {
    // 查询成功,返回频道黑名单中身份组列表
    var roleList = value.data?.roleList;
    // 下一页的起始时间戳
    var nextTimeTag = value.data?.nextTimeTag;
    // 是否还有下一页
    var hasMore = value.data?.hasMore;
  } else {
    // 查询失败
  }
});

批量查询黑白名单身份组列表

调用getExistingChannelBlackWhiteRoles方法可根据传入的身份组 ID 列表批量查询其中被加入黑白名单的身份组。

单次调用最多可传入 100 个身份组的 ID。

示例代码如下：

dart// 查询频道中存在的黑名单身份组
final param = QChatGetExistingChannelBlackWhiteRolesParam(
  serverId: serverId,
  channelId: channelId,
  type: QChatChannelBlackWhiteType.black,
  roleIds: roleIds);
NimCore.instance.qChatChannelService.getExistingChannelBlackWhiteRoles(param).then((value) {
  if (value.isSuccess) {
    // 查询到的在黑名单中的身份组列表
    var roleList = value.data?.roleList;
  } else {
    // 查询失败
  }
});

相关系统通知

圈组系统通知的类型在QChatSystemNotificationType枚举中定义，与频道黑白名单相关的内置系统通知类型如下：

枚举值	说明
channel_update_white_black_member	“频道黑白名单成员”更新
channel_update_white_black_role	“频道黑白名单身份组”更新

这两种系统通知的接收条件，请参见服务端文档的频道相关事件通知。