ai_member_xiaobian/.agents/skills/lark-base/references/lark-base-dashboard-block-create.md

base +dashboard-block-create

前置条件： 先阅读 lark-base-dashboard.md 了解整体工作流 关键： 创建前必须阅读 dashboard-block-data-config.md 了解组件类型和 data_config 结构

在仪表盘中创建一个组件（Block）。

关键约束

• type 创建后不可修改，创建时务必选对
• data_config 结构随 type 变化，不同组件类型字段不同，⚠️ 必须阅读 dashboard-block-data-config.md 了解如何构造
• 组件创建必须串行执行，不能并发

推荐命令

# 简单示例：创建一个指标卡（统计记录数）
lark-cli base +dashboard-block-create \
  --base-token xxx \
  --dashboard-id blk_xxx \
  --name "总记录数" \
  --type statistics \
  --data-config '{"table_name":"订单表","count_all":true}'

# 文本组件示例（Markdown 富文本）
lark-cli base +dashboard-block-create \
  --base-token xxx \
  --dashboard-id blk_xxx \
  --name "说明文字" \
  --type text \
  --data-config '{"text":"# 标题\n## 副标题\n**加粗** *斜体* ~~删除~~\n1. 列表1\n2. 列表2"}'

# 复杂配置用文件传入
lark-cli base +dashboard-block-create \
  --base-token xxx \
  --dashboard-id blk_xxx \
  --name "销售额趋势" \
  --type line \
  --data-config @config.json

完整流程参考 lark-base-dashboard.md 的「场景 1：从 0 到 1 创建仪表盘」

参数

参数	必填	说明
--base-token <token>	是	Base Token
--dashboard-id <id>	是	仪表盘 ID（从 +dashboard-list/get 获取）
--name <name>	是	组件名称（允许重名）
--type <type>	是	组件类型，见下方枚举值。不同 type 对应不同的 data_config 结构，常用：column(柱状图)、line(折线图)、pie(饼图)、statistics(指标卡)、text(文本)
--data-config <json>	否	数据配置 JSON，结构随 type 变化。⚠️ 必须阅读 dashboard-block-data-config.md 了解如何构造。创建时会做本地校验，更新时由后端校验
--user-id-type <type>	否	用户 ID 类型，filter 涉及人员字段时使用
--dry-run	否	预览 API 调用，不执行

type 枚举值

值	说明
column	柱状图
bar	条形图
line	折线图
pie	饼图
ring	环形图
area	面积图
combo	组合图
scatter	散点图
funnel	漏斗图
wordCloud	词云
radar	雷达图
statistics	指标卡
text	文本（支持 Markdown）

返回示例

{
  "block": {
    "block_id": "chtxxxxxxxx",
    "name": "总记录数",
    "type": "statistics",
    "data_config": {
      "table_name": "电商交易明细",
      "count_all": true
    }
  },
  "created": true
}

返回重点

字段	说明
block.block_id	组件 ID，后续编辑/删除需要用到，务必记录
block.name	组件名称
block.type	组件类型
block.data_config	实际创建的数据配置（可能包含后端自动添加的默认值）
created	是否创建成功

Caution

这是写入操作 — 执行前必须向用户确认。

参考

• lark-base-dashboard.md — dashboard 模块指引
• dashboard-block-data-config.md — data_config 结构、图表类型、filter 规则