From f053c4cfc03e9add7cecf615b321b259f0f4b6e9 Mon Sep 17 00:00:00 2001 From: Him188 Date: Mon, 11 Jan 2021 22:49:10 +0800 Subject: [PATCH] Improve buildMessageSource and update docs --- docs/Messages.md | 2 +- .../src/commonMain/kotlin/IMirai.kt | 4 +- .../kotlin/message/data/MessageSource.kt | 24 ++++-- .../message/data/MessageSourceBuilder.kt | 85 ++++++++++++------- .../kotlin/message/data/PlainText.kt | 9 +- 5 files changed, 82 insertions(+), 42 deletions(-) diff --git a/docs/Messages.md b/docs/Messages.md index 7f38276cd..686e158ca 100644 --- a/docs/Messages.md +++ b/docs/Messages.md @@ -38,7 +38,7 @@ Mirai 支持富文本消息。各类型消息元素如下文表格所示。 -[`PlainText`]: ../mirai-core-api/src/commonMain/kotlin/message/data/At.kt +[`PlainText`]: ../mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt [`At`]: ../mirai-core-api/src/commonMain/kotlin/message/data/At.kt [`AtAll`]: ../mirai-core-api/src/commonMain/kotlin/message/data/AtAll.kt [`Face`]: ../mirai-core-api/src/commonMain/kotlin/message/data/Face.kt diff --git a/mirai-core-api/src/commonMain/kotlin/IMirai.kt b/mirai-core-api/src/commonMain/kotlin/IMirai.kt index ba19057fb..42381d671 100644 --- a/mirai-core-api/src/commonMain/kotlin/IMirai.kt +++ b/mirai-core-api/src/commonMain/kotlin/IMirai.kt @@ -146,7 +146,9 @@ public interface IMirai : LowLevelApiAccessor { public suspend fun queryImageUrl(bot: Bot, image: Image): String /** - * 构造一个 [OfflineMessageSource] + * 构造一个 [OfflineMessageSource]. + * + * 更推荐使用 [MessageSourceBuilder] 和 [MessageSource.copyAmend] 创建 [OfflineMessageSource]. * * @param ids 即 [MessageSource.ids] * @param internalIds 即 [MessageSource.internalIds] diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt b/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt index f56b9f40e..49ebe45cb 100644 --- a/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt +++ b/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt @@ -35,30 +35,40 @@ import net.mamoe.mirai.utils.safeCast /** * 消息源. 消息源存在于 [MessageChain] 中, 用于表示这个消息的来源, 也可以用来分辨 [MessageChain]. * - * 对于来自 [MessageEvent.message] 的 [MessageChain] - * * * ## 组成 - * [MessageSource] 由 metadata (元数据), form & target, content 组成 + * [MessageSource] 由 定位属性, 发信人和收信人, 内容 组成 * - * ### metadata + * ### 定位属性 * - [ids] 消息 ids (序列号) * - [internalIds] 消息内部 ids * - [time] 时间 * - * 官方客户端通过 metadata 这三个数据定位消息, 撤回和引用回复都是如此. + * 官方客户端通过这三个属性定位消息, 撤回和引用回复都是如此. * - * ### form & target + * ### 发信人和收信人 * - [fromId] 消息发送人 * - [targetId] 消息发送目标 * - * ### content + * ### 内容 * - [originalMessage] 消息内容 * + * ## 获取 + * - 来自 [MessageEvent.message] 的 [MessageChain] 总是包含 [MessageSource]. 可通过 [MessageChain.get] 获取 [MessageSource]: + * ``` + * val source = chain[MessageSource] + * ``` + * - 构造离线消息源 [IMirai.constructMessageSource] + * + * * ## 使用 * * 消息源可用于 [引用回复][MessageSource.quote] 或 [撤回][MessageSource.recall]. * + * 对于来自 [MessageEvent.message] 的 [MessageChain], 总是包含 [MessageSource]. + * 因此也可以对这样的 [MessageChain] 进行 [引用回复][MessageChain.quote] 或 [撤回][MessageChain.recall]. + * + * * @see IMirai.recallMessage 撤回一条消息 * @see MessageSource.quote 引用这条消息, 创建 [MessageChain] * diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/MessageSourceBuilder.kt b/mirai-core-api/src/commonMain/kotlin/message/data/MessageSourceBuilder.kt index 03124c475..dda2b57f0 100644 --- a/mirai-core-api/src/commonMain/kotlin/message/data/MessageSourceBuilder.kt +++ b/mirai-core-api/src/commonMain/kotlin/message/data/MessageSourceBuilder.kt @@ -19,7 +19,6 @@ import net.mamoe.mirai.Mirai import net.mamoe.mirai.contact.ContactOrBot import net.mamoe.mirai.message.data.MessageSource.Key.quote import net.mamoe.mirai.message.data.MessageSource.Key.recall -import net.mamoe.mirai.message.data.MessageSourceBuilder.Companion.create import net.mamoe.mirai.utils.PlannedRemoval import net.mamoe.mirai.utils.currentTimeSeconds @@ -48,9 +47,12 @@ public fun MessageSource.copyAmend( } /** - * 仅于 [copyAmend] 中修改 [MessageSource] + * [MessageSource] 复制修改器. 不会修改原 [MessageSource], 而是会创建一个新的 [MessageSource]. + * + * @see copyAmend Kotlin DSL + * @see MessageSourceBuilder */ -public class MessageSourceAmender internal constructor( +public class MessageSourceAmender public constructor( origin: MessageSource, ) : MessageSourceBuilder() { public var kind: MessageSourceKind = origin.kind @@ -77,7 +79,31 @@ public class MessageSourceAmender internal constructor( /** - * 构建一个 [OfflineMessageSource] + * 使用 DSL 构建一个 [OfflineMessageSource]. 用法参考 [MessageSourceBuilder]. + * + * @see copyAmend + */ +@JvmSynthetic +public inline fun IMirai.buildMessageSource( + botId: Long, + kind: MessageSourceKind, + block: MessageSourceBuilder.() -> Unit +): OfflineMessageSource = MessageSourceBuilder().apply(block).build(botId, kind) + +/** + * 使用 DSL 构建一个 [OfflineMessageSource]. 用法参考 [MessageSourceBuilder]. + * + * @see buildMessageSource + */ +@JvmSynthetic +public inline fun Bot.buildMessageSource( + kind: MessageSourceKind, + block: MessageSourceBuilder.() -> Unit +): OfflineMessageSource = Mirai.buildMessageSource(this.id, kind, block) + + +/** + * 离线消息源构建器. * * ### 参数 * 一个 [OfflineMessageSource] 需要以下参数: @@ -89,10 +115,11 @@ public class MessageSourceAmender internal constructor( * - 消息内容: 通过 [MessageSourceBuilder.messages] 设置 * * ### 性质 - * - 当两个消息的元数据相同时, 他们在群中会是同一条消息. 可通过此特性决定官方客户端 "定位原消息" 的目标 + * - 当两个消息的元数据相同时, 它们在群中会是同一条消息. 可通过此特性决定官方客户端 "定位原消息" 的目标 * - 发送人的信息和消息内容会在官方客户端显示在引用回复中. * * ### 实例 + * Kotlin: * ``` * bot.buildMessageSource(MessageSourceKind.GROUP) { * from(bot) @@ -105,32 +132,20 @@ public class MessageSourceAmender internal constructor( * } * ``` * - * @see copyAmend - */ -public fun IMirai.buildMessageSource( - botId: Long, - kind: MessageSourceKind, - block: MessageSourceBuilder.() -> Unit -): OfflineMessageSource = MessageSourceBuilder.create().apply(block).run { - Mirai.constructMessageSource(botId, kind, fromId, targetId, ids, time, internalIds, originalMessages.build()) -} - -/** - * 构建一个 [OfflineMessageSource] + * Java: + * ```java + * MessageSourceBuilder + * .create() + * .from(bot) + * .target(target) + * .metadata(source) // 从另一个消息源复制 ids, internalIds, time + * .messages(new PlainText("hi")) + * .build(botId, MessageSourceKind.FRIEND); + * ``` * * @see buildMessageSource */ -public fun Bot.buildMessageSource( - kind: MessageSourceKind, - block: MessageSourceBuilder.() -> Unit -): OfflineMessageSource = Mirai.buildMessageSource(this.id, kind, block) - - -/** - * @see buildMessageSource - * @see create - */ -public open class MessageSourceBuilder internal constructor() { +public open class MessageSourceBuilder public constructor() { public open var fromId: Long = 0 public open var targetId: Long = 0 @@ -235,8 +250,16 @@ public open class MessageSourceBuilder internal constructor() { public fun setSenderAndTarget(sender: ContactOrBot, target: ContactOrBot): MessageSourceBuilder = sender(sender).target(target) - public companion object { - @JvmStatic - public fun create(): MessageSourceBuilder = MessageSourceBuilder() + public fun build(botId: Long, kind: MessageSourceKind): OfflineMessageSource { + return Mirai.constructMessageSource( + botId, + kind, + fromId, + targetId, + ids, + time, + internalIds, + originalMessages.build() + ) } } \ No newline at end of file diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt b/mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt index 47a81a994..e99d4fd8b 100644 --- a/mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt +++ b/mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt @@ -20,13 +20,18 @@ import net.mamoe.mirai.message.code.internal.appendStringAsMiraiCode import net.mamoe.mirai.utils.MiraiExperimentalApi /** - * 纯文本. 可含 emoji 表情如 😊. + * 纯文本. * - * 一般不需要主动构造 [PlainText], [Message] 可直接与 [String] 相加. Java 用户请使用 [Message.plus] + * 使用时直接构造即可. [Message] 也可以直接与 [String] 相加, 详见 [Message.plus]. + * + * @see String.toPlainText */ @Serializable @SerialName(PlainText.SERIAL_NAME) public data class PlainText( + /** + * 消息内容 + */ public val content: String ) : MessageContent, CodableMessage { @Suppress("unused")