# 消息元素

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

本章节介绍 KOOK 组件中针对 simbot 标准库中 消息元素(`Message.Element`) 的实现类型。

## Message.Element

先简单介绍一下 `Message.Element`。它是 simbot 标准库中提供一个接口类型， 用来定义一个消息元素。一个消息元素或多个消息元素组成的消息链可用于发送消息。

simbot 标准库提供了一些常见的标准消息元素实现，例如 `At`、`Image` 等。 但是很多情况下，对于一个组件而言这些标准实现可能不能满足需求，这时候就需要组件实现这个接口， 来提供更多期望的功能。

> **Tip:**
> 你可以前往 [simbot4 手册的消息元素](https://simbot.forte.love/basic-messages.html) 了解更多详情。

## 标准消息元素支持

PlainText
: 最基础的消息元素类型。支持使用文本消息元素， 例如 `Text`。

At
: 提及一个用户、提及一个角色或提及一个子频道。 提及目标根据 `At.type` 决定：
:
:
:
: * `user`(默认) 或其他未知: 提及一个用户
:
: * `role`: 提及一个角色
:
: * `channel`: 提及一个子频道
:
:
:
: 如果你希望直接构建这三种 `At`， 可使用 `KookMessages.atUser(...)` 、`KookMessages.atRole(...)` 、`KookMessages.atChannel(...)` 。

AtAll
: 提及所有人。即 `@全体`。

Image
: 支持使用:
:
:
:
: * `OfflineImage`: 上传一个本地离线文件作为图片并用于发送。
:
: * `RemoteImage`: 如果是 `RemoteUrlAwareImage`，则使用它的 `url`，否则将它的 `id` 视为 `url` 字符串。 > **Tip:** > 不会进行 url 的有效性校验。因为如果不是url、或者 url 不能用于发送则可能会引发异常。

Face
: 会作为 [KMarkdown](https://developer.kookapp.cn/doc/kmarkdown) 中的 “服务器表情” 使用。
:
:
:
: > **Warning:**
: > 目前已知的问题是 `Face` 只有 `id`, 而“服务器表情”似乎还需要“名称”, 因此会将 `id` 也视为名称, 最终产生如下结果:
: >
: > `(emj)服务器表情id(emj)[服务器表情id]`

Emoji
: 会作为 [KMarkdown](https://developer.kookapp.cn/doc/kmarkdown) 中的 “emoji” 使用。 `Emoji.id` 会被处理为:
:
:
:
: `:Emoji.id:`

## KOOK 组件消息元素实现

KOOK 组件进行特殊实现的 `Message.Element` 均继承自 `love.forte.simbot.component.kook.message.KookMessageElement`。

其中一部分“仅用于发送”的元素会被 `@KookSendOnlyMessage` 标记， 意味着它们通常不会原样出现在接收事件里。

KookKMarkdownMessage
: 将 `love.forte.simbot.kook.objects.kmd.KMarkdown` 包装为消息元素。
:
:
:
: 常用入口：
:
:
:
: * `KMarkdown.asMessage()`
:
: * `kookKMarkdown { ... }`

KookCardMessage
: 将 KOOK Card Message 包装为消息元素。
:
:
:
: 常用入口：
:
:
:
: * `CardMessage.asMessage()`
:
: * `kookCard { ... }`

KookAssetMessage
: 表示“已经通过 `CreateAssetApi` 上传完成”的资产消息。 这是典型的发送型消息元素。
:
:
:
: 主要子类型：
:
:
:
: * `KookAsset`: 任意资产 + 指定消息类型
:
: * `KookAssetImage`: 资产图片，同时可视为 `RemoteImage`
:
:
:
: 常见来源：
:
:
:
: * `KookBot.uploadAsset(...)`
:
: * `KookBot.uploadAssetImage(...)`
:
: * `Asset.asMessage(...)`
:
: * `Asset.asImage()`

KookAtAllHere
: 通知当前在线成员，语义接近 “@在线成员”。

KookAttachmentMessage 子类型
: 表示从接收消息中解析出来的附件消息。 这类类型通常更偏向“接收侧”。

KookAttachmentMessage
: KookAttachment
: : 普通附件。
:
:
: KookAttachmentFile
: : 文件附件。
:
:
: KookAttachmentImage
: : 图片附件，同时可作为 `Image` 使用。
:
:
: KookAttachmentVideo
: : 视频附件。

KookQuote
: > **Tip:**
: > 添加自 `4.0.0-beta5`
:
:
:
: 通过 `MessageContent.reference()` 查询得到的消息引用信息。 它也可以直接作为发送时的引用目标使用，语义等同于 `MessageIdReference`。