开发指南/消息卡片/搭建工具卡片组件/通用模块与元素
# 通用模块与元素
在消息卡片中，一些模块和元素可以被包含在其他多个组件当中使用，本文汇总了这些通用模块与元素，供你参考了解。
## 交互模块（action）
消息卡片的交互组件包括：按钮（button）、列表选择器（seletMenu）、折叠按钮组（overflow）、日期选择器（datePicker）。以上组件在单独使用时均包含在交互模块中，交互模块的标识为 `"tag": "action"`。
如果可交互的组件被绑定在内容模块（div）的 `extra` 字段，则无需包含在交互模块（action）中。
交互模块的参数说明如下表所示。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
tag | 是 | String | 交互模块的标识。固定取值：action
actions | 是 | 数组 | 添加可交互的组件。支持添加的组件如下，你可以跳转至对应的组件文档查看参数配置详情。
- [按钮（button）](https://open.larksuite.com/document/ukTMukTMukTM/uEzNwUjLxcDM14SM3ATN)
- [列表选择器（selectMenu）](https://open.larksuite.com/document/ukTMukTMukTM/uIzNwUjLycDM14iM3ATN)
- [折叠按钮组（overflow）](https://open.larksuite.com/document/ukTMukTMukTM/uMzNwUjLzcDM14yM3ATN)
- [日期选择器（datePicker）](https://open.larksuite.com/document/ukTMukTMukTM/uQzNwUjL0cDM14CN3ATN)
layout | 否 | String | 设置窄屏自适应布局方式。取值:
- bisected：二等分布局，每行两列交互元素。
- trisection：三等分布局，每行三列交互元素。
- flow：流式布局，元素会按自身大小横向排列并在空间不够的时候折行。
交互组件配置示例：
```json
{
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"tag": "plain_text",
"content": "primary"
},
"type": "primary",
"multi_url": {
"url": "https://open.larksuite.com/document",
"android_url": "",
"ios_url": "",
"pc_url": ""
}
},
{
"tag": "button",
"text": {
"tag": "plain_text",
"content": "default"
},
"url": "https://open.larksuite.com/document",
"type": "default"
},
{
"tag": "button",
"text": {
"tag": "plain_text",
"content": "danger"
},
"url": "https://open.larksuite.com/document",
"type": "danger"
}
]
}
]
}
```
卡片效果展示：
## 内容模块（div）
消息卡片的以下组件均包含在内容模块中，内容模块的标识为 `"tag": "div"`。
- 文本
- 双列文本
- 文本 + 按钮
- 文本 + 图片
- 文本 + 列表选择器
- 文本 + 折叠按钮组
- 文本 + 日期选择器
内容模块的参数说明如下表所示。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
tag | 是 | String | 内容模块的标识。固定取值：div
text | 是 | Object | 单个文本内容，参数配置详情可参见[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)。
JSON 示例配置：
```JSON
{
"tag": "div",
"text": {
"tag": "plain_text",
"content": "Content module"
}
}
```
**注意事项**：**说明**：在内容模块中，`text` 和 `fields` 字段需至少设置一个。
fields | 否 | Object | 多列文本，参数配置详情可参见[双列文本](https://open.larksuite.com/document/ukTMukTMukTM/uYzNwUjL2cDM14iN3ATN)。
JSON 示例配置：
```JSON
{
"tag": "div",
"fields": [
{
"text": {
"tag": "lark_md",
"content": "**module:**\nContent module（div）"
},
"is_short": true
},
{
"text": {
"tag": "lark_md",
"content": "**function:**\nNew function"
},
"is_short": true
}
]
}
```
**注意事项**：**说明**：在内容模块中，`text` 和 `fields` 字段需至少设置一个。
extra | 否 | Object | 附加元素，添加后展示在文本右侧。支持附加的元素：
- 图片（image）
- [按钮（button）](https://open.larksuite.com/document/ukTMukTMukTM/uEzNwUjLxcDM14SM3ATN)
- [列表选择器（selectMenu）](https://open.larksuite.com/document/ukTMukTMukTM/uIzNwUjLycDM14iM3ATN)
- [折叠按钮组（overflow）](https://open.larksuite.com/document/ukTMukTMukTM/uMzNwUjLzcDM14yM3ATN)
- [日期选择器（datePicker）](https://open.larksuite.com/document/ukTMukTMukTM/uQzNwUjL0cDM14CN3ATN)
JSON 示例配置：
```JSON
// 如需使用该 JSON 示例，则注意需要手动清除 // 开头的注释
{
"tag": "div",
"extra": {
"tag": "img", // 附加一张图片
"img_key": "f32****5cf7",
"alt": {
"tag":
"plain_text",
"content": "alt_content"
}
}
}
```
在内容模块（div）中通过 `text` 或 `fields` 参数展示文本内容，通过 `extra` 参数附加 `image` 元素或者 `button`、`overflow`、`selectMenu`、`datePicker` 可交互元素。JSON 示例配置如下：
```json
// 如需使用该 JSON 示例，则注意需要手动清除 // 开头的注释
{
"elements": [
{
"text": {
"tag": "plain_text", // 一行文本
"content": "Content module"
},
"tag": "div",
"fields": [ // 多行文本（is_short = false）
{
"text": {
"tag": "lark_md",
"content": "**module:**\nContent module（div）"
},
"is_short": false
},
{
"text": {
"tag": "lark_md",
"content": "**function:**\nNew function"
},
"is_short": false
}
],
"extra": { // 附加一张图片
"tag": "img",
"img_key": "f32******************5cf7",
"alt": {
"tag": "plain_text",
"content": "alt_content"
}
}
}
]
}
```
卡片效果展示：
## 图片元素（image）
image 是图片元素，可用于内容模块的 `extra` 字段或备注组件的 `elements` 字段中。
- 放置在内容组件 `extra` 字段的图片尺寸固定为 64 × 64。
- 放置在备注组件 `elements` 字段的图片尺寸固定为 16 × 16。
image 元素的参数说明如下表所示。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
tag | 是 | String | image 元素的标识。固定取值：img
img_key | 是 | String | 图片资源 image_key。你可以调用[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口，上传一张用于发送消息的图片，获取返回值中的 image_key。
alt | 是 | Struct | 鼠标悬浮提示文字。文字内容由文本组件构成（仅支持文本组件的 `plain_text` 模式），详细说明可参见[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)。
preview | 否 | Boolean | 点击后是否放大图片。
- true（默认）：放大
- false：不放大。如果你的卡片配置了消息卡片跳转链接（card_link），则建议配置为 `preview = false`，使用户点击卡片图片时也能响应 card_link 的跳转链接。
使用示例：
```json
// 如需使用该 JSON 示例，则注意需要手动清除 // 开头的注释
{
"elements": [
{
"tag": "div",
"text": {
"tag": "plain_text",
"content": "image element"
},
"extra": {
"tag": "img", // image 元素
"img_key": "asdfxxxxxxxxx1234", // image_key
"alt": { // 鼠标悬浮提示文字
"tag": "plain_text",
"content": "hover图片后的tips文案"
}
}
},
{
"tag": "hr"
},
{
"tag": "note",
"elements": [
{
"tag": "img", // image 元素
"img_key": "asdfxxxxxxxxx1234", // image_key
"alt": { // 鼠标悬浮提示文字
"tag": "plain_text",
"content": "hover图片后的tips文案"
}
},
{
"tag": "plain_text",
"content": "note"
}
]
}
]
}
```
卡片效果展示：
## 消息卡片跳转链接（card_link）
`card_link` 用于指定卡片整体的点击跳转链接，可以配置默认链接，也可以分别为 PC 端、Android 端、iOS 端配置不同的跳转链接。
card_link 的参数说明如下表所示。
- 如果未配置 `pc_url`、`ios_url`、`android_url`，则默认跳转至 `url`。
- 如果配置了 `pc_url`、`ios_url`、`android_url`，则优先生效各端指定的跳转链接。
| 参数 | 是否必须 | 描述 |
| ------------ | ---- | -------------------- |
| url | 是 | 默认的链接地址。 |
| pc_url | 否 | PC 端的链接地址。 |
| ios_url | 否 | iOS 端的链接地址。 |
| android_url | 否 | Android 端的链接地址。 |
使用示例：
```json
{
"elements": [
{
"tag": "div",
"text": {
"content": "This is a text example",
"tag": "plain_text"
}
}
],
"header": {
"template": "blue",
"title": {
"content": "This is a title",
"tag": "plain_text"
}
},
"card_link": {
"url": "https://www.baidu.com",
"android_url": "https://developer.android.com/",
"ios_url": "https://developer.apple.com/",
"pc_url": "https://www.windows.com"
}
}
```
对应的消息卡片示例如下图所示。
假如在 PC 端点击该示例卡片，会自动跳转到 pc_url 对应的地址。
## 二次确认（confirm）
confirm 元素用于交互组件（按钮、列表选择器、折叠按钮组、日期选择器）的二次确认。二次确认的弹窗默认提供了确认和取消按钮，你只需要配置弹窗的标题与内容即可。
confirm 元素的参数说明如下表所示。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
title | 是 | Struct | 弹窗标题。由文本组件构成（仅支持文本组件的 plain_text 模式），详情参见[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)。
text | 是 | Struct | 弹窗内容。由文本组件构成（仅支持文本组件的 plain_text 模式），详情参见[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)。
使用示例：
```json
"confirm":{
"title":{
"tag":"plain_text",
"content":"title"
},
"text":{
"tag":"plain_text",
"content":"content"
}
}
```
二次确认弹框样例：
## 选项元素（option）
option 是列表选择器（selectMenu）或折叠按钮组（overflow）组件中的选项元素。
option 元素参数说明如下表所示。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
text | 否 | Struct | 选项显示的内容。
- 基于文本组件的 plain_text 模式设置文本内容，详情参见[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)。
- 当列表选择器（selectMenu）的模式为人员选择器（select_person）时，无需配置 `text` 字段，除此之外，其他场景中 `text` 字段必填。
value | 否 | String | 回传参数值。当选项选中后，应用会将该值返回至消息卡片请求地址。
url | 否 | String | 选项的跳转链接，仅支持在折叠按钮组（overflow）中设置。
**注意事项**：**说明**：`url` 和 `multi_url` 字段必须且仅能填写其中一个。
multi_url | 否 | Struct | 选项的跳转链接,仅支持在折叠按钮组（overflow）中设置。支持按操作系统设置不同的链接，参数配置详情参见 **链接元素（url）**。
**注意事项**：**说明**：`url` 和 `multi_url` 字段必须且仅能填写其中一个。
使用示例：
```json
// 如需使用该 JSON 示例，则注意需要手动清除 // 开头的注释
{
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "select_static",
"placeholder": {
"tag": "plain_text",
"content": "default"
},
"value": {
"key": "value"
},
"options": [ // 自定义的文本选项
{
"text": {
"tag": "plain_text",
"content": "text"
},
"value": "value"
}
]
}
]
}
]
}
```
卡片效果展示：
## 链接元素（url）
url 元素用于设置默认跳转链接以及多端（支持 PC 端、Android 端、iOS 端）跳转链接。该元素可被添加到：
- [按钮（button）](https://open.larksuite.com/document/ukTMukTMukTM/uEzNwUjLxcDM14SM3ATN) 组件的 `multi_url` 字段。
- [Markdown](https://open.larksuite.com/document/ukTMukTMukTM/uADOwUjLwgDM14CM4ATN) 组件的 `href` 字段。此外 `lark_md` 类型的[文本组件](https://open.larksuite.com/document/ukTMukTMukTM/uUzNwUjL1cDM14SN3ATN)也支持设置 `href` 字段。
url 元素的参数说明如下表所示。warning
**注意：**
- url 和各端的链接（android_url、ios_url、pc_url）必填其中一个。具体的跳转策略：
- 只填写 url，未填写 android_url、ios_url、pc_url 时，默认跳转至 url。
- 如果不填写 url，则必须完整填写 android_url、ios_url、pc_url 三个字段。
- 如果同时填写了 url 和 android_url、ios_url、pc_url，优先跳转各端 url。
- 如果需要禁止某端进行跳转，可以将对应的参数值配置为 `lark://msgcard/unsupported_action`。
参数 | 是否必须 | 类型 | 说明
---|---|---|---
url | 否 | String | 默认的跳转链接。
android_url | 否 | String | Android 端的跳转链接。
ios_url | 否 | String | iOS 端的跳转链接。
pc_url | 否 | String | PC 端的跳转链接。
### 在 button 组件中配置 url
在 button 的 `multi_url` 字段中设置默认 url 和各端的 url，示例配置如下：
```json
{
"elements": [
{
"tag": "action",
"actions": [
{
"tag": "button",
"text": {
"tag": "plain_text",
"content": "demoButton"
},
"multi_url": {
"url": "https://www.baidu.com",
"android_url": "https://developer.android.com/",
"ios_url": "https://developer.apple.com/",
"pc_url": "https://www.windows.com"
},
"type": "primary"
}
]
}
]
}
```
### 在 markdown 组件中配置 url
1. 在 `content` 中使用 Markdown 语法定义链接 `[链接名称]($urlVal)`，其中 `$urlVal` 为变量，名称可自定义设置。
2. 在 `href` 字段中指定变量（例如 `urlVal`）对应的 url 元素实现多端跳转。
JSON 示例：
```json
{
"elements": [
{
"tag": "markdown",
"content": "Demo：[Click to jump]($urlDemo)\n",
"href": {
"urlVal": {
"ios_url": "www.baidu.com",
"pc_url": "www.baidu.com",
"android_url": "www.baidu.com",
"url": "www.baidu.com"
}
}
}
]
}
```
### 在 lark_md 模式的文本组件中配置 url
`lark_md` 类型的文本组件支持设置 `href` 字段。配置方式为：
1. 在 `content` 中使用 Markdown 语法定义链接 `[链接名称]($urlVal)`，其中 `$urlVal` 为变量，名称可自定义设置。
2. 在 `href` 字段中指定变量（例如 `urlVal`）对应的 url 元素实现多端跳转。
JSON 示例：
```json
{
"elements": [
{
"tag": "div",
"text": {
"tag": "lark_md",
"content": "Demo: [Click to jump]($urlVal)",
"href": {
"urlVal": {
"url": "https://www.baidu.com",
"android_url": "https://developer.android.com/",
"ios_url": "https://developer.apple.com/",
"pc_url": "https://www.windows.com"
}
}
}
}
]
}
```