108 lines
6.0 KiB
Markdown
108 lines
6.0 KiB
Markdown
# 卡片 2.0 组件大纲
|
||
|
||
Card 2.0 组件按**容器 / 展示 / 交互**三类，均通过 `tag` 字段声明。先在下表按用途选组件，再点明细看字段：有明细文件的点 `components/<tag>.md`（完整字段+示例+易错点），低频组件点链接看官方文档。
|
||
|
||
## 根结构
|
||
|
||
顶层固定四字段，先搭骨架再往 `body.elements` 填组件。以下为**推荐完整骨架**（含 type scale、light/dark color token、header 三件套）：
|
||
|
||
```json
|
||
{
|
||
"schema": "2.0",
|
||
"config": {
|
||
"update_multi": true,
|
||
"width_mode": "default",
|
||
"style": {
|
||
"text_size": {
|
||
"title": { "default": "heading-2", "pc": "heading-2", "mobile": "heading-3" },
|
||
"body": { "default": "normal", "pc": "normal", "mobile": "normal" },
|
||
"caption": { "default": "notation", "pc": "notation", "mobile": "notation" }
|
||
},
|
||
"color": {
|
||
"cus-primary": { "light_mode": "rgba(30,120,255,1)", "dark_mode": "rgba(80,150,255,1)" },
|
||
"cus-primary-bg": { "light_mode": "rgba(30,120,255,0.08)", "dark_mode": "rgba(80,150,255,0.12)" },
|
||
"cus-muted": { "light_mode": "rgba(100,106,115,1)", "dark_mode": "rgba(150,155,163,1)" }
|
||
}
|
||
}
|
||
},
|
||
"header": {
|
||
"title": { "tag": "plain_text", "content": "卡片标题" },
|
||
"subtitle": { "tag": "plain_text", "content": "副标题：一句上下文（时间/来源/状态）" },
|
||
"template": "blue",
|
||
"icon": { "tag": "standard_icon", "token": "lark-logo_colorful" },
|
||
"text_tag_list": [
|
||
{ "tag": "text_tag", "text": { "tag": "plain_text", "content": "状态标签" }, "color": "blue" }
|
||
]
|
||
},
|
||
"body": { "direction": "vertical", "padding": "12px 12px 20px 12px", "elements": [] }
|
||
}
|
||
```
|
||
|
||
> **按需裁剪**：`subtitle` / `text_tag_list` / color token 按实际诉求取舍，不强制全用。组件里用 `"text_size": "title"` / `"caption"` 引用 token，用 `"font_color": "cus-muted"` 引用颜色 token；主色系变化时只需改 config 里的 RGBA，全卡自动跟随。
|
||
|
||
- `schema` 必须显式为 `"2.0"`，否则按 1.0 渲染。`header` 详见 `components/header.md`。
|
||
- **元素通用字段**（所有 `elements[]` 组件）：`tag`(必填) · `element_id`(卡内唯一，字母开头、≤20 字符) · `margin`(外边距 [-99,99]px)。
|
||
- `card_link`（整卡跳转）：`{url, pc_url, ios_url, android_url}`，至少填 `url`；某端禁跳设 `lark://msgcard/unsupported_action`。
|
||
- 硬限制：单卡 ≤ **200** 元素；需客户端 **≥ 7.20**（旧版仅显示 header）。
|
||
- 颜色 / 图标枚举见 `resource/colors.md` · `resource/icons.md`。
|
||
|
||
**config**（全局行为，可整体省略）：
|
||
|
||
| 字段 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `update_multi` | true | 共享卡片，v2 仅支持 true |
|
||
| `width_mode` | default | `default`(≤600px) / `compact`(400px) / `fill`(撑满) |
|
||
| `enable_forward` | true | 是否允许转发 |
|
||
| `summary` | — | 会话列表预览：`{content, i18n_content:{zh_cn,en_us,…}}` |
|
||
| `streaming_mode` | false | 流式更新模式（配 `streaming_config`） |
|
||
| `style.text_size` | — | 自定义字号 token，格式 `{"<名称>":{default,pc,mobile}}`；名称可自定义（如 `title`/`caption`），组件 `text_size` 引用该名称 |
|
||
| `style.color` | — | 自定义颜色 token，格式 `{"<名称>":{light_mode,dark_mode}}`（RGBA）；名称可自定义（如 `cus-primary`），组件 `font_color`/`background_style` 等字段引用 |
|
||
|
||
> 多语言：`config.locales` 限定生效语种、`use_custom_translation` 优先用自带 i18n。
|
||
|
||
**body 布局字段**（均 v2 新增）：`direction`(vertical/horizontal) · `padding`([0,99]px) · `horizontal_spacing`/`vertical_spacing`(`small`4/`medium`8/`large`12/`extra_large`16 或 px) · `horizontal_align`/`vertical_align`。
|
||
|
||
---
|
||
|
||
## 容器类（布局 / 组织交互）
|
||
|
||
| 组件 | 用途 |
|
||
|---|---|
|
||
| [column_set](components/column_set.md) | 横向分栏，多列图文对齐（数据表、字段对、列表） |
|
||
| [collapsible_panel](components/collapsible_panel.md) | 折叠面板，收纳备注/长文本等次要信息 |
|
||
| [form](components/form.md) | 表单容器，批量录入表单项后一次提交 |
|
||
| [interactive_container](components/interactive_container.md) | 整块可点击区域，可统一定义样式与交互 |
|
||
| [循环容器](components/recycling_container.md) | 批量渲染同版式不同数据（仅搭建工具） |
|
||
|
||
## 展示类（无交互）
|
||
|
||
| 组件 | 用途 |
|
||
|---|---|
|
||
| [header](components/header.md) | 卡片标题区：主/副标题、后缀标签、主题色 |
|
||
| [div](components/div.md) | 普通文本，带前缀图标、字段对 |
|
||
| [markdown](components/markdown.md) | 富文本，最常用；@人、彩色、链接、列表、表格等 |
|
||
| [img](components/img.md) | 单图 |
|
||
| [img_combination](components/img_combination.md) | 多图拼排（双图/三图/宫格） |
|
||
| [person](components/person.md) | 单个人员头像/姓名 |
|
||
| [person_list](components/person_list.md) | 多个人员头像/姓名 |
|
||
| [chart](components/chart.md) | VChart 图表（折线/柱/饼/词云等） |
|
||
| [table](components/table.md) | 多列数据表（只能放根节点） |
|
||
| [hr](components/hr.md) | 分割线 |
|
||
|
||
## 交互类
|
||
|
||
| 组件 | 用途 |
|
||
|---|---|
|
||
| [button](components/button.md) | 按钮：回调 / 跳转 / 表单提交 |
|
||
| [input](components/input.md) | 文本输入框（多嵌在 form 内） |
|
||
| [overflow](components/overflow.md) | 折叠按钮组，收纳多个操作 |
|
||
| [select_static](components/select_static.md) | 下拉单选 |
|
||
| [multi_select_static](components/multi_select_static.md) | 下拉多选 |
|
||
| [select_person](components/select_person.md) | 人员单选 |
|
||
| [multi_select_person](components/multi_select_person.md) | 人员多选 |
|
||
| [date_picker](components/date_picker.md) | 日期选择器 |
|
||
| [picker_time](components/picker_time.md) | 时间选择器 |
|
||
| [picker_datetime](components/picker_datetime.md) | 日期时间选择器 |
|
||
| [select_img](components/select_img.md) | 图片选择（单/多选） |
|
||
| [checker](components/checker.md) | 勾选器，任务勾选回调 |
|