# 消息

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

## 标准消息元素

作为一个simbot组件，OneBot组件理所当然的会支持部分simbot核心库所定义的标准消息元素。

Text
: 纯文本消息。

At
: At某人。

AtAll
: At全体。

Face
: 一个表情。

Image
: 图片类型的接口类型。
:
: 发送时可以使用simbot标准API中的 `Image` 实现类型， 例如 `OfflineImage` 的某个实现。
:
:
:
: > **Warning: 本地图片与base64**
: > 参考 [OneBotImage](#OneBotImage) 的说明， 如果发送本地图片文件，那么这里面有些注意事项需要你留意。
: >
: >
: >
: > 因为默认情况下，你直接发送 `FileResource`、`PathResource` 或其他可以表示本地文件的资源时，会优先默认直接使用它们的 绝对路径 而不是转化为 `base64`。如果你的OneBot服务端并非本地服务， 那么便会产生问题。

## 消息段

在OneBot组件中，我们选择使用消息段的方式进行消息交互。 除了直接使用部分上述的simbot标准消息元素以外， 我们还提供了OneBot11协议中定义的所有消息段类型的实现。

当想要发送它们的时候，我们统一使用 `OneBotMessageSegmentElement` 对其进行包装， 表示这是一个OneBot的消息段元素。

Kotlin:

```KOTLIN
val segment = ...
val element = segment.toElement()
```

Java:

```JAVA
var segment = ...;
var element = OneBotMessageSegments.toElement(segment);
```

### 消息段定义

OneBotText
: [纯文本](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#纯文本)。
:
:
:
: > **Tip:**
: > 实现了simbot标准消息类型 `PlainText` 接口。

OneBotAt
: [@某人或@全体](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#某人)。
:
:
:
: > **Tip:**
: > 因为与simbot标准消息类型 `At` 或 `AtAll` 的表达能力相同， 因此在接收的消息中会直接解析为 `At` 或 `AtAll`， 不会收到内容为 `OneBotAt` 的消息段元素。

OneBotFace
: [QQ表情](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#qq-表情)。
:
:
:
: > **Tip:**
: > 因为与simbot标准消息类型 `Face` 的表达能力相同， 因此在接收的消息中会直接解析为 `Face` ， 不会收到内容为 `OneBotFace` 的消息段元素。

OneBotAnonymous
: [匿名发消息](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#匿名发消息-)。

OneBotContact
: [推荐好友/推荐群](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#推荐好友)。

OneBotDice
: [掷骰子魔法表情](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#掷骰子魔法表情)。

OneBotForward
: [消息转发/合并转发](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#合并转发-)。
:
:
:
: `OneBotForward` 是通过事件接收到的元素类型。

OneBotForwardNode
: [消息转发节点/合并转发节点](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#合并转发节点-)。
:
:
:
: > **Warning:**
: > 自定义合并转发节点的结构定义有些...迷惑。 它似乎一个节点只能描述一个用户所发送的消息内容，但是又没说如何聚合发送。
: >
: > 不过其实按照实际情况来看，如果你打算发送合并转发消息， 那么消息元素链中只能包含 `OneBotForwardNode` 内容的元素。

OneBotImage
: [图片](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#图片)。
:
:
:
: 发送时:
:
:
:
: 如果你发送的是一个本地图片文件（例如使用 `File` 或 `Path`）， 而你希望发送时使用 `base64` 而不是此文件的绝对路径（默认是绝对路径）， 那么在构建 `OneBotImage` 时请注意额外的配置：
:
:
:
: Kotlin:
:
:
:
: ```KOTLIN
: val obimg = OneBotImage.create(
: Path("xxx.png").toResource(),
: ) {
: localFileToBase64 = true
: }
:
: val emement = obimg.toElement()
: ```
:
:
:
: Java:
:
:
:
: ```JAVA
: var params = new OneBotImage.AdditionalParams();
: params.setLocalFileToBase64(true);
:
: var obimg = OneBotImage.create(
: Resources.valueOf(Path.of("xxx.png")),
: params
: );
:
: var element = obimg.toElement();
: // 或使用 OneBotMessageSegments.toElement(obimg);
: ```
:
:
:
:
: 当然，你也可以选择直接使用 `ByteArrayResource` 进行发送。
:
:
:
: 接收时:
:
:
:
: 会直接转为 `OneBotImage.Element` 而不是 `DefaultOneBotMessageSegmentElement`， 不过它们都实现 `OneBotMessageSegmentElement`。
:
:
:
: `OneBotImage.Element` 实现 `Image` 并提供了一些辅助属性或API，比如获取 `Resource` 或 `url` 字符串。

OneBotVideo
: [短视频](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#短视频)。
:
:
:
: 发送时:
:
:
:
: 如果你发送的是一个本地文件（例如使用 `File` 或 `Path`）， 而你希望发送时使用 `base64` 而不是此文件的绝对路径（默认是绝对路径）， 那么在构建 `OneBotVideo` 时请注意额外的配置：
:
:
:
: Kotlin:
:
:
:
: ```KOTLIN
: val obvideo = OneBotVideo.create(
: Path("xxx.mp4").toResource(),
: OneBotVideo.AdditionalParams().apply {
: localFileToBase64 = true
: }
: )
:
: val emement = obvideo.toElement()
: ```
:
:
:
: Java:
:
:
:
: ```JAVA
: var params = new OneBotVideo.AdditionalParams();
: params.setLocalFileToBase64(true);
:
: var video = OneBotVideo.create(
: Resources.valueOf(Path.of("xxx.mp4")),
: params
: );
:
: var element = OneBotMessageSegments.toElement(video);
: ```
:
:
:
:
: 当然，你也可以选择直接使用 `ByteArrayResource` 进行发送。

OneBotLocation
: [位置](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#位置)。

OneBotMusic
: [音乐分享](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#音乐分享-)。

OneBotPoke
: [戳一戳](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#戳一戳)。

OneBotRecord
: [语音](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#语音)。

OneBotReply
: [引用回复](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#回复)
:
:
:
: 如果使用 `reply` API 发送消息，且消息链中没有其他的内容为 `OneBotReply` 的元素， 则会自动附加一个。

OneBotRps
: [猜拳魔法表情](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#猜拳魔法表情)

OneBotShake
: [窗口抖动（戳一戳）](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#窗口抖动戳一戳-)

OneBotShare
: [链接分享](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#链接分享)

OneBotXml
: [XML 消息](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#xml-消息)。

OneBotJson
: [JSON 消息](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md#json-消息)。

OneBotUnknownSegment
: 一个当出现了除上述其他已知类型以外的消息段类型时使用的包装类型。 它通过对 `SerializersModule` 的配置增加了 `OneBotMessageSegment` 类型的默认序列化/反序列化器来支持解析为此默认类型。
:
:
:
: 它只支持使用JSON序列化器，因为它使用了 `JsonElement` 作为 `data` 属性的类型。
:
:
:
: > **Warning: 实验性**
: > `OneBotUnknownSegment` 是实验性的。可能不稳定或在未来发生变更、移除。