# 频道 QGGuild

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

## API模块中的Guild

API模块中部分用于获取频道信息的API中会返回一些与 `Guild` 相关的数据类型。

当你使用 `GetGuildApi` 或 `GetBotGuildListApi` 时， 返回值类型分别为 `SimpleGuild` 和 `List<SimpleGuild>`。

## Stdlib模块中的Guild

> **Warning:**
> 标准库模块可能会在未来被弃用并移除。 前往议题 [#168](https://github.com/simple-robot/simbot-component-qq-guild/issues/168) 了解更多。

除了使用API主动查询、获取以外， 你还可能在stdlib模块下订阅与Guild相关的事件时获取到它。

当你订阅 `EventGuildDispatch` 或它的子类型事件 `GuildCreate`、`GuildUpdate`、`GuildDelete` 时，可以通过 `data` 获取到 `EventGuild`。

Kotlin:

```KOTLIN
bot.subscribe<GuildCreate> {
    val guild: EventGuild = data
}
```

Java:

```JAVA
bot.subscribe(EventProcessors.async(GuildCreate.class, (event, raw) -> {
    EventGuild guild = event.getData();
    // ...
    return CompletableFuture.completedFuture(null);
}));
```

```JAVA
bot.subscribe(EventProcessors.block(GuildCreate.class, (event, raw) -> {
    EventGuild guild = event.getData();
}));
```

## 组件库中的QGGuild

在组件库模块中，QQ频道组件提供了一个针对 simbot标准API中的 `Guild` 类型的实现： `QGGuild`，它基于 stdlib模块的 `Guild` (这个不是指simbot标准API中的 `Guild`) 提供更进一步的功能。

### 得到QGGuild

你可以在 `QGBot` 中得到 `QGGuild`。 这部分可以前往参考 [频道操作](component-qq-guild-qgbot.html#qgbot-guild)。

除了直接在 `QGBot` 中获取，你也可以在与频道相关的事件中获取到它。

如果一个频道是这个事件中的主体(例如 `QGGuildCreateEvent`)， 那么你可以通过 `content` 得到 `QGGuild`。

Kotlin:

```KOTLIN
val event: QGGuildCreateEvent = ...
val guild = event.content()
```

Java:

```JAVA
QGGuildCreateEvent event = ...
event.getContentAsync()
    .thenAccept(guild -> { ... })
```

```JAVA
QGGuildCreateEvent event = ...
var guild = event.getContentBlocking() 
```

```JAVA
QGGuildCreateEvent event = ...
event.getContentReserve()
        // 例如转为 Reactor 的 `Mono`
        .transform(SuspendReserves.mono())
        .subscribe(guild -> { ... })
```

### 获取基本信息

`QGGuild` 理所当然得可以获取到一些频道服务器的基本属性， 比如id、名称、图标等。

Kotlin:

```KOTLIN
guild.id
guild.name
guild.ownerId
guild.joinTime
guild.description
guild.icon
guild.memberCount
guild.maxMembers
```

Java:

```JAVA
guild.getId();
guild.getName();
guild.getOwnerId();
guild.getJoinTime();
guild.getDescription();
guild.getIcon();
guild.getMemberCount();
guild.getMaxMembers();
```

### 获取子频道

你可以在 `QGGuild` 中获取到子频道类型 `QGChannel`。

> **Tip:**
> 更多有关子频道的信息可前往参考 [子频道 QGChannel](component-qq-guild-qgchannel.html)。
>
>
>
> 其中，更多有关论坛子类型(`Forum`)的信息可前往参考 [论坛 QGForum](component-qq-guild-qgforum.html)。

Kotlin:

寻找指定ID的子频道

```KOTLIN
val guild: QGGuild = ...
// 假设这是某个子频道的ID
val id = 1234L.ID

val channel = guild.channel(id)
val chatChannel = guild.chatChannel(id)
val forumChannel = guild.forum(id)
```

批量获取子频道

```KOTLIN
val guild: QGGuild = ...

guild.channels
    // .asFlow() // 也可以转成 Flow
    .collect { channel ->  }
    
val chatChannelList = guild.chatChannels
    .asFlow().toList()

guild.forums.collect { forum ->  }
```

Java:

寻找指定ID的子频道

```JAVA
QGGuild guild = ...
// 假设这是某个子频道的ID
var id = Identifies.of(1234L);

guild.getChannelAsync(id)
        .thenAccept(channel -> {...});

guild.getChatChannelAsync(id)
        .thenAccept(channel -> {...});

guild.getForumAsync(id)
        .thenAccept(channel -> {...});
```

```JAVA
QGGuild guild = ...
// 假设这是某个子频道的ID
var id = Identifies.of(1234L);

final var channel = guild.getChannel(id);
final var chatChannel = guild.getChatChannel(id);
final var forum = guild.getForum(id);
```

```JAVA
QGGuild guild = ...
// 假设这是某个子频道的ID
var id = Identifies.of(1234L);

guild.getChannelReserve(id)
        // 假设转化为 Reactor 的 `Mono`
        .transform(SuspendReserves.mono())
        .subscribe(channel -> {});

guild.getChatChannelReserve(id)
        // 假设转化为 Reactor 的 `Mono`
        .transform(SuspendReserves.mono())
        .subscribe(channel -> {});

guild.getForumReserve(id)
        // 假设转化为 Reactor 的 `Mono`
        .transform(SuspendReserves.mono())
        .subscribe(channel -> {});
```

批量获取子频道

```JAVA
QGGuild guild = ...

// 可以直接在异步中遍历
// 第一个参数 scope 可以选择 QGGuild、QGBot 等，
// 或者直接使用 GlobalScope
guild.getChannels().collectAsync(GlobalScope.INSTANCE, channel -> { });

// 可以使用 Collectables.collectAsync
var chatChannelsCollectable = guild.getChatChannels();
Collectables.collectAsync(chatChannelsCollectable, Collectors.toList())
        .thenAccept(chatChannelList -> {});

// 可以直接使用 Collectable的扩展
var forumsCollectable = guild.getForums();
Collectables.toListAsync(forumsCollectable);
        .thenAccept(forum -> {...});
```

```JAVA
QGGuild guild = ...

// 可以使用 SuspendReserves.list 转为 List
var channelList = guild.getChannels().transform(SuspendReserves.list());

// 可以使用 Collectables 转成 Stream 或 List
var chatChannelsCollectable = guild.getChatChannels();
Collectables.asStream(chatChannelsCollectable)
        .forEach(chatChannel -> {});

// 可以直接使用 Collectable的扩展
var forumsCollectable = guild.getForums();
var forumList = Collectables.toList(forumsCollectable);
```

```JAVA
QGGuild guild = ...
        
// 可以直接在异步中遍历
// CoroutineScope 可以选择 QGBot、QGGuild等
// 也可以选择 GlobalScope
guild.getChannels().collectAsync(GlobalScope.INSTANCE, channel -> { });

// 可以使用 Collectables 转成 Flux
var chatChannelsCollectable = guild.getChatChannels();
Collectables.asFlux(chatChannelsCollectable)
        .subscribe(chatChannel -> {});

var forumsCollectable = guild.getForums();
Collectables.asFlux(forumsCollectable)
        .subscribe(forum -> {});
```

### 获取成员

你可以在 `QGGuild` 中获取到成员类型 `QGMember`。

> **Tip:**
> 更多有关子频道的信息可前往参考 [频道成员 QGMember](component-qq-guild-qgmember.html)。

Kotlin:

寻找指定ID的成员

```KOTLIN
val guild: QGGuild = ...
// 假设这是某个成员的ID
val id = 1234L.ID

val member = guild.member(id)
```

批量获取成员

```KOTLIN
val guild: QGGuild = ...

guild.members
    // .asFlow() // 也可以转成 Flow
    .collect { member ->  }
```

Java:

寻找指定ID的成员

```JAVA
QGGuild guild = ...
// 假设这是某个成员的ID
var id = Identifies.of(1234L);

guild.getMemberAsync(id)
        .thenAccept(member -> {...});
```

```JAVA
QGGuild guild = ...
// 假设这是某个成员的ID
var id = Identifies.of(1234L);

var member = guild.getMember(id);
```

```JAVA
QGGuild guild = ...
// 假设这是某个成员的ID
var id = Identifies.of(1234L);

guild.getMemberReserve(id)
        // 假设转化为 Reactor 的 `Mono`
        .transform(SuspendReserves.mono())
        .subscribe(member -> {});
```

批量获取成员

```JAVA
QGGuild guild = ...

// 可以直接在异步中遍历
// 第一个参数 scope 可以选择 QGGuild、QGBot 等，
// 或者直接使用 GlobalScope
guild.getMembers().collectAsync(GlobalScope.INSTANCE, member -> { });

// 可以使用 Collectables.toListAsync / collectAsync
var chatChannelsCollectable = guild.members(100); // batch: 内部每次查询的批次量
Collectables.toListAsync(chatChannelsCollectable)
        .thenAccept(chatChannelList -> {});
```

```JAVA
QGGuild guild = ...

// 可以使用 SuspendReserves.list 转为 List
var memberList = guild.getMembers().transform(SuspendReserves.list());

var membersCollectable = guild.members(100); // batch: 内部每次查询的批次量
// 可以使用 Collectables 转成 Stream 或 List
Collectables.asStream(membersCollectable)
        .forEach(member -> {});
```

```JAVA
QGGuild guild = ...
        
// 可以直接在异步中遍历
// 第一个参数 scope 可以选择 QGGuild、QGBot 等，
// 或者直接使用 GlobalScope
guild.getMembers().collectAsync(GlobalScope.INSTANCE, member -> { });

var membersCollectable = guild.members(100); // batch: 内部每次查询的批次量
// 可以使用 Collectables 转为 Flux
Collectables.asFlux(membersCollectable)
        .subscribe(member -> {  });
```

### 获取权限

你可以在 `QGGuild` 中获取到当前频道对 bot 的权限限制信息 `ApiPermissions`。

> **Tip:**
> 更多有关频道权限的信息可前往参考 [API权限信息](component-qq-guild-apipermission.html)。

Kotlin:

```KOTLIN
val guild: QGGuild = ...

val permissions = guild.permissions()
```

Java:

```JAVA
QGGuild guild = ...

guild.getPermissionsAsync()
        .thenAccept(permissions -> {  });
```

```JAVA
QGGuild guild = ...

var permissions = guild.getPermissions();
```

```JAVA
QGGuild guild = ...

guild.getPermissionsReserve()
        .transform(SuspendReserves.mono())
        .subscribe(permissions -> {  });
```

### 操作角色

`QGGuild` 中存在一些对 `QGGuildRole` 进行获取或操作的 API。

> **Tip:**
> 更多有关子频道的信息可前往参考 [频道角色 QGRole](component-qq-guild-qgrole.html)。

#### 获取角色

你可以在 `QGGuild` 中获取到角色类型 `QGGuildRole`。

Kotlin:

批量获取角色

```KOTLIN
val guild: QGGuild = ...

guild.roles
    // .asFlow() // 也可以转成 Flow
    .collect { member ->  }
```

Java:

批量获取角色

```JAVA
QGGuild guild = ...

// 可以直接在异步中遍历
// 第一个参数 scope 可以选择 QGGuild、QGBot 等，
// 或者直接使用 GlobalScope
guild.getRoles().collectAsync(GlobalScope.INSTANCE, role -> { });

// 可以使用 Collectables.toListAsync / collectAsync
var rolesCollectable = guild.getRoles();
Collectables.toListAsync(rolesCollectable)
        .thenAccept(role -> {});
```

```JAVA
QGGuild guild = ...

// 可以使用 SuspendReserves.list 转为 List
var roleList = guild.getRoles().transform(SuspendReserves.list());

// 可以使用 Collectables 转成 Stream 或 List
var rolesCollectable = guild.getRoles();
Collectables.asStream(rolesCollectable)
        .forEach(role -> {});
```

```JAVA
QGGuild guild = ...

// 可以直接在异步中遍历
// CoroutineScope 可以选择 QGBot、QGGuild 等
// 也可以选择 GlobalScope
guild.getRoles().collectAsync(GlobalScope.INSTANCE, role -> {  });

// 可以使用 Collectables 转为 Flux
var rolesCollectable = guild.getRoles();
Collectables.asFlux(rolesCollectable)
        .subscribe(role -> {  });
```

#### 创建角色

在 `QGGuild` 中可以通过 `roleCreator` 得到一个用来创建 `QGGuildRole` 的构建器。

Kotlin:

```KOTLIN
val guild: QGGuild = ...

val creator = guild.roleCreator()
// 一些属性...
creator.name = ...
creator.isHoist = ...
creator.color = ...

// 请求API创建一个新角色
val role = creator.create()
```

Kotlin 中可以使用扩展函数 `createRole` 来简化：

```KOTLIN
val guild: QGGuild = ...

// 请求API创建一个新角色
val role = guild.createRole {
    name = ...
    isHoist = ...
    color = ...
}
```

Java:

```JAVA
QGGuild guild = ...
var creator = guild.roleCreator();

creator.setName("123");
creator.setHoist(false);
creator.setColor(0);

// 请求API创建一个新角色
creator.createAsync().thenAccept(role -> {});
```

```JAVA
QGGuild guild = ...
var creator = guild.roleCreator();

creator.setName("123");
creator.setHoist(false);
creator.setColor(0);

// 请求API创建一个新角色
var role = creator.createBlocking();
```

```JAVA
QGGuild guild = ...
var creator = guild.roleCreator();

creator.setName("123");
creator.setHoist(false);
creator.setColor(0);

// 请求API创建一个新角色
creator.createReserve()
        .transform(SuspendReserves.mono())
        .subscribe(role -> {});
```