频道身份组 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

频道身份组

更新时间： 2024/11/21 17:18:39

频道身份组用于对用户在频道维度进行权限控制。频道身份组分为两种，@everyone 身份组和自定义身份组。其中 @everyone 身份组在频道创建时默认自动创建，自定义身份组需要用户手动创建。

频道下 @everyone 身份组的属性和权限默认继承自服务器的 @everyone 身份组。

频道身份组定义

SDK 内定义频道身份组的类为QChatChannelRole。该类的成员参数如下：

单击展开查看 QChatChannelRole 的参数

参数	返回数据类型	说明
`roleId`	int	频道身份组 ID
`serverId`	int	频道身份组所属服务器的 ID
`channelId`	int	频道身份组所属的频道的 ID
`parentRoleId`	int	频道身份组所继承的服务器身份组的 ID
`name`	String	频道身份组名称
`icon`	String	频道身份组图标的 URL
`extention`	String	频道身份组的扩展字段
`resourceAuths`	Map<`QChatRoleResource`, `QChatRoleOption`	频道身份组的权限列表，其中: `QChatRoleResource`表示身份组权限项，具体说明请参见身份组权限项 `QChatRoleOption`定义了权限的配置状态（开启或关闭），包括： `allow`：开启，身份组成员将拥有该权限 `deny`：关闭，身份组成员无该权限 `inherit`：继承（针对频道自定义身份组来说，指继承自频道的 @everyone 身份组中对应的相同权限项的配置状态）
`type`	`QChatRoleType`	返回身份组的类型，`everyone`表示@everyone 身份组，`custom`表示自定义身份组
`createTime`	int	频道身份组的创建时间
`updateTime`	int	频道身份组配置的更新时间

前提条件

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

具体与频道身份组相关的系统通知类型，见本文末尾的相关系统通知。
已创建服务器。

实现方法

以下两个时序图分别展示了服务器普通成员（用户B）和服务器创建者（用户A）进行频道身份组管理前需要实现的业务逻辑。普通成员需要拥有管理频道和管理角色的权限才能创建和管理频道身份组，而服务器创建者默认拥有全量权限，可以在频道内直接创建并管理频道身份组。

服务器普通成员管理频道身份组：

sequenceDiagram



note over QChat 实例: 初始化与登录

note over QChat 实例: 用户A 将相应权限授予用户 B
用户A ->> QChat 实例: 创建服务器
用户A ->> QChat 实例: 创建服务器身份组
用户A ->> QChat 实例: 修改服务器身份组
note over 用户A: 修改时将该身份组的<br>管理角色权限和管理频道权限开启，<br>使该身份组成员拥有这两项权限
用户A ->> QChat 实例: 邀请用户B 加入服务器
用户B ->> QChat 实例: 接受邀请加入服务器
note left of 用户B: 需先加入服务器<br>才能被加为身份组成员
用户A ->> QChat 实例: 将用户B 加入服务器身份组
note over 用户A: 用户B 加入该身份组后，<br>获得管理角色权限和管理频道权限

note over QChat 实例: 用户B 可访问用户A 创建的频道
用户A ->> QChat 实例: 在服务器内创建频道
note over 用户A: 用户B 在以下两种情况下可访问频道（即成为频道成员）：<br>1. 创建的是公开频道，且用户B 未被加入频道黑名单<br>2. 创建的私密频道，且用户B 被加入频道白名单

note over QChat 实例: 用户B 设置频道身份组
note over 用户B: 用户B 可访问频道，且拥有<br>管理角色权限和管理频道权限，<br>所以可创建和管理频道身份组
用户B ->> QChat 实例: 创建频道自定义身份组<br>(addChannelRole)
用户B ->> QChat 实例: 修改频道自定义身份组<br>(updateChannelRole)
用户B ->> QChat 实例: 此处省略其他接口调用
用户B ->> QChat 实例: 删除频道自定义身份组<br>(removeChannelRole)

服务器创建者管理频道身份组：

sequenceDiagram



note over QChat 实例: 初始化与登录
note over QChat 实例: 创建服务器
note over QChat 实例: 创建服务器身份组
note over QChat 实例: 将其他用户加入服务器
note over QChat 实例: 将其他用户加入服务器身份组
note over QChat 实例: 创建频道
note over QChat 实例: 管理频道身份组
用户A ->> QChat 实例: 创建频道自定义身份组<br>(addChannelRole)
用户A ->> QChat 实例: 修改频道自定义身份组<br>(updateChannelRole)
用户A ->> QChat 实例: 此处省略其他接口调用
用户A ->> QChat 实例: 删除频道自定义身份组<br>(removeChannelRole)

创建频道自定义身份组

默认情况下，频道直接使用服务器身份组来控制权限。如有需要，可调用addChannelRole方法新增一个频道身份组，新增的频道身份组的权限配置默认继承自服务器身份组（调用时必须通过serverRoleId指定新增的频道身份组继承自哪个服务器身份组）。

调用该方法必须先拥有manageRole权限和manageChannel权限，且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。

新创建的频道身份组和被继承的服务器身份组有以下联系：

公开频道的身份组成员等于被继承的服务器身份组成员去掉频道黑名单成员和频道黑名单身份组成员；私密频道的身份组成员是同时存在于频道白名单和被继承的服务器身份组的公共成员。
刚创建时两者权限一样。频道身份组刚创建时所有权限配置都为继承（inherit），因此实际权限和被继承的服务器身份组一样，之后可以调用updateChannelRole方法手动修改，使频道身份组和服务器身份组拥有不一样的权限。
频道身份组的parentRoleId等于被继承的服务器身份组的roleId。

频道身份组继承逻辑.png

示例代码

dartfinal param = QChatAddChannelRoleParam(serverId,roleId,channelId);
NimCore.instance.qChatRoleService.addChannelRole(param).then((value) {
  if (value.isSuccess) {
    // 操作成功,返回Channel身份组信息
    var  channelRole = value.data.role;
  } else {
    // 操作失败
  }
});

修改频道自定义身份组

调用updateChannelRole方法可修改频道自定义身份组的权限配置。

该方法的入参结构为QChatUpdateChannelRoleParam，需要传入频道身份组所属的服务器 ID、频道 ID、频道身份组 ID 和待更新的权限 Map。

调用该方法必须先拥有manageRole权限和manageChannel权限，且必须是该频道的成员。如果没有权限，调用该方法将返回 403 错误码。
用户无法配置自己没有的权限。例如用户没有权限A，则无法修改权限A 的配置。
用户无法将自己拥有的某个权限在全部所属身份组中都设置为关闭（deny）。例如用户属于 10 个身份组且这 10 个身份组都开启了权限A，那么用户最多可以将其中 9 个身份组的权限A 设置为deny。

示例代码如下：

dartfinal param = QChatUpdateChannelRoleParam(serverId, channelId, roleId,
                                           {QChatRoleResource.deleteMsg: 
                                            QChatRoleOption.allow});
NimCore.instance.qChatRoleService.updateChannelRole(param).then((value) {
  if (value.isSuccess) {
    // 操作成功,返回修改后的Channel身份组信息
    var channelRole = value.data?.role;
  } else {
    // 操作失败
  }
});

删除频道身份组

调用 removeChannelRole可删除频道身份组。