Simple Robot v4.14.0 Help

频道角色 QGRole

QQ频道中有一些针对 角色 的API。

API中的角色

在API模块中存在一些用来获取 Role 的API。

比如你可以通过 GetGuildRoleListApi 获取一个频道服务器中的角色列表。

组件库中的角色

在组件库模块中， QGRole 实现了simbot标准API中的 Role， 并提供了一些高级功能的封装。

QGRole的类型

QGRole 有两个子类型，用于在不同的场景下描述角色信息：

类型

描述

QGGuildRole

表示一个频道服务器中的角色

QGMemberRole

表示某个频道成员拥有的角色

根据不同的类型，部分API会产生的效果也不同。

获取QGRole

在 QGGuild 中，你可以通过属性 roles 获取到频道服务器中定义的所有 QGGuildRole。

在 QGMember 中，你可以通过属性 roles 获取这个成员所拥有的所有 QGMemberRole。

在 QGMemberRole 中，会额外提供一些属性来获取到它所属的成员ID和对应的 QGGuildRole 实例本身。

val memberRole: QGMemberRole = ... memberRole.memberId // 此角色所属的成员ID memberRole.guildRole // 此角色所实际代表的频道角色
QGMemberRole memberRole = ... memberRole.getMemberId(); // 此角色所属的成员ID memberRole.getGuildRole(); // 此角色所实际代表的频道角色

创建QGRole

创建QGGuildRole

在 QGGuild 中提供了一个API roleCreator 可以创建一个用于新建 QGGuildRole 的构建器。 前往 创建角色 参考代码示例。

创建QGMemberRole

实际上 QGMemberRole 作为一个"频道成员拥有的角色"，与其说创建， 不如说是 "赋予"："赋予"一个角色给成员，并由此诞生 QGMemberRole。

想要赋予给用户一个角色，首先你得先拥有一个 QGGuildRole。 QGGuildRole 中提供了用于赋予角色的 API grantTo(...)。

赋予需要一个参数来代表目标成员，它可以是 QGMember、 Member 或 ID， 它们的可靠性依次递减 (类型越宽泛，越可能存在类型校验等异常)。

下面的示例中会以 QGGuildRole 和 QGMember 为例。

val role: QGGuildRole = ... val member: QGMember = ... // 将角色赋予目标成员，得到 QGMemberRole 结果 val memberRole: QGMemberRole = role.grantTo(member)
QGGuildRole role = ... QGMember member = ... // 将角色赋予目标成员，得到 QGMemberRole 结果 role.grantToAsync(member) .thenAccept(memberRole -> {});
QGGuildRole role = ... QGMember member = ... // 将角色赋予目标成员，得到 QGMemberRole 结果 QGMemberRole memberRole = role.grantToBlocking(member);
QGGuildRole role = ... QGMember member = ... // 将角色赋予目标成员，得到 QGMemberRole 结果 role.grantToReserve(member) .transform(SuspendReserves.mono()) .subscribe(memberRole -> {});

删除角色/移除角色授权

QGGuildRole 和 QGMemberRole 各自实现了 DeleteSupport ，因此它们支持 delete 操作。 根据它们的类型， delete 具有不同的含义：

类型

含义

QGGuildRole.delete(...)

删除这个频道中的角色

QGMemberRole.delete(...)

取消这个成员的角色(移除权限)

val role: QGGuildRole = ... // 删除这个角色 role.delete()
QGGuildRole role = ... // 删除这个角色 role.deleteAsync() .thenAccept(unit -> { });
QGGuildRole role = ... // 删除这个角色 role.deleteBlocking();
QGGuildRole role = ... // 删除这个角色 role.deleteReserve() .transform(SuspendReserves.mono()) .subscribe(unit -> { });
val role: QGMemberRole = ... // 取消此角色对其对应用户的授权 role.delete()
QGMemberRole role = ... // 取消此角色对其对应用户的授权 role.deleteAsync() .thenAccept(unit -> { });
QGMemberRole role = ... // 取消此角色对其对应用户的授权 role.deleteBlocking();
QGMemberRole role = ... // 取消此角色对其对应用户的授权 role.deleteReserve() .transform(SuspendReserves.mono()) .subscribe(unit -> { });
20 September 2025
频道成员 QGMember论坛 QGForum