# 卡片搭建说明
本文档介绍如何从 0 到 1 搭建卡片交互机器人教程中的三张卡片。通过本文档，你可了解搭建卡片、传入变量、配置交互动作所需步骤及对应原因解释。
## 搭建欢迎卡片
本步骤介绍搭建欢迎卡片的具体流程，包括搭建结构、配置内容和样式、配置组件的变量、交互动作和多语言。
步骤 | 搭建步骤 | 说明 | 具体操作（本教程已经自动完成以下配置）
---|---|---|---
1 | 基于案例库创建卡片 | 基于案例库提供的卡片，你可了解常用组件的搭建方式，快速构建卡片。了解更多，参考[构建卡片内容](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/build-card-content)。 | 1. 在[飞书卡片搭建工具](https://open.feishu.cn/cardkit?from=open_docs_tutorial)首页，点击 **参考案例库**。
2. 在 **参考案例库** 弹窗 **新版专区** 页面，找到 **欢迎卡片**，并点击 **使用**。
**提示**：新版专区的卡片新增 20+ 卡片能力。了解新旧版本卡片区别，参考[搭建工具新版卡片变更说明](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/cardkit-upgraded-version-card-release-notes)。
4. 将卡片名称设为 **欢迎卡片**，然后点击 **创建**。你将进入卡片的编辑页面。
2 | 搭建卡片结构 | 一张新版卡片由标题（可选）组件和正文组成。正文中可放置其它多个组件。搭建卡片时，你可先设计卡片大纲，明确卡片基本结构，再填充内容。欢迎卡片的大纲如下所示：
其中：
- 富文本、分割线组件为展示组件
- 分栏组件中用于更好布局卡片中的内容，可以添加多个列容器，每个列容器中可内嵌多个组件
- 按钮组件用于实现卡片的交互 | 要体验从 0 到 1 搭建欢迎卡片，你可参考以下步骤：
1. 在卡片编辑页面左侧 **组件** 页签下，依次点击标题、富文本、分割线、富文本、分栏、按钮、按钮组件。
此时，卡片大纲树如下所示：
3. 选中大纲树分栏中的 **列** 容器，然后点击卡片预览页面的删除按钮。保留一个列容器即可。
4. 选中两个按钮组件，将两个按钮组件分别拖拽放入列容器中。
5. 在左侧大纲树中选中 列 容器，在右侧配置页面，点击 样式 页签，在 **布局方式** 配置项中，选择 **流式**。
你已完成欢迎卡片基本结构和布局的构建，最终大纲如下所示：
3 | 配置组件文本内容和样式 | 基于卡片可视化搭建工具，你可实时为组件填充文本内容、改变组件样式，并预览效果。 | 为富文本和按钮组件分别配置内容，可参考文档[富文本](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/rich-text)。
4 | 配置组件变量 | 你可将变量理解为卡片内容的占位符。具体的内容或数据可在发送卡片时携带。如果你希望机器人发送欢迎卡片时能够显示@用户的效果，你可添加用户 ID 变量，在发送卡片的代码中携带用户的 [Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)。详情参考[发送卡片](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/send-feishu-card)和[示例代码解释](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-a-card-interactive-bot/explanation-of-example-code)。 | 1. 在画布区域右上角，点击变量图标，弹出 **变量** 页面，点击 **添加自定义变量**。
1. 在添加变量弹窗中，按照下图，添加一个 `open_id` 变量。
1. 在富文本组件的文本内容中，将光标定位至富文本组件的 @ 人语法中，然后点击右下角的变量图标，添加 `open_id` 变量。
5 | 配置组件交互动作 | 为按钮配置请求回调动作后，当用户点击该按钮时，飞书会向你的服务端发送[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)回调，其中包含了用户的交互信息，例如，当用户点击 **去体验：发起告警** 按钮后，卡片回调交互信息中将携带如下参数：
```JSON
{
"action": { // 用户操作交互组件回传的数据
"tag": "button", // 交互组件的标签，此处为按钮
"value": { // 交互组件绑定的开发者自定义的回传参数，此处类型为开发者自定义的对象
"action": "send_alarm"
}
}
}
```
你可基于此配置，继续处理用户点击按钮后的代码逻辑，详情参考[示例代码解释](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-a-card-interactive-bot/explanation-of-example-code)。 | 1. 为 **去体验：发起告警** 按钮配置 **请求回调** 动作，输入参数如下所示。详情参考[配置请求回调交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions#5746ae32)。
1. 为 **查看教程** 按钮配置 **打开链接** 动作。详情参考[配置打开链接交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions#3867b9c6)。
6 | 配置卡片多语言 | 如果你想配置多语言卡片，你可在搭建工具中实现不同语言内容的配置。案例库中的卡片为中英双语卡片。
 | 参考[为新版卡片配置多语言](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content#882164bf)了解如何配置多语言。
## 搭建发起告警卡片
本步骤介绍发起告警卡片的具体流程，包括搭建结构和布局、配置内容和样式、配置组件的变量、交互动作和多语言。
步骤 | 搭建步骤 | 说明 | 具体操作（本教程已经自动完成以下配置）
---|---|---|---
1 | 基于案例库创建卡片 | 基于案例库提供的卡片，你可了解常用组件的搭建方式，快速构建卡片。了解更多，参考[构建卡片内容](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/build-card-content)。 | 1. 在[飞书卡片搭建工具](https://open.feishu.cn/cardkit?from=open_docs_tutorial)首页，点击 **参考案例库**。
1. 在 **参考案例库** 弹窗 **新版专区** 页面，找到 **发起告警** 卡片，并点击 **使用**。
**提示**：新版专区的卡片新增 20+ 卡片能力。了解新旧版本卡片区别，参考[搭建工具新版卡片变更说明](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/cardkit-upgraded-version-card-release-notes)。
1. 将卡片名称设为 **发起告警**，然后点击 **创建**。你将进入卡片的编辑页面。
2 | 搭建卡片结构和布局 | 一张新版卡片由标题（可选）组件和正文组成。正文中可放置其它多个组件。搭建卡片时，你可先设计卡片大纲，明确卡片基本结构，再填充内容。发起告警卡片的大纲如下所示：
其中：
- 分栏组件中用于布局卡片中的内容，分栏包含多个列容器，每个列容器中可内嵌多个组件
- 富文本、分割线组件为展示组件
- 表单容器用于用户提交数据场合，包含一个提交按钮、一个取消按钮。你也可在其中放置输入框、下拉选项组件等结合使用 | 要体验从 0 到 1 搭建发起告警卡片，你可参考以下步骤：
1. 在卡片编辑页面左侧 **组件** 页签下，依次点击左列大纲图中的组件：标题、分栏、富文本、富文本、分栏、富文本、富文本、分割线、表单容器、输入框。
卡片大纲树将如下所示：
1. 在画布中，分别删除两个分栏容器中的一个 **列** 容器，然后将四个富文本组件分别拖入剩下的四个列容器中。
1. 选中两个按钮组件，将两个按钮组件分别拖拽放入列容器中。
1. 在左侧大纲树中，将输入框组件拖拽上移，放入表单容器中。
1. 在左侧大纲树中，选中表单容器中 **取消** 按钮所在的 **列** 容器，然后点击删除图标。
1. 在画布中，选中输入框组件，在右侧 **属性** 页签下，将宽度模式改为 **填满父容器-fill**。
你已完成发起告警卡片基本结构和布局的构建，最终大纲如下所示：
3 | 配置组件文本内容和样式 | 基于卡片可视化搭建工具，你可实时为组件填充文本内容、改变组件样式，并预览效果。 | 为标题文本、富文本、输入框占位文本、按钮文本分别配置内容，富文本语法可参考[富文本](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/rich-text)。
4 | 配置组件变量 | 你可将变量理解为卡片内容的占位符。具体的内容或数据可在发送卡片时携带。
在本教程中，发起告警卡片中传入了告警时间变量 `alarm_time`，并在代码逻辑中，将交互过程中告警卡片实际发送的时间传给变量 `alarm_time` 作为具体的数据。
详情参考[发送卡片](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/send-feishu-card)和[示例代码解释](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-a-card-interactive-bot/explanation-of-example-code)了解如何传入变量。 | 1. 在画布区域右上角，点击变量图标，弹出 **变量** 页面，点击 **添加自定义变量**。
2. 在添加变量弹窗中，按照下图，添加一个 `alarm_time` 变量。
3. 在富文本组件的文本内容中，将光标定位至目标富文本组件内容框中，然后点击右下角的变量图标，添加 `alarm_time` 变量。
添加完成后的效果如下所示：
5 | 配置组件交互动作 | 为按钮配置请求回调动作后，当用户点击该按钮时，飞书会向你的服务端发送[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)回调，其中包含了用户的交互信息。在本教程中，当用户点击 **处理完成** 按钮时，回传参数中需包含以下参数，以用于更新卡片。详情参考[示例代码解释](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-a-card-interactive-bot/explanation-of-example-code)。
```json
{
"action": { // 用户操作交互组件回传的数据
"tag": "button", // 交互组件的标签，此处为按钮
"value": { // 交互组件绑定的开发者自定义的回传参数，此处类型为开发者自定义的对象
"action": "complete_alarm", // 用户点击了处理完成按钮
"time": "${alarm_time}" // 告警时间
}
}
}
``` | 为 **处理完成** 按钮创建事件，配置 **请求回调** 动作，输入参数如下所示。详情参考[配置请求回调交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions#5746ae32)。
6 | 配置卡片多语言 | 如果你想配置多语言卡片，你可在搭建工具中实现不同语言内容的配置。案例库中的卡片为中英双语卡片。 | 参考[为新版卡片配置多语言](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content#882164bf)了解如何配置多语言。
## 搭建告警处理完成卡片
本步骤介绍告警处理完成卡片的具体流程，包括搭建结构、配置内容和样式、配置组件的变量、交互动作和多语言。
步骤 | 搭建步骤 | 说明 | 具体操作（本教程已经自动完成以下配置）
---|---|---|---
1 | 基于案例库创建卡片 | 基于案例库提供的卡片，你可了解常用组件的搭建方式，快速构建卡片。了解更多，参考[构建卡片内容](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/build-card-content)。 | 1. 在[飞书卡片搭建工具](https://open.feishu.cn/cardkit?from=open_docs_tutorial)首页，点击 **参考案例库**。
1. 在 **参考案例库** 弹窗 **新版专区** 页面，找到 **告警处理完成** 卡片，并点击 **使用**。
**提示**：新版专区的卡片新增 20+ 卡片能力。了解新旧版本卡片区别，参考[搭建工具新版卡片变更说明](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/feishu-card-cardkit/cardkit-upgraded-version-card-release-notes)。
1. 将卡片名称设为 **告警处理完成**，然后点击 **创建**。你将进入卡片的编辑页面。
2 | 搭建卡片结构和布局 | 一张新版卡片由标题（可选）组件和正文组成。正文中可放置其它多个组件。搭建卡片时，你可先设计卡片大纲，明确卡片基本结构，再填充内容。发起告警卡片的大纲如下所示：
其中：
- 分栏组件中用于布局卡片中的内容，分栏包含多个列容器，每个列容器中可内嵌多个组件
- 富文本、分割线组件为展示组件 | 从 0 到 1 搭建告警处理完成卡片与搭建发起告警卡片步骤类似，你可参考上文 **搭建发起告警卡片** 一节。
3 | 配置组件文本内容和样式 | 基于卡片可视化搭建工具，你可实时为组件填充文本内容、改变组件样式，并预览效果。 | 为标题文本、富文本、输入框占位文本、按钮文本分别配置内容，富文本语法可参考[富文本](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/rich-text)。
4 | 配置组件变量 | 你可将变量理解为卡片内容的占位符。具体的内容或数据可在发送卡片时携带。在本教程中，告警处理完成卡片中传入以下变量，详情参考[示例代码解释](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-a-card-interactive-bot/explanation-of-example-code)。
- 告警时间变量 `alarm_time`。在示例代码逻辑中，该变量实际的值为开发者在搭建发起告警卡片时，为 **处理完成** 按钮配置的回传参数 2：
- 用户 ID 变量 `open_id`。[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)回调中包含了用户的 Open ID，示例代码中获取了回调中用户的 Open ID，并将其传给了变量 `open_id`。将该变量放置于[富文本](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/rich-text#6d6698b6)的人员语法中，即可实现展示用户名称、头像等效果。
- 处理时间变量 `complete_time`。在示例代码逻辑中，当服务在[卡片回传交互](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)回调的回传参数收到如下图中的参数 1 时，将会把当前实际的时间作为具体数据传给变量 `complete_time` 。
- 备注变量 `notes`。示例代码中，首先基于卡片回传交互中`form_value` 属性，使服务读取了告警卡片中用户填写的备注文本信息，之后将该信息作为具体数据传给变量 `notes`。 | 1. 在画布区域右上角，点击变量图标，弹出 **变量** 页面，点击 **添加自定义变量**。
1. 在添加变量弹窗中，参考下图，添加以下四个变量。
1. 在富文本组件的文本内容中，将光标定位至目标富文本组件内容框中，然后点击右下角的变量图标，依次添加变量。
添加完成后的效果如下所示：
5 | 配置卡片多语言 | 如果你想配置多语言卡片，你可在搭建工具中实现不同语言内容的配置。案例库中的卡片为中英双语卡片。 | 参考[为新版卡片配置多语言](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configure-multi-language-content#882164bf)了解如何配置多语言。
## 后续操作
卡片搭建完成后，需要保存、发布、并为其添加应用，才可被应用通过 API 调用。在卡片交互机器人教程中，系统已自动帮助你完成上述配置。以下为具体操作步骤说明。
1. 进入卡片编辑页面，在顶部菜单栏单击 **保存**，然后点击**发布**。
1. 在发布成功弹窗中，点击绑定应用。
1. 在 **添加自定义机器人/应用** 弹窗中，添加你创建的卡片交互机器人应用，使该应用拥有调用该卡片模板的权限。
