消息

公告

站点迁移啦~！

为什么迁移?

作为由我们官方维护的组件库，分散在各自的文档站点中的确有好处：它们可以各自维护自己所需的东西、互不干扰。

但是缺点也很明显：太过分散。

组件库与核心库之间的关系是比较紧密的，我们希望你能够在一个站点内就可以查阅或搜索到所有你想要得知的信息。

标准消息元素

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

Text

纯文本消息。

At

At某人。

AtAll

At全体。

Face

一个表情。

Image

图片类型的接口类型。

发送时可以使用simbot标准API中的 Image 实现类型，例如 OfflineImage 的某个实现。

消息段

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

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

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

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

消息段定义

OneBotText

纯文本。

OneBotAt

@某人或@全体。

OneBotFace

QQ表情。

OneBotAnonymous

OneBotContact

OneBotDice

OneBotForward

OneBotForward 是通过事件接收到的元素类型。

OneBotForwardNode

消息转发节点/合并转发节点。

OneBotImage

图片。

发送时:

如果你发送的是一个本地图片文件（例如使用 File 或 Path），而你希望发送时使用 base64 而不是此文件的绝对路径（默认是绝对路径），那么在构建 OneBotImage 时请注意额外的配置：

val obimg = OneBotImage.create(
    Path("xxx.png").toResource(),
) {
    localFileToBase64 = true
}

val emement = obimg.toElement()

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

短视频。

发送时:

如果你发送的是一个本地文件（例如使用 File 或 Path），而你希望发送时使用 base64 而不是此文件的绝对路径（默认是绝对路径），那么在构建 OneBotVideo 时请注意额外的配置：

val obvideo = OneBotVideo.create(
    Path("xxx.mp4").toResource(),
    OneBotVideo.AdditionalParams().apply {
        localFileToBase64 = true
    }
)

val emement = obvideo.toElement()

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

位置。

OneBotMusic

音乐分享。

OneBotPoke

戳一戳。

OneBotRecord

语音。

OneBotReply

引用回复

如果使用 reply API 发送消息，且消息链中没有其他的内容为 OneBotReply 的元素，则会自动附加一个。

OneBotRps

猜拳魔法表情

OneBotShake

窗口抖动（戳一戳）

OneBotShare

链接分享

OneBotXml

XML 消息。

OneBotJson

JSON 消息。

OneBotUnknownSegment

一个当出现了除上述其他已知类型以外的消息段类型时使用的包装类型。它通过对 SerializersModule 的配置增加了 OneBotMessageSegment 类型的默认序列化/反序列化器来支持解析为此默认类型。

它只支持使用JSON序列化器，因为它使用了 JsonElement 作为 data 属性的类型。

Last modified: 02 July 2025