# 频道角色 QGRole

> For the complete documentation index, see [llms.txt](https://simbot.forte.love/v4/llms.txt).

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

## API中的角色

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

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

> **Tip:**
> 详细的API列表请参考 [API定义列表](component-qq-guild-api-list.html) 或 [API文档](https://docs.simbot.forte.love)。

## 组件库中的角色

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

> **Tip:**
> 你可以通过属性 `QGRole.source` 得到API模块中定义的原始 `Role` 类型。

### QGRole的类型

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

| 类型 | 描述 |
| --- | --- |
| `QGGuildRole` | 表示一个频道服务器中的角色 |
| `QGMemberRole` | 表示某个频道成员拥有的角色 |

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

### 获取QGRole

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

> **Tip:**
> 有关 `QGGuild` 获取角色，前往参考 [获取角色](component-qq-guild-qgguild.html#get-roles)。

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

> **Tip:**
> 有关 `QGMember` 获取角色，前往参考 [获取角色](component-qq-guild-qgmember.html#get-roles)。

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

Kotlin:

```KOTLIN
val memberRole: QGMemberRole = ...
memberRole.memberId  // 此角色所属的成员ID
memberRole.guildRole // 此角色所实际代表的频道角色 
```

Java:

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

### 创建QGRole

#### 创建QGGuildRole

在 `QGGuild` 中提供了一个API `roleCreator` 可以创建一个用于新建 `QGGuildRole` 的构建器。 前往 [创建角色](component-qq-guild-qgguild.html#create-role) 参考代码示例。

#### 创建QGMemberRole

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

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

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

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

Kotlin:

```KOTLIN
val role: QGGuildRole = ...
val member: QGMember = ...
// 将角色赋予目标成员，得到 QGMemberRole 结果
val memberRole: QGMemberRole = role.grantTo(member)
```

Java:

```JAVA
QGGuildRole role = ...
QGMember member = ...
// 将角色赋予目标成员，得到 QGMemberRole 结果
role.grantToAsync(member)
        .thenAccept(memberRole -> {});
```

```JAVA
QGGuildRole role = ...
QGMember member = ...
// 将角色赋予目标成员，得到 QGMemberRole 结果
QGMemberRole memberRole = role.grantToBlocking(member);
```

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

> **Tip: 子频道管理员**
> 如果角色是 子频道管理员(id=5)， 那么在赋予的时候需要额外的一个 `channelId` 参数来指定一个子频道。

### 删除角色/移除角色授权

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

| 类型 | 含义 |
| --- | --- |
| `QGGuildRole.delete(...)` | 删除这个频道中的角色 |
| `QGMemberRole.delete(...)` | 取消这个成员的角色(移除权限) |

QGGuildRole:

Kotlin:

```KOTLIN
val role: QGGuildRole = ...
// 删除这个角色
role.delete()
```

Java:

```JAVA
QGGuildRole role = ...
// 删除这个角色
role.deleteAsync()
        .thenAccept(unit -> {  });
```

```JAVA
QGGuildRole role = ...
// 删除这个角色
role.deleteBlocking();
```

```JAVA
QGGuildRole role = ...
// 删除这个角色
role.deleteReserve()
        .transform(SuspendReserves.mono())
        .subscribe(unit -> {  });
```

QGMemberRole:

Kotlin:

```KOTLIN
val role: QGMemberRole = ...
// 取消此角色对其对应用户的授权
role.delete()
```

Java:

```JAVA
QGMemberRole role = ...
// 取消此角色对其对应用户的授权
role.deleteAsync()
        .thenAccept(unit -> {  });
```

```JAVA
QGMemberRole role = ...
// 取消此角色对其对应用户的授权
role.deleteBlocking();
```

```JAVA
QGMemberRole role = ...
// 取消此角色对其对应用户的授权
role.deleteReserve()
        .transform(SuspendReserves.mono())
        .subscribe(unit -> {  });
```