# 表格组件 飞书卡片支持表格组件，并支持在表格中添加普通文本、富文本、选项标签、数字、人员列表、日期类型的内容。 本文档介绍表格组件的 JSON 2.0 结构，要查看历史 JSON 1.0 结构，参考[表格](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/table)。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3842e9152a953b188b307840ad65ef4a_Qjwuc2fyDl.gif?height=608&lazyload=true&maxWidth=434&width=610) ## 注意事项 - 单张卡片最多支持放置五个表格组件。若卡片配置了多语言，则单个语言最多支持放置五个表格组件。 - 当单元格内剩余空间无法完整展示内容时，末尾将省略。在客户端，用户可通过光标悬浮或点击的方式查看被省略的内容。 ## 嵌套规则 - 表格组件不可被内嵌在其它组件内，只可放在卡片根节点下。 - 表格组件不支持内嵌其它组件。 ## 组件属性 ### JSON 结构 表格组件的完整 JSON 2.0 结构如下所示： ```json { "schema": "2.0", // 卡片 JSON 结构的版本。默认为 1.0。要使用 JSON 2.0 结构，必须显示声明 2.0。 "body": { "elements": [ { "tag": "table", // 组件的标签。表格组件的固定取值为 table。 "element_id": "custom_id", // 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用组件相关接口中指定组件。需开发者自定义。 "margin": "0px 0px 0px 0px", // 组件的外边距。JSON 2.0 新增属性。默认值 "0"，支持范围 [-99,99]px。 "page_size": 5, // 每页最大展示的数据行数。支持[1,10]整数。默认值 5。 "row_height": "low", // 行高设置。默认值 low。 "row_max_height": "50px", // 当 row_height 为 auto 时，可使用该参数设置最大行高。JSON 2.0 新增属性。取值范围为 [32,999]，单位为像素。 "freeze_first_column": true, //是否冻结首列，默认 false。 "header_style": { // 在此设置表头。 "text_align": "left", // 文本对齐方式。默认值 left。 "text_size": "normal", // 字号。默认值 normal。 "background_style": "none", // 背景色。默认值 none。 "text_color": "grey", // 文本颜色。默认值 default。 "bold": true, // 是否加粗。默认值 true。 "lines": 1 // 文本行数。默认值 1。 }, "columns": [ // 在此定义列。最多支持添加 50 列，超出 50 列的内容不展示。 { // 添加列，列的数据类型为不带格式的普通文本。 "name": "customer_name", // 列的 key（键名）。必填。用于在行数据对象数组中，指定数据填充的单元格。 "display_name": "客户名称", // 列的展示名称。为空时不展示列名称。 "width": "auto", // 列宽。默认值 auto。 "data_type": "text", // 列的数据类型。 "vertical_align": "top", // 列内数据垂直对齐方式。默认值 center。 "horizontal_align": "left" // 列内数据水平对齐方式。默认数字类型的数据右对齐，其它文本左对齐。 }, { // 添加列，列的数据类型为 lark_md 文本。 "name": "customer_link", "display_name": "相关链接", "data_type": "lark_md" }, { // 添加类型为数字的列。 "name": "customer_arr", "display_name": "ARR(万元)", "data_type": "number", "format": { // 列的数据类型为 number 时的字段配置。 "symbol": "¥", // 数字前展示的货币单位。支持 1 个字符的货币单位文本。可选。 "precision": 2, // 数字的小数点位数。支持 [0,10] 的整数。默认不限制小数点位数。 "separator": true // 是否生效按千分位逗号分割的数字样式。默认值 false。 }, "width": "120px" }, { // 添加类型为选项的列。 "name": "customer_scale", "display_name": "客户规模", "data_type": "options" }, { // 添加类型为人员的列。 "name": "customer_poc", "display_name": "客户对接人", "data_type": "persons" }, { // 添加类型为日期的列。 "name": "meeting_date", "display_name": "对接时间", "data_type": "date", "date_format": "YYYY/MM/DD" }, { // 添加类型为 markdown 文本的列。 "name": "company_image", "display_name": "企业图片", "data_type": "markdown" } ], "rows": [ // 设置好列之后，在此添加与列定义对应的行数据。用 "name":VALUE 的形式，定义每一行的数据内容。name 即列的 key（键名）。 { "customer_name": "飞书科技", "customer_date": 1699341315000, "customer_scale": [ { "text": "S2", "color": "blue" } ], "customer_arr": 168, "customer_poc": [ "ou_14a32f1a02e64944cf19207aa43abcef", "ou_e393cf9c22e6e617a4332210d2aabcef" ], "customer_link": "[飞书科技](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)" }, { "customer_name": "飞书科技_01", "customer_date": 1606101072000, "customer_scale": [ { "text": "S1", "color": "red" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_01](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](image_key)" }, { "customer_name": "飞书科技_02", "customer_date": 1606101072000, "customer_scale": [ { "text": "S3", "color": "orange" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_02](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](image_key)" }, { "customer_name": "飞书科技_03", "customer_date": 1606101072000, "customer_scale": [ { "text": "S2", "color": "blue" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_03](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](image_key)" } ] } ] } } ``` ### 字段说明 表格组件的字段说明如下表。 字段 | 是否必填 | 类型 | 默认值 | 说明 ---|---|---|---|--- tag | 是 | String | / | 组件的标签。表格组件的固定取值为 `table`。 element_id | 否 | String | 空 | 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用[组件相关接口](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card-element/create)中指定组件。在同一张卡片内，该字段的值全局唯一。仅允许使用字母、数字和下划线，必须以字母开头，不得超过 20 字符。 margin | 否 | String | 0 | 组件的外边距。JSON 2.0 新增属性。值的取值范围为 [-99,99]px。可选值：
- 单值，如 "10px"，表示组件的四个外边距都为 10 px。
- 双值，如 "4px 0"，表示组件的上下外边距为 4 px，左右外边距为 0 px。使用空格间隔（边距为 0 时可不加单位）。
- 多值，如 "4px 0 4px 0"，表示组件的上、右、下、左的外边距分别为 4px，12px，4px，12px。使用空格间隔。 page_size | 否 | Number | 5 | 每页最大展示的数据行数。支持 [1,10] 整数。 row_height | 否 | String | low | 表格的行高。单元格高度如无法展示一整行内容，则上下裁剪内容。可取值：
- low：低
- middle：中
- high：高
- auto：行高与自适应内容。JSON 2.0 新增枚举，V7.33 及以上客户端版本支持。
- [32,124]px：自定义行高，单位为像素，如 40px。取值范围是 [32,124] row_max_height | 否 | String | 124px | 当 row_height 为 auto 时，可使用该参数设置最大行高。若内容超过该值，将被裁剪。取值范围为 [32,999]，单位为像素。JSON 2.0 新增属性，V7.33 及以上客户端版本支持。 header_style | 否 | header_style | / | 表头样式风格。详见下方 `header_style` 字段说明。 freeze_first_column | 否 | Boolean | false | 是否冻结首列。可取值：
- true：冻结首列。即左右滚动表格时不滚动首列，其余列叠加展示在首列底下
- false：不冻结首列。即左右滚动表格时所有表格均做滚动 columns | 是 | column[] | [] | 列对象数组。详见下方 `column` 字段说明。 rows | 是 | JSON | [] | 行对象数组。与列定义对应的数据。用 `"name":VALUE` 的形式，定义每一行的数据内容。`name`即你自定义的列标记。 #### `header_style` 字段说明 `header_style` 用于设置表头的样式、风格等。`header_style` 的子字段如下表所示。 字段 | 是否必填 | 类型 | 默认值 | 说明 ---|---|---|---|--- text_align | 否 | String | left | 表头文本对齐方式。可取值：
- left：左对齐
- center：居中对齐
- right：右对齐
**注意**：卡片搭建工具上暂时不支持 `text_align` 属性。 text_size | 否 | String | normal | 表头文本大小。可取值：
- normal：正文（14px）
- heading：标题（16px） background_style | 否 | String | none | 表头背景色。可取值：
- grey：灰色
- none：无背景色 text_color | 否 | String | default | 文本颜色。可取值：
- default：客户端浅色主题模式下为黑色；客户端深色主题模式下为白色
- grey：灰色 bold | 否 | Boolean | true | 表头文本是否加粗。可取值：
- true：加粗
- false：不加粗 lines | 否 | Number | 1 | 表头文本的行数。支持大于等于 1 的整数。 #### **`column`** **字段说明** `column` 用于定义表格的列，包括列的 key （键名）、展示名称、该列数据的类型、宽度、对齐方式等。最多支持添加 50 列，超出 50 列的内容不展示。 字段 | 是否必填 | 类型 | 默认值 | 说明 ---|---|---|---|--- name | 是 | String | 空 | 列的 key（键名）。必填。用于在行数据对象数组中，指定数据填充的单元格。 display_name | 否 | String | 空 | 在表头展示的列名称。不填或为空则不展示列名称。 width | 否 | String | auto | 列宽度。可取值：
- auto：自适应内容宽度
- 自定义宽度：自定义表格的列宽度，如 120px。取值范围是 [80px,600px] 的整数
- 自定义宽度百分比：自定义列宽度占当前表格画布宽度的百分比（表格画布宽度 = 卡片宽度-卡片左右内边距），如 25%。取值范围是 [1%,100%] vertical_align | 否 | String | center | 列内数据垂直对齐方式。可选值：
- top：顶部对齐
- center：中间对齐
- bottom：底部对齐 horizontal_align | 否 | String | 数字（number）类型数据的默认值为 right；
其它类型数据的默认值为 left | 列内数据水平对齐方式。可选值：
- left：左对齐
- center：居中对齐
- right：右对齐 data_type | 是 | String | text | 列数据类型。可选值如下所示。了解不同类型用法，参考 `data_type` 字段说明一节。
- text：不带格式的普通文本。为 `data_type` 默认值。
- lark_md：支持部分 markdown 格式的文本。飞书 v7.10 及之后版本支持。详情参考[普通文本-lark_md 支持的 Markdown 语法](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/plain-text)
- options：选项标签。标签中的文本内容不可过长，否则可能会导致 PC 端或移动端内容显示不完整。如果文本过长，可使用 text 或者 lark_md 类型
- number：数字。默认在单元格中右对齐展示。若选择该数据类型，你可继续在 `column` 中添加 `format` 字段，设置数字的格式属性
- persons：人员列表。为用户名称+头像样式
- date：日期时间。需输入 Unix 标准毫秒级时间戳，飞书客户端将按用户本地时区展示日期时间。飞书 v7.6 及之后版本支持
- markdown：支持完整 Markdown 语法的文本内容。详情参考[富文本（Markdown）组件](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/rich-text)。飞书 v7.14 及之后版本支持 format | 否 | Object | / | 该字段仅当 `data_type` 为 `number` 时生效，你可以在该字段内选择设置小数点位数、货币单位以及千分位样式。 └ precision | 否 | Int | 空 | 数字的小数点位数。默认不限制小数点位数，原样透传展示开发者输入的数字。可填 0~10 的整数。小数点位数为 0 表示取整数。 └ symbol | 否 | String | 空 | 数字前的货币单位。不填或为空不展示。可填 1 个字符的货币单位文本，如 “¥”。 └ separator | 否 | Boolean | false | 是否生效按千分位逗号分割的数字样式。 date_format | 否 | String | 空 | 该字段仅当 `data_type` 为 `date` 时生效。你可按需选择以下日期时间占位符，并使用任意分隔符组合。
- YYYY：年
- MM：月
- DD：日
- HH：小时
- mm：分钟
- ss：秒
推荐使用以下日期格式。默认按 RFC 3339 标准格式展示日期时间。
- YYYY/MM/DD
- YYYY/MM/DD HH:mm
- YYYY-MM-DD
- YYYY-MM-DD HH:mm
- DD/MM/YYYY
- MM/DD/YYYY #### `data_type` 字段说明 `data_type` 用于指定列的数据类型。`data_type` 支持的枚举值及详细说明如下所示。 data_type 枚举 | 描述 | 对应行的数据结构与示例 ---|---|--- text | 不带格式的普通文本。为 data_type 默认值。 | 结构：
```json
"name":"plain text" // 不填或为空时展示空单元格，非字符串类型转换为字符串展示
```
示例：
```json
"business_domain_name": "飞书卡片"
``` lark_md | 支持部分 markdown 格式的文本。详情参考[普通文本-lark_md 支持的 Markdown 语法](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/plain-text)。 | 结构：
```json
"name":"[文字链接](https://www.feishu.cn)" // 不填或为空时展示空单元格，非字符串类型转换为字符串展示
```
示例：
```json
"customer_link": "[飞书科技_01](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)"
``` options | 选项标签。支持使用 color 参数自定义标签颜色。color 枚举值及展示效果如下所示。默认值为 blue。
**注意**：标签中的文本内容不可过长，否则可能会导致 PC 端或移动端内容显示不完整。如果文本过长，可使用 text 或者 lark_md 类型。
![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7dce9769aa1475bb36bada6533775403_nCnDT2EAmq.png?height=494&lazyload=true&width=1722) | 结构：
```json
// 支持仅展示一个默认样式的标签
"name":"option"
// 支持展示多个自定义样式的标签
"name":[
{
"text":"option 1",
"color":"red"
},
{
"text":"option 2",
"color":"green"
}
]
```
示例：
```json
"customer_scale": [
{
"text": "S2",
"color": "green"
}
]
``` number | 数字。默认在单元格中右对齐展示。支持添加 format 字段，设置数字的格式属性。详情参考 format 字段说明。 | 结构：
```json
"name":NUMBER
```
示例：
```json
"customer_arr": 26.57774928467545
``` persons | 人员列表。为用户名称+头像样式。支持传入用户 ID 指定人员，用户 ID 类型可以是 user_id、open_id、union_id和 lark_id。了解更多 ID 相关信息，参考[用户身份概述](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。
**注意**：当用户 ID 无效时，将展示“未知用户”样式。 | 结构：
```json
"name":[
"user_id_1",
"user_id_2",
…
] //展示多人员
或
"name":"user_id" //展示单人员
```
示例：
```json
"customer_name": "ou_c99c5f35d542efc7ee492afe11af19ef"
``` date | 日期时间。需输入 Unix 标准毫秒级时间戳，飞书客户端将按用户本地时区展示日期时间。
支持添加 date_format 字段，设置日期的格式属性。默认按 RFC 3339 标准格式展示日期时间。详情参考 date_format 字段说明。 | 结构：
```json
name":NUMBER
```
示例：
```json
"customer_date": 1606101072000 // 毫秒级时间戳
``` markdown | 支持完整 Markdown 语法的文本内容。详情参考[富文本（Markdown）](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/content-components/rich-text)组件。 | 结构：
```json
"name":"markdown text" // 不填或为空时展示空单元格，非字符串类型转换为字符串展示
```
示例：
```json
"company_image": "![image.png](img_v3_02cc_bf88cdee-6650-4b39-987c-f8e87c3227fg)"
``` ## Demo 示例 以下 JSON 2.0 结构的示例代码可实现如下图所示的卡片效果。 ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3842e9152a953b188b307840ad65ef4a_Q5yCXHkNtm.gif?height=608&lazyload=true&maxWidth=434&width=610) ```json { "schema": "2.0", "header": { "template": "blue", "title": { "content": "表格组件示例", "tag": "plain_text" } }, "body": { "elements": [ { "tag": "table", "page_size": 5, "row_height": "auto", "header_style": { "text_align": "left", "text_size": "normal", "background_style": "none", "text_color": "grey", "bold": true, "lines": 1 }, "columns": [ { "name": "customer_name", "display_name": "客户名称", "data_type": "text", "horizontal_align": "left", "vertical_align": "top", "width": "auto" }, { "name": "customer_scale", "display_name": "客户规模", "data_type": "options", "horizontal_align": "left", "vertical_align": "top", "width": "auto" }, { "name": "customer_arr", "display_name": "ARR(万元)", "data_type": "number", "format": { "symbol": "¥", "precision": 2, "separator": true }, "width": "auto" }, { "name": "customer_poc", "display_name": "跟进人", "data_type": "persons", "horizontal_align": "left", "vertical_align": "top", "width": "auto" }, { "name": "customer_date", "display_name": "签约日期", "data_type": "date", "date_format": "YYYY/MM/DD", "width": "auto" }, { "name": "customer_link", "display_name": "相关链接", "data_type": "lark_md", "width": "auto" }, { "name": "company_image", "display_name": "企业图片", "data_type": "markdown" } ], "rows": [ { "customer_name": "飞书科技", "customer_date": 1699341315000, "customer_scale": [ { "text": "S2", "color": "blue" } ], "customer_arr": 168, "customer_poc": [ "ou_14a32f1a02e64944cf19207aa43abcef", "ou_e393cf9c22e6e617a4332210d2aabcef" ], "customer_link": "[飞书科技](/document-mod/index?fullPath=/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](img_v3_02cc_bf88cdee-6650-4b39-987c-f8e87c3227fg)" }, { "customer_name": "飞书科技_01", "customer_date": 1606101072000, "customer_scale": [ { "text": "S1", "color": "red" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_01](/document-mod/index?fullPath=/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](img_v3_02cc_bf88cdee-6650-4b39-987c-f8e87c3227fg)" }, { "customer_name": "飞书科技_02", "customer_date": 1606101072000, "customer_scale": [ { "text": "S3", "color": "orange" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_02](/document-mod/index?fullPath=/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](img_v3_02cc_bf88cdee-6650-4b39-987c-f8e87c3227fg)" }, { "customer_name": "飞书科技_03", "customer_date": 1606101072000, "customer_scale": [ { "text": "S2", "color": "blue" } ], "customer_arr": 168.23, "customer_poc": "ou_14a32f1a02e64944cf19207aa43abcef", "customer_link": "[飞书科技_03](/document-mod/index?fullPath=/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message-reaction/emojis-introduce)", "company_image": "![image.png](img_v3_02cc_bf88cdee-6650-4b39-987c-f8e87c3227fg)" } ] } ] } } ```