sam/PhoneWork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
PhoneWork/docs/feishu/card_json_schema_2_breaking_changes.md
Yuyao Huang 26746335c4 refactor(commands): rename status command to list and update related references 
feat(feishu): update card schema to 2.0 and simplify approval card structure

docs(feishu): add documentation for card json schema 2.0 changes
2026-04-01 14:50:30 +08:00

15 KiB
Raw Blame History

卡片 JSON 2.0 版本更新说明

本文档介绍卡片 JSON 2.0 版本与 1.0 版本结构之间的不兼容变更和优化说明。了解完整的 JSON 2.0 结构数据，参考卡片 JSON 2.0 结构。

注意事项

  • 卡片 JSON 2.0 结构支持飞书客户端 7.20 及之后版本。当使用 JSON 2.0 结构的卡片发送至低于 7.20 版本的客户端时，卡片标题可正常显示，但内容将展示兜底的升级提示文案。

  • 卡片 JSON 2.0 结构暂时仅支持共享卡片，不支持独享卡片配置。即 update_multi 参数仅支持设为 true。

不兼容变更

本小节介绍卡片 JSON 2.0 版本相对于 1.0 版本所发生的不兼容变更。

卡片交互有效期变更

  • 1.0 结构：发出卡片的可交互时间为 30 天，可更新时间为 14 天（如果在第 14-30 天交互卡片，且交互回调动作为更新卡片，更新动作将不会生效）。
  • 2.0 结构：卡片可交互和可更新时间统一为 14 天。

属性校验变更

在 JSON 2.0 版本中，传入不支持的属性将报错。

1.0 结构 2.0 结构
传入不支持的属性作忽略处理 传入不支持的属性将报错

JSON 全局结构和字段变更

  • 结构变更

  • JSON 2.0 版本新增 body 字段，elements 属性放置在 body 层级下。了解 2.0 整体结构，参考卡片 JSON 2.0 结构。

    • JSON 2.0 版本不再支持通过 i18n_elements 字段设置全局多语言。你可通过 i18n_content 等局部多语言字段实现组件级别的多语言配置，详情参考配置卡片多语言。

  • fallback 字段变更

JSON 2.0 版本暂不支持使用 fallback 字段配置自定义的全局降级规则。

  • 默认值变更

JSON 2.0 版本中的 update_multi 默认值变更为 true，且暂时仅支持设为 true。update_multi 属性用于设置卡片是否为共享卡片；true 表示设置卡片为共享卡片，更新卡片的内容对所有收到这张卡片的人员可见；false 表示设置卡片为独享卡片，更新卡片的内容对他人不可见。

