Appearance
卡片资源
卡片用于把插件、工作流或应用产生的数据组织成结构化消息。与纯文本相比，卡片可以同时呈现标题、说明、图片、状态标签、评分、音视频、表单控件和操作按钮，更适合结果摘要、审批通知、业务提醒、商品或知识推荐等场景。
卡片资源归属于当前工作空间。搭建器中的修改先保存为草稿；只有发布版本才能被调用方稳定绑定、复制到其他工作空间或用于正式输出。
本栏目导航
入口与使用边界
- 页面入口：资源 > 低代码 > 卡片。
- 页面地址：
/workbench/resource-library?type=card。 - 列表能力：按创建者和发布状态筛选，按名称搜索，并通过行操作复制、跨空间复制或删除。
- 资源边界：复制会创建拥有独立标识和生命周期的新卡片，源卡片后续更新不会自动同步到副本。
- 发布边界：草稿只供当前搭建器继续编辑；调用方通常继续使用上一次已发布版本。
卡片负责展示和交互，不负责完成复杂业务判断。数据加工、权限判断和外部接口调用应放在插件或工作流中，卡片只消费经过约束的输出字段。
创建卡片
在资源库右上角点击 资源 > 卡片，填写名称和描述后确认。
图 1：创建卡片。先确认当前工作空间和卡片页签，再填写稳定、可识别的基础信息。
| 字段 | 规则与建议 |
|---|---|
| 卡片名称 | 必填，最多 30 个字符。建议体现业务场景和输出用途，例如“工单处理结果卡片” |
| 卡片描述 | 可选，最多 500 个字符。建议说明数据来源、展示内容、使用位置和关键交互 |
创建成功后会直接进入卡片搭建器。不要用“测试”“未命名”等名称长期发布；同一空间内存在多个相似卡片时，调用方很难判断应该绑定哪一个。
搭建器结构
卡片搭建器由顶部资源区、左侧素材区、中间画布、右侧属性面板和底部工具栏组成。
图 2：卡片搭建器。通常先选择布局，再拖入组件，最后选中组件完成属性和数据绑定。
顶部资源区
- 返回与名称：返回资源库，查看发布状态，并修改卡片名称。
- 基本信息：查看或调整卡片说明等配置。
- 历史：查看发布版本，并在确认影响后回滚。
- 预览：在不离开搭建器的情况下检查真实渲染结果。
- 发布：填写版本号和版本描述，生成可供调用方使用的版本。
绿色发布标识表示当前卡片已经存在发布版本，不表示画布上的最新草稿已经发布。修改后仍要重新预览并发布。
左侧素材区
左侧提供三类工作区：
- 模板：使用已保存的个人模板或官方模板快速生成结构。
- 组件：选择布局、基础组件和表单组件。
- 结构：查看当前卡片的层级结构，适合定位嵌套组件和调整选中项。
中间画布
画布展示卡片当前结构和内容。将布局或组件拖入画布后，可以继续选择、移动、复制或删除。复杂卡片建议从外层布局开始，再逐层放入内容组件，避免产生难以维护的深层嵌套。
右侧属性面板
选中画布中的组件后，右侧显示对应配置。不同组件可能提供文本、样式、尺寸、对齐、数据绑定、显示条件和交互等配置。没有选中组件时，面板会提示先选择一个元素。
底部工具栏
- 桌面端与移动端视图切换。
- 撤销和重做。
- 将当前设计保存为模板。
- 清空当前卡片。
- 查看搭建帮助。
清空卡片会影响整个草稿，操作前应先确认是否需要保存模板。撤销/重做只用于当前编辑过程，不能替代已发布版本和历史记录。
布局与组件
布局组件
| 布局 | 适用场景 | 使用建议 |
|---|---|---|
| 单列布局 | 通知、详情、摘要等从上到下阅读的内容 | 默认优先选择，移动端适配最稳定 |
| 多列布局 1:1:1 | 并列指标、操作入口、紧凑信息组 | 控制列内文字长度，避免移动端过度拥挤 |
| 列表布局 | 重复的记录、步骤或推荐项 | 配合数组变量和统一子项结构使用 |
| 网格布局 | 图片、指标或功能入口矩阵 | 保持单元格信息密度和尺寸一致 |
| 横滑布局 | 移动端横向浏览多个项目 | 提供清晰的首项内容，避免隐藏关键操作 |
| 浮动布局 | 徽标、角标或局部叠加效果 | 谨慎处理遮挡、层级和不同尺寸下的位置 |
基础组件
| 组件 | 主要用途 | 注意事项 |
|---|---|---|
| 标题 | 展示卡片主标题 | 每张卡片只允许一个标题组件；层级标题可用文本样式表达 |
| 文本 | 说明、摘要、正文和辅助信息 | 对动态内容限制长度，并处理空值 |
| 按钮 | 触发跳转或业务动作 | 按钮文案应明确结果，危险操作需要二次确认 |
| 图标 | 表示状态或辅助识别 | 不要只靠图标传递关键信息 |
| 图片 | 封面、缩略图、二维码等 | 使用可信地址，准备加载失败和比例不一致的情况 |
| 标签 | 状态、分类和短文本强调 | 枚举值应稳定，颜色含义保持一致 |
| 评分 | 展示等级或评分 | 明确取值范围和空值展示方式 |
| 分割线 | 划分信息区块 | 避免过多分割造成视觉噪声 |
| 音频、视频 | 展示多媒体内容 | 检查格式、访问权限、加载体积和终端兼容性 |
表单组件
输入框、下拉选择和按钮选择等表单组件可以收集用户输入或提供选项。配置时应明确：
- 字段名称、提示语和默认值。
- 是否必填、允许的长度和选项范围。
- 提交或点击后的目标动作。
- 用户重复点击、取消或输入非法值时的处理方式。
卡片不是完整业务表单系统。涉及大量字段、跨步骤校验或敏感数据时，优先跳转到受控页面处理。
变量与动态数据
卡片变量用于把调用方的输出映射到组件内容。搭建器支持 String、Number、Boolean、Object 和 Array 类型，并可为变量配置默认值。
图 3：变量面板。先建立稳定的数据契约，再在组件属性中绑定变量。
创建变量
- 切换到 变量 面板。
- 点击 新建变量。
- 使用有业务含义的变量名，并选择准确类型。
- 按需要填写默认值。
- 保存后，在组件属性中通过
{{变量名}}绑定。
对象字段可以按实际结构继续引用；数组变量适合列表或网格中的循环渲染。变量名、类型和字段路径构成调用方与卡片之间的契约，不应仅为了页面展示方便随意改名。
变量设计建议
- 用
title、status、items等语义化名称，不使用data1、value2。 - 对可能缺失的字段设置可理解的默认展示，不直接渲染
undefined或空对象。 - 数字、布尔和数组不要伪装成字符串；类型不一致会导致条件、循环或组件渲染异常。
- 数组项应保持统一结构，并限制最大条数，避免卡片无限增长。
- 删除变量前先检查所有组件引用；删除后残留的变量表达式不会自动变成正确内容。
- 不把令牌、密钥、完整内部响应或无权展示的个人信息传入卡片变量。
与插件、工作流对齐
插件工具或工作流输出字段必须与卡片变量的名称、类型和层级一致。建议先定义稳定输出契约，再设计卡片；如果先做卡片，也要在绑定前补齐字段说明和示例值。
变更已发布的输出字段时，应按以下顺序处理：
- 确认新增、删除或改名字段对现有卡片的影响。
- 在卡片草稿中更新变量和组件引用。
- 使用真实样例数据预览。
- 发布卡片新版本。
- 重新检查并更新插件、工作流或应用中的绑定关系。
模板复用
完成一组通用布局后，可以通过底部工具栏保存为个人模板。模板会保存当前组件结构，并包含当前设计引用的变量，适合复用统一的通知、摘要或列表样式。
使用模板前要注意：
- 模板名称最多 30 个字符，应体现用途和适用数据结构。
- 使用模板会用模板内容替换当前组件和变量；有未保存设计时应先确认。
- 模板只是设计起点，后续修改不会自动同步到已经使用它的卡片。
- 删除模板通常不可恢复；确认没有团队约定或后续复用需求后再删除。
预览与终端适配
编辑过程中可以在底部切换桌面端和移动端视图，也可以点击顶部 预览 查看更接近最终输出的卡片。
图 4：卡片预览。需要滚动检查全部内容，不能只确认首屏。
预览至少检查：
- 标题、文本、图片和标签是否完整显示。
- 长文本、空值、极大数字和超长数组是否破坏布局。
- 桌面端与移动端是否都能阅读和操作。
- 按钮、选择控件和链接的文案、状态及目标是否正确。
- 图片、音频和视频资源加载失败时是否仍可理解。
- 条件显示是否与变量值一致。
- 颜色对比、字号、点击区域和纯键盘操作是否可接受。
不要只使用默认值预览。至少准备正常数据、最小数据、空数据和边界数据四组样例。
草稿、发布与版本
草稿与自动保存
搭建器会自动保存当前草稿。自动保存成功不等于发布成功，也不会立即改变调用方正在使用的版本。离开页面前应观察保存状态，网络异常时不要假设最后一次修改已经写入。
卡片至少需要存在一个有效内容块才能预览和发布。只有空画布或无效结构时，应先补齐组件和必要配置。
发布版本
点击 发布 后填写版本信息。
图 5：发布卡片。版本号用于区分稳定输出，版本描述用于记录本次变化和影响范围。
| 字段 | 规则与建议 |
|---|---|
| 版本号 | 必填，最多 20 个字符。采用团队统一规则，例如 1.2.0 |
| 版本描述 | 可选，最多 200 个字符。写清新增字段、样式变化、交互调整和需要重新绑定的调用方 |
发布前会再次保存草稿。发布成功后，如果页面提示需要重新绑定卡片信息，应回到插件工具、工作流或应用中重新选择或确认卡片，避免调用方仍使用旧绑定。
发布历史与回滚
历史面板会按版本展示版本号、发布状态、版本描述和时间。选择历史版本后可以回滚。
图 6：发布历史。回滚会用历史快照覆盖当前画布，执行前应确认当前草稿是否需要保留。
回滚不是“查看旧版本”。回滚后应重新检查变量、资源链接和预览结果，再决定是否发布新的版本。已经被调用方消费过的历史输出不会因为回滚自动改变。
绑定与调用
插件工具绑定
插件工具支持三种卡片方式：
- 不使用卡片：直接返回文本或结构化结果。
- 根据工具响应自动生成卡片：适合快速验证或结构简单的输出。
- 绑定已有卡片：选择当前空间中已发布的卡片，用于稳定、可设计的业务展示。
绑定已有卡片时，要把工具输出字段映射到卡片变量，并用真实工具响应测试。工具或卡片任一方升级后，都要重新检查字段契约和绑定状态。
工作流与应用使用
工作流可以把最终输出组织成卡片需要的数据结构，应用或智能体再渲染已发布卡片。建议把数据清洗和异常处理放在流程内：当数据源失败时，返回明确的空状态或错误状态，而不是让卡片收到不完整结构。
跨空间复制
卡片必须先发布，才能复制到其他工作空间。复制后应检查：
- 目标空间是否存在相同插件、工作流和媒体资源权限。
- 卡片变量是否仍与目标调用方输出一致。
- 图片、音视频和链接是否可以从目标环境访问。
- 新副本是否需要使用独立名称、版本和负责人。
发布前检查清单
- [ ] 名称和描述能够区分业务用途。
- [ ] 画布至少包含一个有效内容块，没有误留测试组件。
- [ ] 布局在桌面端和移动端均可阅读。
- [ ] 所有变量名称、类型、路径和默认值都与调用方一致。
- [ ] 正常、空值、超长文本、长数组和媒体失败场景均已预览。
- [ ] 按钮和表单控件具备明确结果、校验和重复操作保护。
- [ ] 没有密钥、内部地址或越权个人信息进入卡片。
- [ ] 版本号和版本描述符合团队规则。
- [ ] 发布后已重新检查插件、工作流或应用绑定。
常见问题
为什么搭建器里已经修改，调用方仍显示旧内容？
当前修改可能只保存在草稿中。确认卡片已发布新版本，并根据页面提示重新检查调用方绑定。
为什么组件显示空白或变量原样出现？
检查调用方是否提供对应字段、字段路径是否正确、类型是否匹配，以及变量是否已经被删除或改名。用一份实际响应逐字段对照，比只看示例值更可靠。
为什么无法预览或发布？
确认画布至少存在一个有效内容块，并检查组件必填配置、变量引用和媒体地址。空画布或无效结构会阻止后续操作。
为什么移动端布局拥挤？
减少并列列数和长文本，优先使用单列、列表或横滑布局，并在移动视图中检查真实最长数据。不要依赖桌面端缩小后的视觉效果判断移动适配。
回滚会恢复调用方绑定吗？
不会。回滚主要恢复卡片画布快照；调用方绑定、外部资源权限和历史产生的数据不会自动恢复。回滚后仍需预览、发布并检查绑定。