标准元素

这里列出了应该由各适配器实现的标准消息元素。各适配器由于平台的限制可能表现出一定的行为差异，但应尽可能贴近标准规定的语义。

与 HTML 的区别

为了方便记忆，我们使用了许多 HTML 中出现的标签来表达类似的语义，如 ,  等。但需要指出的是，这并不意味着这些同名的标签就有着相同的语义。这里举出几个例子：

HTML 中标签  的定义是「表意不清标注元素」，而 Koishi 这里只使用了下划线的功能
HTML 中图像对应 <img> 标签，而 Koishi 中则是 <image>，并且语法也不相同

关于兼容性表格

✓ 表示平台和适配器都完全支持
~ 表示平台不支持，适配器自动回退
○ 表示平台支持但适配器不支持
? 表示平台支持情况未知

基础元素

基本元素是最常见的消息元素，它们能够在大多数平台上正常显示，是组成消息的基本单位。

纯文本 (text)

content: string 文本内容

这是一个特殊的消息元素。它等价于一段纯文本，并且在序列化时也不会带两侧的标签。

	Discord	Kook	OneBot	QQGuild	Telegram
`<text>`	✓	✓	✓	✓	✓

提及用户 (at)

id: string 目标用户的 ID
name: string 目标用户的名称
role: string 目标角色
type: string 特殊操作，例如 all 表示 @全体成员，here 表示 @在线成员

<at> 元素用于提及某个或某些用户。

TIP

由于上述几个属性的语义是互斥的，发送时使用 id, role, type 其一即可。

	Discord	Kook	OneBot	QQGuild	Telegram
`<at>`	✓	✓	✓	✓	✓
`id`	✓	✓	✓	✓	✓

提及频道 (sharp)

id: string 目标频道的 ID
name: string 目标频道的名称

<sharp> 元素用于提及某个频道。

	Discord	Kook	OneBot	QQGuild	Telegram
`<sharp>`	✓	✓	~	✓	~
`id`	✓	✓	~	✓	~

表情 (face)

id: string 表情的 ID
name: string 表情的名称
platform: string 表情显示的平台

<face> 元素用于显示某个表情。通常来说为了跨平台转发，在 <face> 内部还会增加 <image> 作为回退。当图片的存在可能导致消息分片时，可以使用 name 取代图片的渲染。

	Discord	Kook	OneBot	QQGuild	Telegram
`<face>`	✓	○	✓	○	○
`id`	✓	○	✓	○	○

链接 (a)

href: string 链接的 URL

<a> 元素用于显示一个链接。当平台不支持链接时，建议显示为 content (href) 的形式。

	Discord	Kook	OneBot	QQGuild	Telegram
`<a>`	✓	✓	✓	✓	✓
href	~	✓	~	~	✓

资源元素

资源消息元素表示文本中存在的资源文件。不同的平台对资源文件的支持存在较大的差异。发送时只需提供 url。如果某个平台不支持特定的资源类型，适配器应该用 url 代替。如果某个平台不支持将资源消息元素和其他消息元素同时发送，适配器应该分多条发送，并返回最后一条消息的 ID。

url: string 资源的 URL
cache: boolean 是否使用已缓存的文件
timeout: string 下载文件的最长时间

TIP

非网络资源的 URL 写法

本地文件请使用 file: 协议
二进制数据请使用 data: 协议

关于它们的最佳实践，可以参考嵌入图片和其他资源。

图片 (image)

除了上述通用属性外，还支持下面的属性：

type: 特殊类型，例如 flash 表示 QQ 闪照

<image> 元素用于表示图片。

语音 (audio)

参见上述通用属性。

<audio> 元素用于表示语音。

视频 (video)

参见上述通用属性。

<video> 元素用于表示视频。

文件 (file)

参见上述通用属性。

<file> 元素用于表示文件。

修饰元素

修饰元素用于修饰其中的内容。如果对应的平台不支持对应的元素，可以忽略这个元素本身，正常渲染其中的子元素。

粗体 (b, strong)

 或  元素用于将其中的内容以粗体显示。

	Discord	Kook	OneBot	QQGuild	Telegram
`<b>`	✓	✓	~	~	✓

斜体 (i, em)

 或  元素用于将其中的内容以斜体显示。

	Discord	Kook	OneBot	QQGuild	Telegram
`<i>`	✓	✓	~	~	✓

下划线 (u, ins)

 或 <ins> 元素用于为其中的内容附加下划线。

	Discord	Kook	OneBot	QQGuild	Telegram
`<u>`	✓	✓	~	~	✓

删除线 (s, del)

<s> 或 <del> 元素用于为其中的内容附加删除线。

	Discord	Kook	OneBot	QQGuild	Telegram