1.0 结构 2.0 结构
json<br>{<br>"schema": "1.0", // 不填默认为 1.0<br>"config": {<br>"update_multi": false // 默认值为 false。<br>},<br>"card_link": {},<br>"header": {},<br>"i18n_header": {},<br>"elements": [],<br>"i18n_elements": {},<br>"fallback": {}<br>}<br> json<br>{<br>"schema": "2.0", // 2.0 需主动声明<br>"config": {<br>"update_multi": true // 默认值为 true，且暂时仅支持设为 `true`<br>},<br>"card_link": {},<br>"header": {},<br>"body": { // 新增 body 字段，elements 属性放置在 body 层级下。<br>"elements": [] // 不再支持 i18n_elements 字段<br>},<br>"fallback": {}<br>}<br>

容器类组件布局属性默认值变更

  • 表单容器的 vertical_spacing 和 horizontal_spacing 字段的默认值由 16px 改为 12px，且支持开发者自定义配置。
1.0 结构 2.0 结构
json<br>{<br>"margin": "0", // 容器的外边距设置。<br>"padding": "0", // 容器的内边距设置。<br>"vertical_spacing": "16px", // 容器内组件的垂直边距设置。<br>"horizontal_spacing": "16px" // 容器内组件的水平边距设置。<br>}<br> json<br>{<br>"margin": "0",<br>"padding": "0",<br>"vertical_spacing": "12px", // 默认值变更，且支持自定义。<br>"horizontal_spacing": "12px" // 默认值变更，且支持自定义。<br>}<br>

  • 交互容器的 vertical_spacing 和 horizontal_spacing 字段的默认值由 12px 改为 4px 和 8px，且支持开发者自定义配置。
1.0 结构 2.0 结构
json<br>{<br>"margin": "0", // 容器的外边距设置。<br>"padding": "4px 12px", // 容器的内边距设置。<br>"vertical_spacing": "12px", // 容器内组件的垂直边距设置。<br>"horizontal_spacing": "12px" // 容器内组件的水平边距设置。<br>}<br> json<br>{<br>"margin": "0",<br>"padding": "4px 12px",<br>"vertical_spacing": "4px", // 默认值变更，且支持自定义。<br>"horizontal_spacing": "8px" // 默认值变更，且支持自定义。<br>}<br>

- [折叠面板](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/containers/collapsible-panel)的 `padding` 字段默认值变更： - 当折叠面板配置了边框（border）或背景色（background_color）时，标题区 `padding` 字段的默认值变更为上下边距 4px，左右边距 8px。
1.0 结构 2.0 结构
json<br>// 有边框（border）或背景色（background_color）时<br>{<br>"header": {<br>"margin": "0",<br>"padding": "8px" // 标题区的内边距。<br>},<br>"margin": "0",<br>"padding": "8px",<br>"vertical_spacing": "8px",<br>"horizontal_spacing": "8px"<br>}<br> json<br>// 有边框（border）或背景色（background_color）时<br>{<br>"header": {<br>"margin": "0",<br>"padding": "4px 8px" // 标题区的内边距默认值变更。上下边距为 4px，左右边距为 8px。<br>},<br>"margin": "0",<br>"padding": "8px",<br>"vertical_spacing": "8px",<br>"horizontal_spacing": "8px"<br>}<br>
  • 当折叠面板未配置边框（border）或背景色（background_color）时，标题区 padding 字段的默认值变更为 0，内容区的内边距默认值变更为上边距 8px，右、下、左边距 0。
1.0 结构 2.0 结构
```json
// 无边框（border）或背景色（background_color）时
{
"header": {
"margin": "0",
"padding": "8px 0 8px 0" // 标题区的内边距。
},
"margin": "0",
"padding": "0",
"vertical_spacing": "8px",
"horizontal_spacing": "8px"
}		 ```json
// 无边框（border）或背景色（background_color）时
{
"header": {
"margin": "0",
"padding": "0" // 标题区的内边距默认值变更
},
"margin": "0",
"padding": "8px 0 0 0", // 内容区的内边距默认值变更。上边距为 8px，右、下、左边距为 0px。
"vertical_spacing": "8px",
"horizontal_spacing": "8px"
}

vertical_spacing 和 horizontal_spacing 枚举值 & 映射数值变更

1.0 结构 2.0 结构
vertical_spacing 和 horizontal_spacing字段的枚举和对应的值为：
- small：4px
- medium：8px
- large：16px		 vertical_spacing 和 horizontal_spacing字段的枚举和对应的值为：
- small：4px
- medium：8px
- large：12px
- extra_large：16px

标题组件配置变更

  • 标题组件的 icon 配置结构变更，对齐其它组件：
1.0 结构 2.0 结构
json<br>{<br>"header": {<br>"title": {},<br>"icon": {<br>"img_key": "img_v2_38811724" <br>},<br>"ud_icon": {<br>"token": "chat-forbidden_outlined", <br>"style": {<br>"color": "red"<br>}<br>}<br>}<br>}<br> json<br>{<br>"header": {<br>"title": {},<br>"icon": {<br>"tag": "standard_icon",<br>"token": "chat-forbidden_outlined",<br>"color": "orange", <br>"img_key": "img_v2_38811724"<br>}<br>}<br>}<br>

图片组件不再支持通栏配置

1.0 结构 2.0 结构
支持 stretch_without_padding 通栏配置，图片的宽度将撑满卡片宽度。
json<br>{<br>"tag": "img",<br>"img_key": "img_v3_0238_073f1823-df2b-4377-86c6-e293f183622j",<br>"size": "stretch_without_padding" // 支持通栏配置，图片宽度将撑满卡片宽度。<br>}<br>		 不再支持通栏配置，但可设置 margin 字段为负数实现通栏效果。
json<br>{<br>"tag": "img",<br>"img_key": "img_v3_0238_073f1823-df2b-4377-86c6-e293f183622j",<br>"size": "crop_center",<br>"margin": "4px -12px"<br>}<br>

富文本（Markdown）组件废弃差异化跳转语法

2.0 结构不再支持以下差异化跳转语法。你可使用<link></link> 标签替代，如 <link icon='chat_outlined' url='``https://applink.feishu.cn/client/chat/xxxxx'`` pc_url='' ios_url='' android_url=''> `` 战略研讨会 </link> 。

{
    "tag": "markdown",
    "href": {
        "urlVal": {
            "url": "xxx",
            "pc_url": "xxx",
            "ios_url": "xxx",
            "android_url": "xxx"
        }
    },
    "content": "[差异化跳转]($urlVal)"
}

兜底高度 & 宽度变更

1.0 结构 2.0 结构
  • 卡片兜底高度：24px
    - 组件宽度设置的像素值如果大于父容器宽度，会收缩限制到父容器宽度，仅在交互容器中会截断展示 | - 卡片的兜底高度：40px
    - 组件宽度设置的像素值如果大于父容器宽度，将会截断展示

废弃备注组件 & 交互模块

2.0 结构不再支持备注（note）组件和交互模块（"tag" 为 "action"），相关效果可由以下组件和属性实现：

  • 备注（note）组件：可由普通文本组件配置 notation 字号、grey 字体颜色、icon 属性替代；
  • 交互模块：可由按钮（button）或折叠按钮组（overflow）组件配置合适的组件间距 (vertical_spacing 和 horizontal_spacing) 替代。

新增属性和优化说明

本小节介绍 2.0 结构新增的属性和优化点。

新增 streaming_mode 属性，支持流式更新

2.0 结构新增 streaming_mode 和 summary 字段，支持卡片流式更新、文本流式更新能力。详情参考流式更新 OpenAPI 调用指南。

{
    "schema": "2.0", // 卡片 JSON 结构的版本。默认为 1.0。
    "config": {
        "streaming_mode": true, // 卡片是否处于流式更新模式，默认值为 false。
        "summary": {
            "content": "自定义内容", // 自定义摘要信息。默认为“生成中”。
            "i18n_content": { // 摘要信息的多语言配置。了解支持的所有语种。参考。
                "zh_cn": "",
                "en_us": "",
                "ja_jp": ""
            }
        }
    }
}

新增 element_id 属性，用于操作组件

所有组件和元素（如 tag 为 plain_text 的文本元素）新增 element_id 属性，作为操作组件或元素的唯一标识。在同一张卡片内，该字段的值全局唯一。仅允许使用字母、数字和下划线，必须以字母开头，不得超过 20 字符。

{
    "tag": "button", // 组件的标签。
    "element_id": "button_1" // 操作组件时的唯一标识。
}

组件统一支持布局相关能力

卡片 JSON 2.0 结构中，各类组件统一新增了一批布局类属性。

// 卡片层级
{
    "schema": "2.0",
    "header": {
        "title": {},
        "padding": "4px" // 支持设置[0,99]px
    },
    "body": {
        "vertical_spacing": "4px", // body 内子组件的垂直间距，支持设置[0,99]px
        "padding": "4px", // body 的内边距配置，支持设置[0,99]px
        "elements": []
    }
}
// 组件
{
    "tag": "xxxx",
    // 各组件均新增的布局类属性
    "margin": "4px", // 外边距，默认值 "0"，支持范围 [-99,99]px
    // 容器类组件(含elements)新增的布局类属性，用于控制子元素排列
    "padding": "4px", // 内边距，支持范围 [0,99]px
    "direction": "vertical", // 布局方向，支持 "vertical"|"horizontal"，默认值 "vertical"
    "horizontal_spacing": "3px", // 水平间距，支持范围 [0,99]px
    "vertical_spacing": "4px", // 垂直间距，支持范围 [0,99]px
    "horizontal_align": "left", // 水平对齐，支持 "left"|"center"|"right"，默认值 "left"
    "vertical_align": "center", // 垂直对齐，支持 "top"|"center"|"bottom"，默认值 "top"
    // 其他
    "elements": []
}

普通文本组件支持配置 width 属性。可取值：

  • fill：文本的宽度将与组件宽度一致，撑满组件。
  • auto：文本的宽度自适应文本内容本身的长度。
  • [16,999]px：自定义文本宽度。
{
  "tag": "div",
  "width": "fill", // 文本宽度。支持 "fill"|"auto"|"{{[16,999]}}px"。默认值为 fill。
  }

富文本组件支持标准 markdown 语法

卡片 JSON 2.0 结构支持除 HTMLBlock 外所有标准的 Markdown 语法和部分 HTML 语法。了解 Markdown 标准语法，请参考 CommonMark Spec 官方文档。你也可以使用 CommonMark playground 预览 Markdown 效果。了解更多，参考富文本（Markdown）。

注意，在卡片的富文本组件中，以下语法的渲染效果与 CommonMark 有差异：

  • 富文本组件支持使用一个 Enter 键作为软换行（Soft Break）；支持两个 Enter 键作为硬换行（Hard Break）。软换行在渲染时可能会被忽略，具体取决于渲染器如何处理；硬换行在渲染时始终会显示为一个新行。

  • 2.0 结构支持以下 HTML 语法：

    • 开标签 <br>
    • 自闭合标签 <br/>
    • 开标签 <hr>
    • 自闭合标签 <hr/>
    • 闭合标签 <person></person>
    • 闭合标签 <local_datetime></local_datetime>
    • 闭合标签 <at></at>
    • 闭合标签 <a></a>
    • 闭合标签 <text_tag></text_tag>
    • 闭合标签 <raw></raw>
    • 闭合标签 <link></link>
    • 闭合标签 </font>，支持嵌套其它标签，如 <font color=red>red<font color=green>greenagain</font>。其它标签包括：
      • 闭合标签 <local_datetime></local_datetime>
      • 闭合标签 <at></at>
      • 闭合标签 <a></a>
      • 闭合标签 <link></link>
      • 闭合标签 <font></font>

容器类组件新增可内嵌的组件类型

JSON 2.0 结构中，表单容器、交互容器、折叠面板、分栏组件可内嵌除表单容器和表格组件外的其它所有组件。

1.0 结构 2.0 结构
  • 表单容器：不支持内嵌表格、图表、和表单容器组件；不可直接内嵌普通文本组件
    - 交互容器：仅支持内嵌普通文本、富文本、图片、备注、分栏、勾选器、交互容器组件
    - 折叠面板：不支持内嵌表单容器（form）和表格组件（table）组件
    - 分栏：不支持内嵌表格（table）、表单（form）和多图混排（img_combination）组件 | 表单容器、交互容器、折叠面板、分栏组件可内嵌除表单容器（form）和表格组件（table）外的其它所有组件。