标准元素
这里列出了应该由各适配器实现的标准消息元素。各适配器由于平台的限制可能表现出一定的行为差异,但应尽可能贴近标准规定的语义。
与 HTML 的区别
为了方便记忆,我们使用了许多 HTML 中出现的标签来表达类似的语义,如 <p>
, <em>
等。但需要指出的是,这并不意味着这些同名的标签就有着相同的语义。这里举出几个例子:
- HTML 中标签
<u>
的定义是「表意不清标注元素」,而 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
下载文件的最长时间
图片 (image)
除了上述通用属性外,还支持下面的属性:
- type: 特殊类型,例如
flash
表示 QQ 闪照
<image>
元素用于表示图片。
语音 (audio)
参见上述通用属性。
<audio>
元素用于表示语音。
视频 (video)
参见上述通用属性。
<video>
元素用于表示视频。
文件 (file)
参见上述通用属性。
<file>
元素用于表示文件。
修饰元素
修饰元素用于修饰其中的内容。如果对应的平台不支持对应的元素,可以忽略这个元素本身,正常渲染其中的子元素。
粗体 (b, strong)
<b>
或 <strong>
元素用于将其中的内容以粗体显示。
Discord | Kook | OneBot | QQGuild | Telegram | |
---|---|---|---|---|---|
<b> | ✓ | ✓ | ~ | ~ | ✓ |
斜体 (i, em)
<i>
或 <em>
元素用于将其中的内容以斜体显示。
Discord | Kook | OneBot | QQGuild | Telegram | |
---|---|---|---|---|---|
<i> | ✓ | ✓ | ~ | ~ | ✓ |
下划线 (u, ins)
<u>
或 <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)
<sup>
元素用于将其中的内容以上标显示。
Discord | Kook | OneBot | QQGuild | Telegram | |
---|---|---|---|---|---|
<sup> | ~ | ~ | ~ | ~ | ~ |
下标 (sub)
<sub>
元素用于将其中的内容以下标显示。
Discord | Kook | OneBot | QQGuild | Telegram | |
---|---|---|---|---|---|
<sub> | ~ | ~ | ~ | ~ | ~ |
排版元素
段落 (p)
<p>
元素表示一个段落。在渲染时,它与相邻的元素之间会确保有一个换行。
消息 (message)
- id:
string
消息 ID - forward:
boolean
是否为转发消息
<message>
元素的基本用法是表示一条消息。子元素对应于消息的内容。如果其没有子元素,则消息不会被发送。
当出现 <message>
元素时,之前的元素会被立即视为一条消息被发送。因此下面的两种写法是等价的:
<!-- 第一种写法:发送两条消息 -->
<message>hello</message>
<message>world</message>
<!-- 第二种写法:用一条空消息隔开两段文本,实际上仍然会发送两条消息 -->
hello<message/>world
部分平台允许你模拟其他用户发送消息:
<message>
<author user-id="123123123" nickname="Alice" avatar="url"/>
hello world
</message>
在支持转发的平台上,你可以使用 forward
配合 id
属性来转发一条消息:
<message id="123456789" forward/>
在支持合并转发的平台上,你可以使用带有 forward
属性的 <message>
元素嵌套其他 <message>
元素来实现合并转发:
<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 消息