`<s>`	✓	✓	~	~	✓

剧透 (spl)

<spl> 元素用于将其中的内容标记为剧透 (默认会被隐藏，点击后才显示)。

	Discord	Kook	OneBot	QQGuild	Telegram
`<spl>`	✓	✓	~	~	✓

代码 (code)

<code> 元素用于将其中的内容以等宽字体显示 (通常还会有特定的背景色)。

	Discord	Kook	OneBot	QQGuild	Telegram
`<code>`	✓	✓	~	~	✓

上标 (sup)

 元素用于将其中的内容以上标显示。

	Discord	Kook	OneBot	QQGuild	Telegram
`<sup>`	~	~	~	~	~

下标 (sub)

 元素用于将其中的内容以下标显示。

	Discord	Kook	OneBot	QQGuild	Telegram
`<sub>`	~	~	~	~	~

排版元素

段落 (p)

 元素表示一个段落。在渲染时，它与相邻的元素之间会确保有一个换行。

消息 (message)

id: string 消息 ID
forward: boolean 是否为转发消息

<message> 元素的基本用法是表示一条消息。子元素对应于消息的内容。如果其没有子元素，则消息不会被发送。

当出现 <message> 元素时，之前的元素会被立即视为一条消息被发送。因此下面的两种写法是等价的：

html

<!-- 第一种写法：发送两条消息 -->
<message>hello</message>
<message>world</message>

<!-- 第二种写法：用一条空消息隔开两段文本，实际上仍然会发送两条消息 -->
hello<message/>world

部分平台允许你模拟其他用户发送消息：

html

<message>
  <author user-id="123123123" nickname="Alice" avatar="url"/>
  hello world
</message>

在支持转发的平台上，你可以使用 forward 配合 id 属性来转发一条消息：

html

<message id="123456789" forward/>

在支持合并转发的平台上，你可以使用带有 forward 属性的 <message> 元素嵌套其他 <message> 元素来实现合并转发：

html

<message forward>
  <message id="123456789"/>
  <message id="987654321"/>
  <!-- 合并转发里也可以嵌套模拟其他用户发送的消息 -->
  <message>
    <author user-id="123123123" nickname="Alice" avatar="url"/>
    hello world
  </message>
</message>

	Discord	Kook	OneBot	QQGuild	Telegram
`<message>`	✓	✓	✓	✓	✓
`id`	?	?	✓	?	?
`forward`	?	?	✓	?	?

元信息元素

元信息元素通常不会被渲染，但会影响到消息的发送行为。

引用 (quote)

<quote> 元素用于表示对消息引用。它的子元素会被渲染为引用的内容。理论上所有 <message> 元素的特性也可以用于 <quote> 元素，包括子元素 (构造引用消息) 和 forward 属性 (引用合并转发)。然而目前似乎并没有平台提供了这样的支持。

	Discord	Kook	OneBot	QQGuild	Telegram
`<quote>`	✓	✓	✓	✓	✓
`id`	✓	✓	✓	✓	✓

作者 (author)

userId: string 用户 ID
nickname: string 昵称
avatar: string 头像 URL

<author> 元素用于表示消息的作者。它的子元素会被渲染为作者的名字。

	Discord	Kook	OneBot	QQGuild	Telegram
`<author>`	⭘^[1]	~	✓^[2]	~	~
`userId`	~	~	✓	~	~
`nickname`	⭘	~	✓	~	~
`avatar`	⭘	~	~	~	~

[1]: 基于 Webhook 功能，目前暂未支持
[2]: 仅限 forward 和 quote 消息

标准元素 ​

基础元素 ​

纯文本 (text) ​

提及用户 (at) ​

提及频道 (sharp) ​

表情 (face) ​

链接 (a) ​

资源元素 ​

图片 (image) ​

语音 (audio) ​

视频 (video) ​

文件 (file) ​

修饰元素 ​

粗体 (b, strong) ​

斜体 (i, em) ​

下划线 (u, ins) ​

删除线 (s, del) ​

剧透 (spl) ​

代码 (code) ​

上标 (sup) ​

下标 (sub) ​

排版元素 ​

段落 (p) ​

消息 (message) ​

元信息元素 ​

引用 (quote) ​

作者 (author) ​

标准元素

基础元素

纯文本 (text)

提及用户 (at)

提及频道 (sharp)

表情 (face)

链接 (a)

资源元素

图片 (image)

语音 (audio)

视频 (video)

文件 (file)

修饰元素

粗体 (b, strong)

斜体 (i, em)

下划线 (u, ins)

删除线 (s, del)

剧透 (spl)

代码 (code)

上标 (sup)

下标 (sub)

排版元素

段落 (p)

消息 (message)

元信息元素

引用 (quote)

作者 (author)