feishu-card

## 触发场景 **发卡片** 而非纯文字的情况： - 需要用户做选择（按钮/下拉/人员选择等） - 需要用户填写表单（输入框 + 提交按钮） - 需要展示结构化数据（表格、图表、多列布局） - 需要确认高风险操作（确认/取消双按钮） - 需要提供快速操作入口（按钮组） **纯文字**：简单回复、解释说明、无需交互时，无需发卡片。 --- ## 工具说明 | 工具 | 用途 | 主要参数 | |------|------|---------| | `feishu_send_card` | 发送卡片消息 | `chat_id` / `user_id`，`card`（JSON字符串） | | `feishu_send_form` | 发送含表单容器的卡片 | 同上，card 内须含 `form` 组件 | | `feishu_update_card` | 更新已发卡片内容 | `token`（回调中获取），`card`（新JSON） | --- ## 卡片顶层结构 ```json { "schema": "2.0", "config": { ... }, "card_link": { "url": "..." }, "header": { ... }, "body": { "elements": [ ... ] } } ``` ### config 字段速查 | 字段 | 默认值 | 说明 | |------|--------|------| | `streaming_mode` | false | 流式更新模式 | | `enable_forward` | true | 是否可转发 | | `update_multi` | true | 共享卡片（JSON 2.0 仅支持 true） | | `width_mode` | default(600px) | `compact`(400px) / `fill`(撑满) | | `enable_forward_interaction` | false | 转发后是否仍可交互 | | `summary.content` | - | 自定义聊天栏预览文案 | ### header 字段速查 | 字段 | 说明 | 枚举/格式 | |------|------|---------| | `title.tag` | 标题文本类型 | `plain_text` / `lark_md` | | `title.content` | 主标题内容 | 字符串，最多4行 | | `subtitle.content` | 副标题内容 | 字符串，最多1行 | | `template` | 标题栏颜色 | `blue` `wathet` `turquoise` `green` `yellow` `orange` `red` `carmine` `violet` `purple` `indigo` `grey` `default` | | `icon.tag` | 图标类型 | `standard_icon` / `custom_icon` | | `icon.token` | 图标库token | 如 `chat_outlined` | | `text_tag_list[].color` | 后缀标签颜色 | `neutral` `blue` `turquoise` `lime` `orange` `violet` `indigo` `wathet` `green` `yellow` `red` `purple` `carmine` | | `padding` | 标题内边距 | 默认 `12px` | ### body 字段速查 | 字段 | 默认值 | 说明 | |------|--------|------| | `direction` | `vertical` | `vertical` / `horizontal` | | `padding` | - | 如 `12px 12px` | | `horizontal_spacing` | - | `small`(4px) `medium`(8px) `large`(12px) `extra_large`(16px) 或 `Npx` | | `horizontal_align` | `left` | `left` / `center` / `right` | | `vertical_spacing` | - | 同 horizontal_spacing | | `vertical_align` | `top` | `top` / `center` / `bottom` | | `elements` | [] | 组件数组 | --- ## 组件速查 ### 容器组件 #### column_set（分栏） tag: `column_set`，不可内嵌 `form` 和 `table` ```json { "tag": "column_set", "flex_mode": "none", "horizontal_spacing": "8px", "background_style": "default", "columns": [ { "tag": "column", "width": "weighted", "weight": 1, "vertical_align": "top", "elements": [] } ] } ``` 关键枚举： - `flex_mode`: `none` / `stretch` / `flow` / `bisect` / `trisect` - `column.width`: `auto` / `weighted` / `Npx`([16,600]px) - `background_style`: `default` 或颜色枚举值 #### form（表单容器） tag: `form`，只可放在卡片根节点，不可嵌套表格/表单 ```json { "tag": "form", "name": "form_1", "elements": [ { "tag": "input", "name": "reason", "required": true }, { "tag": "button", "text": { "tag": "plain_text", "content": "提交" }, "type": "primary_filled", "form_action_type": "submit", "name": "btn_submit" } ] } ``` - 表单内交互组件必须有 `name` 字段（唯一标识） - 按钮 `form_action_type`: `submit`（提交）/ `reset`（重置） #### interactive_container（交互容器） tag: `interactive_container`，不可内嵌 `form` 和 `table` ```json { "tag": "interactive_container", "width": "fill", "height": "auto", "has_border": true, "border_color": "grey", "corner_radius": "8px", "background_style": "default", "behaviors": [{ "type": "callback", "value": { "key": "val" } }], "elements": [] } ``` 关键字段： - `background_style`: `default` / `laser` / 颜色枚举 - `behaviors.type`: `callback` / `open_url` #### collapsible_panel（折叠面板） tag: `collapsible_panel`，不可内嵌 `form`，仅支持 JSON 代码（不支持搭建工具） ```json { "tag": "collapsible_panel", "expanded": false, "header": { "title": { "tag": "plain_text", "content": "面板标题" }, "icon": { "tag": "standard_icon", "token": "down-small-ccm_outlined", "size": "16px 16px" }, "icon_position": "right", "icon_expanded_angle": -180 }, "border": { "color": "grey", "corner_radius": "5px" }, "elements": [] } ``` - `icon_position`: `left` / `right` / `follow_text` - `icon_expanded_angle`: `-180` / `-90` / `90` / `180` --- ### 内容组件 #### title（标题组件） 位于 `header` 字段，非 body elements，每卡只能有一个。见上方 header 速查。 #### div（普通文本） tag: `div` ```json { "tag": "div", "text": { "tag": "plain_text", "content": "文本内容", "text_size": "normal", "text_color": "default", "text_align": "left" } } ``` - `text.tag`: `plain_text` / `lark_md` - `text_size`: `heading-0`(30px) `heading-1`(24px) `heading-2`(20px) `heading-3`(18px) `heading-4`(16px) `heading`(16px) `normal`(14px) `notation`(12px) - `text_color`: `default` 或颜色枚举 #### markdown（富文本） tag: `markdown` ```json { "tag": "markdown", "content": "**粗体** *斜体* ~~删除线~~\n- 列表\n`code`\n> 引用", "text_align": "left", "text_size": "normal" } ``` 支持语法：`**粗体**`、`*斜体*`、`~~删除线~~`、`[链接](url)`、`<at id=open_id></at>`、`<at id=all></at>`、`<font color=red>彩色</font>`、`<text_tag color='blue'>标签</text_tag>`、`# 标题`、有序/无序列表、代码块、表格（Markdown表格语法）、`<hr>`分割线 - `text_size`: 同 div 枚举 #### img（图片） tag: `img`，img_key 通过上传图片接口获取 ```json { "tag": "img", "img_key": "img_v3_xxx", "scale_type": "crop_center", "size": "200px 150px", "corner_radius": "8px", "preview": true } ``` - `scale_type`: `crop_center` / `crop_top` / `fit_horizontal` - `size`: `Wpx Hpx` 或预设值，通栏用 `margin: "0 -12px"` #### img_combination（多图混排） tag: `img_combination` ```json { "tag": "img_combination", "combination_mode": "bisect", "img_list": [ { "img_key": "img_v3_aaa" }, { "img_key": "img_v3_bbb" } ] } ``` - `combination_mode`: `double`(双图) / `triple`(三图) / `bisect`(六宫格) / `trisect`(九宫格) #### person（人员） tag: `person` ```json { "tag": "person", "user_id": "ou_xxx", "size": "medium", "show_avatar": true, "show_name": true, "style": "normal" } ``` - `size`: `extra_small` / `small` / `medium` / `large` - `style`: `normal` / `capsule` #### person_list（人员列表） tag: `person_list` ```json { "tag": "person_list", "persons": [{ "id": "ou_xxx" }, { "id": "ou_yyy" }], "show_avatar": true, "show_name": true, "size": "medium" } ``` #### chart（图表） tag: `chart`，基于 VChart 定义 ```json { "tag": "chart", "aspect_ratio": "16:9", "color_theme": "brand", "chart_spec": { "type": "bar", "data": [{ "id": "data", "values": [{ "x": "A", "y": 10 }] }],