mirror of
https://github.com/mamoe/mirai.git
synced 2024-12-27 09:00:15 +08:00
Update docs
This commit is contained in:
Him188
parent
b18c857e5b
commit
b989bce52b
@ -126,7 +126,7 @@ mirai 是一个在全平台下运行，提供 QQ Android 协议支持的高效
|
||||
> *除这两个途径外，Mirai 在各个平台均没有官方交流群或论坛*
|
||||
|
||||
- mirai 官方系列项目: [project-mirai](https://github.com/project-mirai)
|
||||
- mirai 社区相关项目: [awesome-mirai](https://github.com/project-mirai/awsome-mirai/blob/master/README.md) ****
|
||||
- mirai 社区相关项目: [awesome-mirai](https://github.com/project-mirai/awsome-mirai/blob/master/README.md)
|
||||
|
||||
- 帮助 mirai: [CONTRIBUTING](CONTRIBUTING.md)
|
||||
|
||||
|
||||
157
docs/Messages.md
157
docs/Messages.md
@ -4,7 +4,6 @@
|
||||
- [消息系统](#消息系统)
|
||||
- [消息类型](#消息类型)
|
||||
- [消息元素](#消息元素)
|
||||
- [Mirai 码](#mirai-码)
|
||||
- [转义规则](#转义规则)
|
||||
- [消息链的 mirai 码](#消息链的-mirai-码)
|
||||
- [由 `CodableMessage` 取得 mirai 码字符串](#由-codablemessage-取得-mirai-码字符串)
|
||||
@ -14,6 +13,7 @@
|
||||
- [构造消息链](#构造消息链)
|
||||
- [元素唯一性](#元素唯一性)
|
||||
- [获取消息链中的消息元素](#获取消息链中的消息元素)
|
||||
- [Mirai 码](#mirai-码)
|
||||
|
||||
## 消息系统
|
||||
|
||||
@ -36,7 +36,17 @@
|
||||
|
||||
## 消息元素
|
||||
|
||||
Mirai 支持富文本消息。各类型消息元素如下文表格所示。
|
||||
Mirai 支持富文本消息。
|
||||
|
||||
消息拥有三种转换到字符串的表示方式。
|
||||
|
||||
| 方法 | 解释 |
|
||||
|:-------------------------|:---------------------------------------------------------------------------------------------|
|
||||
| `serializeToMiraiCode()` | 对应的 Mirai 码. 消息的一种序列化方式，格式为 `[mirai:TYPE:PROP]`，其中 `TYPE` 为消息类型, `PROP` 为属性 |
|
||||
| `contentToSting()` | QQ 对话框中以纯文本方式会显示的消息内容。无法用纯文字表示的消息会丢失信息，如任何图片都是 `[图片]` |
|
||||
| `toString()` | Java 对象的 `toString()`，会尽可能包含多的信息用于调试作用，**行为可能不确定** |
|
||||
|
||||
各类型消息元素及其 `contentToString()` 如下表格所示。
|
||||
|
||||
[`PlainText`]: ../mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt
|
||||
[`At`]: ../mirai-core-api/src/commonMain/kotlin/message/data/At.kt
|
||||
@ -73,85 +83,17 @@ Mirai 支持富文本消息。各类型消息元素如下文表格所示。
|
||||
| [`ForwardMessage`] | ... | 合并转发 | *`[转发消息]` |
|
||||
| [`SimpleServiceMessage`] | `serviceId: Int, content: String` | （不稳定）服务消息 | `$content` |
|
||||
|
||||
***注意：内容会首先被转义，详见 [转义规则](#转义规则)***
|
||||
|
||||
**请打开相关消息类型的源码查看用法。**
|
||||
|
||||
> 回到 [目录](#目录)
|
||||
|
||||
## Mirai 码
|
||||
|
||||
消息拥有三种转换到字符串的表示方式。
|
||||
- `serializeToMiraiCode()`: 消息的一种序列化方式，格式为 `[mirai:TYPE:PROP]`，其中 `TYPE` 为消息类型, `PROP` 为属性。
|
||||
- `contentToSting()`: QQ 对话框中以纯文本方式会显示的消息内容。无法用纯文字表示的消息会丢失信息，如图片总是 `[图片]`。
|
||||
- `toString()`: Java 对象的 `toString()`，会尽可能包含多的信息用于调试作用，**行为可能不确定**。
|
||||
|
||||
实现了接口 `CodableMessage` 的消息类型支持 mirai 码表示。
|
||||
|
||||
### 转义规则
|
||||
|
||||
mirai 码内的属性字符串会被转义。
|
||||
|
||||
| 原字符 | 转义结果字符 |
|
||||
|:----------:|:---------:|
|
||||
| `[` | `\[` |
|
||||
| `]` | `\]` |
|
||||
| `:` | `\:` |
|
||||
| `,` | `\,` |
|
||||
| `\` | `\\` |
|
||||
| *换行符 \n* | `\n` |
|
||||
| *换行符 \r* | `\r` |
|
||||
|
||||
### 消息链的 mirai 码
|
||||
|
||||
消息链 [`MessageChain`] 是多个 [`SingleMessage`] 的集合。[`MessageChain`] 也实现 [`CodableMessage`]。在转换为 mirai 码时所有 [`CodableMessage`] 直接相连：
|
||||
```
|
||||
val chain = messageChainOf(PlainText("plain"), At(123), AtAll)
|
||||
|
||||
chain.serializeToMiraiCode() // "plain[mirai:at:123][mirai:atall]"
|
||||
```
|
||||
|
||||
### 由 `CodableMessage` 取得 mirai 码字符串
|
||||
|
||||
通过 `CodableMessage.serializeToMiraiCode()`。
|
||||
|
||||
```
|
||||
val at = At(123)
|
||||
|
||||
at.serializeToMiraiCode() // 结果为 `[mirai:at:123]`
|
||||
```
|
||||
|
||||
| 消息类型 | `serializeToMiraiCode()` |
|
||||
|:------------------------:|:-------------------------------------------------|
|
||||
| [`PlainText`] | `$content` |
|
||||
| [`Image`] | `[mirai:image:$imageId]` |
|
||||
| [`At`] | `[mirai:at:$target]` |
|
||||
| [`AtAll`] | `[mirai:atall]` |
|
||||
| [`Face`] | `[mirai:face:id]` |
|
||||
| [`FlashImage`] | `[mirai:flash:${image.imageId}]` |
|
||||
| [`PokeMessage`] | `[mirai:poke:$name,$pokeType,$id]` |
|
||||
| [`VipFace`] | `[mirai:vipface:${kind.id},${kind.name},$count]` |
|
||||
| [`LightApp`] | `[mirai:app:$content]` |
|
||||
| [`SimpleServiceMessage`] | `[mirai:service:$serviceId,$content]` |
|
||||
|
||||
### 由 mirai 码字符串取得 `MessageChain` 实例
|
||||
|
||||
```kotlin
|
||||
val chain = "[mirai:atall]".parseMiraiCode()
|
||||
```
|
||||
```java
|
||||
MessageChain chain = MiraiCode.parseMiraiCode("[mirai:atall]");
|
||||
```
|
||||
|
||||
> 回到 [目录](#目录)
|
||||
|
||||
## 消息链
|
||||
|
||||
[`MessageChain`]: ../mirai-core-api/src/commonMain/kotlin/message/data/MessageChain.kt
|
||||
[`SingleMessage`]: ../mirai-core-api/src/commonMain/kotlin/message/data/Message.kt
|
||||
[`CodableMessage`]: ../mirai-core-api/src/commonMain/kotlin/message/code/CodableMessage.kt
|
||||
|
||||
前文已经介绍消息链，这里介绍消息链的使用。
|
||||
前文已经介绍消息链，这里简略介绍消息链的使用。详细的使用请查看源码内注释。
|
||||
|
||||
### 发送消息
|
||||
|
||||
@ -184,10 +126,10 @@ contact.sendMessage(new PlainText("你要的图片是：").plus(Image.fromId("/f
|
||||
|
||||
| 定义 |
|
||||
|:--------------------------------------------------------|
|
||||
| `fun Iterable<Messaged>.asMessageChain(): MessageChain` |
|
||||
| `fun Sequence<Messaged>.asMessageChain(): MessageChain` |
|
||||
| `fun Array<Message>.asMessageChain(): MessageChain` |
|
||||
| `fun Message.asMessageChain(): MessageChain` |
|
||||
| `fun Iterable<Messaged>.toMessageChain(): MessageChain` |
|
||||
| `fun Sequence<Messaged>.toMessageChain(): MessageChain` |
|
||||
| `fun Array<Message>.toMessageChain(): MessageChain` |
|
||||
| `fun Message.toMessageChain(): MessageChain` |
|
||||
| `fun messageChainOf(vararg Message): MessageChain` |
|
||||
| `fun Message.plus(tail: Message): MessageChain` |
|
||||
|
||||
@ -304,6 +246,71 @@ val image: Image? by chain.orNull()
|
||||
val image: Image? by chain.orElse { /* 返回一个 Image */ }
|
||||
```
|
||||
|
||||
### 序列化
|
||||
|
||||
消息可以序列化为 JSON 字符串，使用 `MessageChain.serializeToJsonString` 和 `MessageChain.deserializeFromJsonString`。
|
||||
|
||||
## Mirai 码
|
||||
|
||||
实现了接口 `CodableMessage` 的消息类型支持 mirai 码表示。
|
||||
|
||||
### 转义规则
|
||||
|
||||
mirai 码内的属性字符串会被转义。
|
||||
|
||||
| 原字符 | 转义结果字符 |
|
||||
|:----------:|:---------:|
|
||||
| `[` | `\[` |
|
||||
| `]` | `\]` |
|
||||
| `:` | `\:` |
|
||||
| `,` | `\,` |
|
||||
| `\` | `\\` |
|
||||
| *换行符 \n* | `\n` |
|
||||
| *换行符 \r* | `\r` |
|
||||
|
||||
### 消息链的 mirai 码
|
||||
|
||||
消息链 [`MessageChain`] 是多个 [`SingleMessage`] 的集合。[`MessageChain`] 也实现 [`CodableMessage`]。在转换为 mirai 码时所有 [`CodableMessage`] 直接相连：
|
||||
```
|
||||
val chain = messageChainOf(PlainText("plain"), At(123), AtAll)
|
||||
|
||||
chain.serializeToMiraiCode() // "plain[mirai:at:123][mirai:atall]"
|
||||
```
|
||||
|
||||
### 由 `CodableMessage` 取得 mirai 码字符串
|
||||
|
||||
通过 `CodableMessage.serializeToMiraiCode()`。
|
||||
|
||||
```
|
||||
val at = At(123)
|
||||
|
||||
at.serializeToMiraiCode() // 结果为 `[mirai:at:123]`
|
||||
```
|
||||
|
||||
| 消息类型 | `serializeToMiraiCode()` |
|
||||
|:------------------------:|:-------------------------------------------------|
|
||||
| [`PlainText`] | `$content` |
|
||||
| [`Image`] | `[mirai:image:$imageId]` |
|
||||
| [`At`] | `[mirai:at:$target]` |
|
||||
| [`AtAll`] | `[mirai:atall]` |
|
||||
| [`Face`] | `[mirai:face:id]` |
|
||||
| [`FlashImage`] | `[mirai:flash:${image.imageId}]` |
|
||||
| [`PokeMessage`] | `[mirai:poke:$name,$pokeType,$id]` |
|
||||
| [`VipFace`] | `[mirai:vipface:${kind.id},${kind.name},$count]` |
|
||||
| [`LightApp`] | `[mirai:app:$content]` |
|
||||
| [`SimpleServiceMessage`] | `[mirai:service:$serviceId,$content]` |
|
||||
|
||||
### 由 mirai 码字符串取得 `MessageChain` 实例
|
||||
|
||||
```kotlin
|
||||
val chain = "[mirai:atall]".deserializeMiraiCode()
|
||||
```
|
||||
```java
|
||||
MessageChain chain = MiraiCode.deserializeFromMiraiCode("[mirai:atall]");
|
||||
```
|
||||
|
||||
> 回到 [目录](#目录)
|
||||
|
||||
|
||||
> 回到 [目录](#目录)
|
||||
>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user