From 034a4a1431b9630b073fc221acadaba9c68d2de2 Mon Sep 17 00:00:00 2001 From: ForteScarlet Date: Sat, 9 Mar 2024 20:33:53 +0800 Subject: [PATCH] =?UTF-8?q?doc:=20=E9=83=A8=E5=88=86=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Writerside/topics/QGBot.md | 11 +- Writerside/topics/QGChannel.md | 200 +++++++++++++++++- Writerside/topics/QGGuild.md | 2 +- Writerside/topics/QGMember.md | 8 +- Writerside/topics/messages.md | 6 +- Writerside/topics/role/api_role.md | 6 + .../component/qguild/channel/QGCategory.kt | 8 +- 7 files changed, 226 insertions(+), 15 deletions(-) diff --git a/Writerside/topics/QGBot.md b/Writerside/topics/QGBot.md index a7c6e4b7..019a55d4 100644 --- a/Writerside/topics/QGBot.md +++ b/Writerside/topics/QGBot.md @@ -820,7 +820,9 @@ bot.sendTo("channel id".ID, "消息内容".toText() + At("user id".ID)) ``` - + + + ```Java QGBot bot = ... @@ -861,8 +863,9 @@ return CompletableFuture.allOf(sendTask1, sendTask2) .thenApply($ -> EventResult.empty()); // 任务全部完成后，返回事件结果 ``` - - + + + ```Java QGBot bot = ... @@ -874,6 +877,8 @@ bot.sendToBlocking(Identifies.of("channel id"), Messages.of( )); ``` + + diff --git a/Writerside/topics/QGChannel.md b/Writerside/topics/QGChannel.md index d5f77cf2..ee0dbbcb 100644 --- a/Writerside/topics/QGChannel.md +++ b/Writerside/topics/QGChannel.md @@ -1,11 +1,205 @@ +--- +switcher-label: Java API 风格 +--- + + + # 子频道 QGChannel -TODO +子频道，即 `Channel`，存在于频道服务器(`Guild`)中， +有多种类型，例如文字子频道、论坛子频道等。 + +> 有关**论坛子频道**可前往参考 +> ， +> 本章节不过多讨论。 + +## API中的子频道 {id="api-channels"} + +万物起源于API。你在API模块中会遇到一些用来获取、操作子频道相关的API。 + +比如你可以通过 `GetGuildChannelListApi` 获取频道服务器的子频道列表、 +`GetChannelApi` 获取某个频道的详情。它们分别返回 `List` +和 `SimpleChannel`。 + +> 详细的API列表请参考 +> +> 或 [API文档](%api-doc%)。 + +## Stdlib模块中的子频道 {id="stdlib-channels"} + +当你直接使用标准库模块时，你可以在一些与子频道相关的事件中得到它的信息。 + +比如当你处理 `ChannelDispatch` 或其子类型的事件时，可以通过 `data` 获取到 `EventChannel`。 +以 `ChannelCreate` 为例： + + + + +```Kotlin +bot.process { + val channel: EventChannel = data +} +``` + + + + +```Java +bot.subscribe(EventProcessors.async(ChannelCreate.class, (event, raw) -> { + var channel = event.getData(); + // ... + return CompletableFuture.completedFuture(null); +})); +``` +{switcher-key="%ja%"} + +```Java +bot.subscribe(EventProcessors.block(ChannelCreate.class, (event, raw) -> { + var channel = event.getData(); +})); +``` +{switcher-key="%jb%"} + + + + ## 组件库中的子频道 {id="component-channels"} -## QGForumChannel +组件库模块中，`QGChannel` 类型即为实现了simbot标准API中 `Channel` 类型的实现类型。 +它基于stdlib模块的 `Channel` (这个不是指simbot标准API中的 `Channel`) +提供更进一步的功能。 + +## 获取子频道 {id="get-channels"} + +如果你想要获取一个 `QGChannel`，你可以在 `QGBot`、`QGGuild` 或一个与子频道相关的事件中获取。 + +在 `QGBot` 中获取子频道你可以前往参考 +。 + +在 `QGGuild` 中获取子频道你可以前往参考 +。 + +在事件中获取，那么这个事件应当与**子频道有所关联**。 +以 `QGChannelCreateEvent` 事件为例： + + + + +```Kotlin +val event: QGChannelCreateEvent = ... +val channel = event.content() +``` + + + + +```Java +QGChannelCreateEvent event = ... +event.getContentAsync() + .thenAccept(channel -> { ... }) +``` +{switcher-key='%ja%'} + +```Java +QGChannelCreateEvent event = ... +var channel = event.getContentBlocking() +``` +{switcher-key='%jb%'} + +```Java +QGChannelCreateEvent event = ... +event.getContentReserve() + // 例如转为 Reactor 的 `Mono` + .transform(SuspendReserves.mono()) + .subscribe(channel -> { ... }) +``` +{switcher-key='%jr%'} + + + + +## 子频道类型 {id='channel-types'} + +在QQ频道中，一个子频道可能有多个不同的类型，例如文字、论坛、分组等等。 +而在这里面只有使用**文字子频道**才能够发送消息。 + +因此 `QGChannl` 进一步差分为了两个子类型： + +- `QGTextChannel` +- `QGNonTextChannel` + +顾名思义，它们分别表示自己是否为一个文字子频道。 + +### QGTextChannel + +如果子频道是文字子频道，那么它在实现simbot标准API的 `Channel` 之上， +额外实现了 `ChatChannel` 接口，即表示一个聊天子频道，可用于发送消息。 + + + + +```Kotlin +val channel: QGTextChannel = ... +channel.send("消息内容") +channel.send("消息内容".toText() + At("user id".ID)) +``` + + + + +```Java +QGTextChannel channel = ... + +var sendTask1 = channel.sendAsync("消息内容"); +var sendTask2 = channel.sendAsync(Messages.of( + Text.of("文本消息"), + At.of(Identifies.of("user id")) +)); +``` + + + + +```Java +QGTextChannel channel = ... + +channel.sendBlocking("消息内容"); +channel.sendBlocking(Messages.of( + Text.of("文本消息"), + At.of(Identifies.of("user id")) +)); +``` + + + + +```Java +QGTextChannel channel = ... + +channel.sendReserve("消息内容") + .transform(SuspendReserves.mono()) + .subscribe(receipt -> { ... }); + +channel.sendReserve(Messages.of( + Text.of("文本消息"), + At.of(Identifies.of("user id")) + )).transform(SuspendReserves.mono()) + .subscribe(receipt -> { ... }); +``` + + + + +### QGForumChannel + +有关论坛子频道的内容可前往参考 +。 + +### QGCategoryChannel +用来表示一个类型为“分类”的子频道。 -## QGTextChannel +### QGNonTextChannel +其他没有特殊实现类型的子频道 (比如语音子频道等) 均会使用 `QGNonTextChannel`。 diff --git a/Writerside/topics/QGGuild.md b/Writerside/topics/QGGuild.md index d8122c1d..41279332 100644 --- a/Writerside/topics/QGGuild.md +++ b/Writerside/topics/QGGuild.md @@ -96,7 +96,7 @@ var guild = event.getContentBlocking() ```Java QGGuildCreateEvent event = ... -var guild = event.getContentReserve() +event.getContentReserve() // 例如转为 Reactor 的 `Mono` .transform(SuspendReserves.mono()) .subscribe(guild -> { ... }) diff --git a/Writerside/topics/QGMember.md b/Writerside/topics/QGMember.md index c963ed1d..c4f4cda8 100644 --- a/Writerside/topics/QGMember.md +++ b/Writerside/topics/QGMember.md @@ -1,3 +1,9 @@ +--- +switcher-label: Java API 风格 +--- + + + # 频道成员 QGMember -Start typing here... \ No newline at end of file +Start typing here... diff --git a/Writerside/topics/messages.md b/Writerside/topics/messages.md index 341b3965..617b8d07 100644 --- a/Writerside/topics/messages.md +++ b/Writerside/topics/messages.md @@ -7,7 +7,7 @@ -## 消息元素实现 +## 消息元素实现 {id='message-impl'} 所有的 `Message.Element` 特殊实现类型均定义在包 `love.forte.simbot.component.qguild.message` 中。 @@ -17,8 +17,6 @@ 对 API 模块中 Ark 消息的包装体，可用来发送 Ark 消息。 对 API 模块中 Embed 消息的包装体，可用来发送 Embed 消息。 -TODO Message type -TODO Message type 发送消息时，QQ频道的消息引用。与官方发送消息API中的 `reference` 对应。 @@ -33,7 +31,7 @@ -## 使用消息元素 +## 使用/发送消息元素 {id='message-usage'} 在simbot中，使用组件的消息元素与使用其他消息元素别无二致。 diff --git a/Writerside/topics/role/api_role.md b/Writerside/topics/role/api_role.md index 5aa44e7e..b44ccd9a 100644 --- a/Writerside/topics/role/api_role.md +++ b/Writerside/topics/role/api_role.md @@ -1,3 +1,9 @@ +--- +switcher-label: Java API 风格 +--- + + + # 角色 QGRole QQ频道中有一些针对 `角色` 的API。 diff --git a/simbot-component-qq-guild-core/src/commonMain/kotlin/love/forte/simbot/component/qguild/channel/QGCategory.kt b/simbot-component-qq-guild-core/src/commonMain/kotlin/love/forte/simbot/component/qguild/channel/QGCategory.kt index 5389a3d2..bf3c861a 100644 --- a/simbot-component-qq-guild-core/src/commonMain/kotlin/love/forte/simbot/component/qguild/channel/QGCategory.kt +++ b/simbot-component-qq-guild-core/src/commonMain/kotlin/love/forte/simbot/component/qguild/channel/QGCategory.kt @@ -18,6 +18,7 @@ package love.forte.simbot.component.qguild.channel import love.forte.simbot.common.id.ID +import love.forte.simbot.component.qguild.guild.QGGuild import love.forte.simbot.definition.Category import love.forte.simbot.qguild.QQGuildApiException import love.forte.simbot.qguild.model.Channel @@ -53,9 +54,10 @@ public interface QGCategory : Category { override val id: ID /** - * 当前子频道分组ID。分组信息未初始化时，值同 [id]。 - * 如果需要获取真正的名称，判断当前类型是否为 [QGCategory] - * 或直接通过 [resolveToChannel] 实时查询新的结果。 + * 当前子频道分组的名称。会通过 [resolveToChannel] + * 获取子频道信息后返回名称。 + * + * @see resolveToChannel */ @STP override suspend fun name(): String?