卡片消息
卡片消息是结构化的消息,可以提供一个易用、统一的富交互形式。
我们还提供了卡片消息编辑器,方便可视化编辑:点击使用
整体结构说明
cardmessage 主要由 json 构成,在卡片消息中,有四种类别的卡片结构:
- 卡片,目前只有 card。
- 模块,主要有 section, header, context 等。
- 元素:主要有 plain-text, image, button 等。
- 结构:目前只有 paragraph。
消息的主要结构
- 一个卡片消息最多只允许 5 个卡片
- 一个卡片可以有多个模块,但是一个卡片消息总共不允许超过 50 个模块
[
{
type: 'card',
//...
modules: [
// ...
],
},
// 其它card
];
主要结构说明
所有的元素都有相似的结构,大体如下:
{
"type" : "类别",
"foo" : "bar", //属性参数
"modules|elements|fields": [], //子元素,根据type类别有不同的值,卡片的为modules,模块的子元素为elements,结构的为fields。
}
一些全局字段说明
在很多结构中,有一些字段都是一样的,因此在此处说明,后面就不单独说明了:
字段 | 类型 | 说明 |
---|---|---|
theme | string | 主题,可选的值为:primary, success, danger, warning, info, secondary, none.默认为 primary,为 none 时不显示侧边框。 |
size | string | 大小,可选值为:xs, sm, md, lg, 一般默认为 lg |
卡片消息发送说明
在消息发送时,卡片消息的发送类型为10
, 在发送时,content 字段为 json 的字符串。详情参见消息发送接口。发送前请调用各语言自带的 json 序列化方法进行序列化再进行发送,直接发送未经序列化的 json 字符串通常会产生错误。
关于卡片中包含的媒体
如果卡片中包含第三方媒体链接,我们将会自行转存媒体后再完成发送。由于访问速度等各种原因,很容易产生失败。推荐大家优先调用asset接口上传媒体文件后再进行发送,以防由于转存失败导致卡片发送不成功。
另外,最大家注意下多媒体的内容,如果有涉黄涉政等内容,可能会导致机器人被封禁,请谨慎对待。
卡片
card
主要结构:
{
"type": "card",
"theme" : "primary|warning|danger|info|none...", // 卡片风格,默认为primay
"color":"#aaaaaa", //色值
"size": "sm|lg", //目前只支持sm与lg, 如果不填为lg。 lg仅在PC端有效, 在移动端不管填什么,均为sm。
"modules": [
// modules...
]
}
说明:
- modules 只能为模块
- 单个 card 模块数量不限制,但是总消息最多只能有 50 个模块
- theme, size 参见全局字段说明 ,卡片中,size 只允许 lg 和 sm
- color 代表卡片边框具体颜色,如果填了,则使用该 color,如果未填,则使用 theme 来渲染卡片颜色。
模块
标题模块
作用说明: 标题模块只能支持展示标准文本(text),突出标题样式。
主要结构:
{
"type": "header",
"text" : {
"type": "plain-text",
"content": "标题1"
}
}
说明:
- text 为文字元素且 content 不能超过 100 个字
内容模块
作用说明: 结构化的内容,显示文本+其它元素。
主要结构:
{
"type": "section",
"mode" : "left|right", //accessory在左侧还是在右侧
"text" : {
"type": "plain-text|kmarkdown|paragraph",
//...
},
"accessory": {
"type": "image|button",
//...
}
}
说明:
- text 可以为 plain-text, kmarkdown 或者 paragraph
- accessory 可以为 image 或者 button
- button 不能放置在左侧
- mode 代表 accessory 是放置在左侧还是在右侧
图片组模块
作用说明: 1 到多张图片的组合
主要结构:
{
"type" : "image-group",
"elements": [
//图片元素,其它元素无效
],
}
说明:
- elements 只能有 image 元素,只能有 1-9 张图片
容器模块
作用说明: 1 到多张图片的组合,与图片组模块不同,图片并不会裁切为正方形。多张图片会纵向排列。
主要结构:
{
"type" : "container",
"elements": [
//图片元素,其它元素无效
],
}
说明:
- elements 只能有 image 元素,只能有 1-9 张图片
交互模块
作用说明: 交互模块中包含交互控件元素,目前支持的交互控件为按钮(button)
主要结构:
{
"type": "action-group",
"elements": [
// buttons
],
}
说明:
- elements 中只能为 button
- elements 最多只能有 4 个
备注模块
作用说明: 展示图文混合的内容。
主要结构:
{
"type": "context",
"elements": [],
}
说明:
- elements 中可以为:plain-text, kmarkdown, image
- elements 最多可包含 10 个元素
分割线模块
作用说明: 展示分割线。
主要结构:
{
"type": "divider",
}
文件模块
作用说明: 展示文件,目前有三种,文件,视频和音频。
主要结构:
{
"type": "file|audio|video",
"src": "", //文件|音频|视频地址
"title": "标题",
"cover": "" //封面图
}
规则:
- cover 仅在音频的时候有效,是音频的封面图。
倒计时模块
作用说明: 展示倒计时。
主要结构:
{
"type": "countdown",
"endTime" : 1608819168000, //到期的毫秒时间戳
"startTime" : 1608819168000, //起始的毫秒时间戳,仅当mode为second才有这个字段
"mode" : "day,hour,second", //倒计时样式, 按天显示,按小时显示或者按秒显示
}
规则:
- mode 主要是倒计时的样式,目前支持三种样式。
- startTime 和 endTime 为毫秒时间戳,startTime 和 endTime 不能小于服务器当前时间戳。
邀请模块
作用说明: 提供服务器邀请/语音频道邀请 主要结构:
{ "type": "invite", "code": "邀请链接或者邀请码" }
元素
普通文本
作用说明: 显示文字。
主要结构:
{
"type": "plain-text",
"content" : "",
"emoji": true|false,
}
规则:
- emoji 为布尔型,默认为 true。如果为 true,会把 emoji 的 shortcut 转为 emoji
- 为了方便书写,所有 plain-text 的使用处可以简单的用字符串代替。
- 最大 2000 个字
// "hello world" 等价于:
{
"type" : "plain-text",
"emoji": true,
"content" : "hello world",
}
kmarkdown
作用说明: 显示文字。
主要结构:
{
"type": "kmarkdown",
"content" : "**hello**",
}
规则:
- 最大 5000 个字
图片
作用说明: 显示图片。
主要结构:
{
"type": "image",
"src" : "",
"alt" : "",
"size" : "sm|lg", // size只用在图文混排 图片组大小固定
"circle" : true|false,
}
规则:
- 图片类型(MimeType)限制说明:目前仅支持
image/jpeg
,image/gif
,image/png
这 3 种 - 图片的 size 默认为 lg
按钮
作用说明: 提供交互的功能
{
"type": "button",
"theme": "primary|warning|info|danger|...", //按钮的主题颜色
"value": "", //要传递的value,为string
"click": "", //click时的事件类型, return-val 返回value值
"text": "",
}
- value 只能为 string
- text 可以为 plain-text, kmarkdown
- click 代表用户点击的事件,默认为””,代表无任何事件。
- 当为 link 时,会跳转到 value 代表的链接;
- 当为 return-val 时,系统会通过系统消息将消息 id,点击用户 id 和 value 发回给发送者,发送者可以根据自己的需求进行处理,消息事件参见button 点击事件。私聊和频道内均可使用按钮点击事件。
结构体
区域文本
作用说明: 支持分栏结构,将模块分为左右两栏,根据顺序自动排列,支持更自由的文字排版模式,提高可维护性
主要结构:
{
"type": "paragraph",
"cols": 3, //移动端忽略该参数
"fields" : [
],
}
规则:
- cols 是 int,可以的取值为 1-3
- fields 可以的元素为 text 或 kmarkdown
- paragraph 最多有 50 个元素