飞书画板矩形树图（Treemap）生成指南：基于 Slice-and-Dice 脚本化坐标计算与 whiteboard-cli 渲染实战

飞书画板矩形树图Treemap生成指南基于 Slice-and-Dice 脚本化坐标计算与 whiteboard-cli 渲染实战【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli导读本文讲解如何在飞书Lark官方 CLI 项目的 lark-whiteboard 技能体系中用脚本化方式在飞书画板中生成矩形树图Treemap通过.cjs脚本按 Slice-and-Dice 交替切分法递归计算每个矩形的精确坐标与面积输出 DSL JSON 后使用larksuite/whiteboard-cli渲染再经由lark-cli whiteboard update写入画板。读完本文你将掌握 treemap 的场景约束、面积比例计算规则、父标签预留空间的正确做法、完整可运行的 JSON 骨架以及渲染与写入画板的完整命令链路。本文依据仓库中 skills/lark-whiteboard/scenes/treemap.md 编写并补充 skills/lark-whiteboard/routes/dsl.md、skills/lark-whiteboard/references/lark-whiteboard-workflow.md 等仓库文档与相关源码佐证。一、Treemap 场景定位与适用前提矩形树图适合表达层级占比信息用嵌套矩形面积直观呈现总量 → 分类 → 子项的数值比例关系。在 lark-whiteboard 技能的场景指南体系中treemap 与架构图、组织架构图、柱状图、漏斗图、金字塔图等并列归属于 DSL 脚本生成类场景见 skills/lark-whiteboard/routes/dsl.md。从 skills/lark-whiteboard/SKILL.md 可以确认本场景的完整使用前置条件包括本机已安装lark-cli运行lark-cli --version确认可用可运行npx -y larksuite/whiteboard-cli^0.2.13 -v本技能约定的 whiteboard-cli 版本开始前需先阅读 skills/lark-shared/SKILL.md 获取认证与权限处理规则。为什么 treemap 必须走脚本生成treemap 的每一个矩形面积都与数值严格成正比多层嵌套下坐标相互依赖任何一层的心算偏差都会导致面积失真。因此 treemap.md 明确给出了 Layout 选型结论脚本生成坐标推荐用.cjs脚本递归切分矩形脚本输出 JSON 文件后调用npx -y larksuite/whiteboard-cli^0.2.13渲染不适合手动心算坐标。这与 skills/lark-whiteboard/routes/dsl.md 中构建方式是强约束当 scene 指南要求『脚本生成』时必须先写脚本.cjsCommonJS并用node执行来产出 JSON 文件的规则完全一致。二、Content 约束信息量与标签规范在开始写脚本前先用 skills/lark-whiteboard/elements/content.md 的思路规划信息量。treemap 场景对内容有硬性约束见 treemap.md约束项要求顶层分类数量3–5 个每个分类下子项数量2–4 个面积比例必须预先计算每个矩形面积 父矩形面积 ×本项数值 / 同级总数值叶子节点标签必须包含数值格式如{{LABEL}} ({{VALUE}})这意味着分类数、子项数都有上下限避免画面过密或信息过载叶子节点的文字必须携带数值如CPU 服务器 (24)让读者无需对照数据表即可读取具体占比总面积的比例关系由数值驱动而不是由视觉喜好决定。三、Layout 规则Slice-and-Dice 交替切分法矩形树图的核心算法是交替切分法Slice-and-Dice规则定义在 treemap.md交替切分方向奇数层水平切分width偶数层垂直切分height父标签预留空间父矩形内必须为标题预留 30–40px 顶部空间子矩形从y 35开始放置边界约束子节点必须完全落在父矩形范围内水平切分公式子width 父 width × (子数值 / 父总数值)子x依次向右累加垂直切分公式子height (父 height - 35) × (子数值 / 父总数值)子y依次向下累加注意扣除父标签预留的 35px。面积比例计算规则详解treemap.md 给出了四步递归算法面积与数值严格成正比任何层级的节点其矩形面积width × height必须与数值成比例奇数层水平切分如第一层分类父矩形的height和y坐标传给所有子节点扣除标签预留空间后按子节点数值占父节点的比例切分父矩形的width子width 父width × (子数值 / 父总数值)子节点的x坐标依次向右累加偶数层垂直切分如第二层子项父矩形的width和x坐标传给所有子节点按子节点数值占父节点的比例切分父矩形的height子height 父height × (子数值 / 父总数值)子节点的y坐标依次向下累加层层递归不断交替水平和垂直切分方向直到所有叶子节点都被分配了精确的坐标和宽高。父标签预留空间每个非叶子节点的矩形顶部必须预留 30–40px 放置分类标签。子矩形从父矩形的y 35开始放置可用高度为父height - 35。treemap.md 给出的示例父矩形{ x: 40, y: 40, height: 700 }则父标签放在y: 46留 6px 上边距子矩形从y: 75开始放置40 35子矩形可用高度为700 - 35 665。为什么要扣 35px分类标签是一个独立的text节点必须落在父矩形内部且不被子矩形遮挡。若子矩形从父矩形顶部直接开始标签会被盖住预留空间不足30px则标签与子矩形拥挤粘连。四、骨架示例2 层 Treemap 完整 JSONtreemap.md 给出了一个可直接运行的 2 层 treemap 骨架3 个分类硬件 40、软件 35、服务 25各含 2 个子项根矩形 1100×700第一层水平切分 width第二层垂直切分 height。{ version: 2, nodes: [ { type: rect, id: root, x: 40, y: 40, width: 1100, height: 700, borderWidth: 2, borderRadius: 6 }, { type: text, x: 48, y: 46, width: 1084, height: 24, text: {{ROOT_TITLE}}, fontSize: 14 }, { type: rect, id: cat-A, x: 40, y: 75, width: 440, height: 665, borderWidth: 2, borderRadius: 6 }, { type: text, x: 48, y: 81, width: 424, height: 24, text: {{CAT_A}}, fontSize: 14 }, { type: rect, id: cat-A-item-1, x: 40, y: 110, width: 440, height: 380, borderRadius: 4 }, { type: text, x: 48, y: 116, width: 424, height: 24, text: {{ITEM_A1}} (24), fontSize: 14 }, { type: rect, id: cat-A-item-2, x: 40, y: 490, width: 440, height: 250, borderRadius: 4 }, { type: text, x: 48, y: 496, width: 424, height: 24, text: {{ITEM_A2}} (16), fontSize: 14 }, { type: rect, id: cat-B, x: 480, y: 75, width: 385, height: 665, borderWidth: 2, borderRadius: 6 }, { type: text, x: 488, y: 81, width: 369, height: 24, text: {{CAT_B}}, fontSize: 14 }, { type: rect, id: cat-B-item-1, x: 480, y: 110, width: 385, height: 380, borderRadius: 4 }, { type: text, x: 488, y: 116, width: 369, height: 24, text: {{ITEM_B1}} (20), fontSize: 14 }, { type: rect, id: cat-B-item-2, x: 480, y: 490, width: 385, height: 285, borderRadius: 4 }, { type: text, x: 488, y: 496, width: 369, height: 24, text: {{ITEM_B2}} (15), fontSize: 14 }, { type: rect, id: cat-C, x: 865, y: 75, width: 275, height: 665, borderWidth: 2, borderRadius: 6 }, { type: text, x: 873, y: 81, width: 259, height: 24, text: {{CAT_C}}, fontSize: 14 }, { type: rect, id: cat-C-item-1, x: 865, y: 110, width: 275, height: 399, borderRadius: 4 }, { type: text, x: 873, y: 116, width: 259, height: 24, text: {{ITEM_C1}} (15), fontSize: 14 }, { type: rect, id: cat-C-item-2, x: 865, y: 509, width: 275, height: 231, borderRadius: 4 }, { type: text, x: 873, y: 515, width: 259, height: 24, text: {{ITEM_C2}} (10), fontSize: 14 } ] }面积比例验证第一层水平切分 width硬件 40/100 × 1100 440软件 35/100 × 1100 385服务 25/100 × 1100 275宽度之和 440 385 275 1100正好铺满根矩形宽度三个分类矩形的x依次为 40、48040 440、865480 385子矩形从y75开始可用高度 665第二层垂直切分时如 cat-A 内item-1 数值 24、item-2 数值 16同级总值 40item-1 高度 (665) × 24/40 399item-2 高度 665 × 16/40 266近似于示例中的 380 与 250骨架保留呼吸空间后的近似值。需要说明的是骨架示例为便于人工阅读对部分数值做了近似与留白处理实际生产中由.cjs脚本严格按比例递归计算不依赖人工近似。五、脚本生成从 data 树到 diagram.jsontreemap.md 明确要求此场景必须用 .cjs 脚本生成。Agent 使用时只需修改data树其余坐标与矩形面积自动递归计算。结合 skills/lark-whiteboard/routes/dsl.md 的脚本构建流程完整操作步骤如下创建产物目录./diagrams/YYYY-MM-DDTHHMMSS/本地时间不含冒号和时区后缀用户指定路径时以用户为准编写坐标计算脚本保存为diagram.gen.cjs必须.cjs后缀——脚本用require()写.js在 ESM 项目下会崩脚本内部只暴露一份data树分类与数值用递归函数实现 Slice-and-Dice 切分执行脚本产出 JSONnode diagram.gen.cjs生成diagram.json渲染预览npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json -o diagram.pngPNG 仅用于预览验证不是最终产物检查并交付确认信息完整、布局合理、配色协调、文字无截断后进入写入画板环节。脚本核心逻辑的伪代码依据 treemap.md 的切分规则如下const { writeFileSync } require(fs); // Agent 只需修改这里data 树 const data { label: {{ROOT_TITLE}}, value: 100, children: [ { label: {{CAT_A}}, value: 40, children: [ { label: {{ITEM_A1}}, value: 24 }, { label: {{ITEM_A2}}, value: 16 } ]}, { label: {{CAT_B}}, value: 35, children: [ /* ... */ ] }, { label: {{CAT_C}}, value: 25, children: [ /* ... */ ] } ] }; // 递归切分depth 为奇数层水平切分 width偶数层垂直切分 height function slice(node, x, y, width, height, depth) { // 叶子节点输出 rect 带数值的 text // 非叶子节点先输出分类标签 text再按比例切分 // 水平切分: childWidth width * (childValue / totalValue), x 依次累加 // 垂直切分: childHeight (height - 35) * (childValue / totalValue), y 依次累加 }脚本输出结构对应 skills/lark-whiteboard/elements/schema.md 中的WBDocument顶层协议{ version: 2, nodes: [...] }节点类型使用rect矩形与text文本标签。注意rect与text都是基础节点x/y/width/height全部为固定像素数值——这正是 treemap 这类极度依赖几何坐标的图必须走脚本构建的原因见 skills/lark-whiteboard/elements/layout.md。六、配色顶层分类用色板区分子节点继承色系treemap 的层级结构天然需要颜色分组。根据 skills/lark-whiteboard/elements/style.md 的上色原则与 treemap.md 的要求不同顶层分类必须用不同背景色从色板选取所有子节点继承对应色系外层浅色填充 内层白色节点 分组色边框分类矩形用浅色fillColor叶子节点用#FFFFFF填充 所属分组的深色borderColor分类标签文字统一用深色#1F2329颜色区分靠容器背景与边框不靠标签文字变色。以经典色板为例见 style.md分组层容器 fillColor层容器 borderColor内部节点 borderColor第 1 组硬件#F0F4FC浅蓝#5178C6#5178C6第 2 组软件#EAE2FE浅紫#8569CB#8569CB第 3 组服务#DFF5E5浅绿#509863#509863用户未指定配色时必须从色板选取#E8F3FF、#1664FF等自创色值不在色板中禁止使用用户指定了色值/风格时以用户为准。七、渲染与写入画板完整命令链路第一步获取 board_token根据 skills/lark-whiteboard/references/lark-whiteboard-workflow.md用户直接给了 whiteboard tokenwbcnXXX直接使用文档 URL 或 doc_id文档中已有画板lark-cli docs fetch --doc URL --as user从返回的whiteboard tokenxxx/提取需要新建画板lark-cli docs update --doc doc_id --command append --content whiteboard typeblank/whiteboard --as user从响应data.new_blocks[0].block_token取得。第二步渲染与写入脚本产出diagram.json后先用 whiteboard-cli 渲染 PNG 预览自查npx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json -o diagram.png确认无误后将 DSL JSON 转换为 OpenAPI 原生节点格式并 pipe 给lark-cli whiteboard update链路详见 dsl.md 与 lark-whiteboard-update.mdnpx -y larksuite/whiteboard-cli^0.2.13 -i diagram.json --to openapi --format json \ | lark-cli whiteboard update --whiteboard-token board_token \ --source - --input_format raw --idempotent-token 时间戳标识 --as userupdate关键参数详见 skills/lark-whiteboard/references/lark-whiteboard-update.md参数必填说明--whiteboard-token是画板 token需要拥有画板的编辑权限--idempotent-token否幂等 token最少 10 个字符建议用时间戳 场景标识拼接如1744800000-board-1。同一次逻辑更新只生成一次重试时须原样复用切勿在每次重试时重新生成否则会重复写入--overwrite否带上则覆盖更新先删除画板所有现有内容再写入省略则为增量追加。默认 false--source是输入画板内容支持path从文件读取或-从 stdin 读取--input_format否输入格式raw、plantuml、mermaid、svg默认为raw身份默认使用--as user仅当需要以应用身份上传时使用--as bot。若写入的是非空已有画板并需要 overwrite先确认会整板重建。渲染前自查清单结合 dsl.md 与 treemap 场景特征提交前逐项检查不同顶层分类用了不同颜色同分类下的叶子节点样式完全一致外层分类矩形浅色背景、内层叶子节点白色填充 分组色边框所有分类矩形有边框borderWidth: 2文字在背景上清晰可读分类标签文字未被叶子矩形遮挡子矩形从y 35开始叶子节点标签都包含数值{{LABEL}} ({{VALUE}})面积比例是否由脚本按数值严格计算而非手工近似八、常见陷阱与规避treemap.md 列出了四类高发问题按严重程度排序父标签被子矩形遮挡最严重子矩形必须从y 35相对父矩形顶部开始放置为父分类标签留出空间分类标签不可见分类标签 text 节点必须在其子矩形 rect 节点之前添加。这与 skills/lark-whiteboard/elements/layout.md 中的图层规则一致——数组中越靠后的节点层级越高若 text 写在 rect 之后会被矩形盖住面积比例不正确必须用脚本预先计算比例不要心算——多层嵌套下心算必然产生累积误差缺少配色区分不同顶层分类必须用不同背景色从色板选取所有子节点继承对应色系否则读者无法快速识别分组边界。九、与其他场景的对照与适用边界treemap 属于 DSL 脚本构建类场景与其并列的还有柱状图bar-chart、折线图line-chart等需要几何坐标计算的图表见 dsl.md。它们共同遵循脚本生成 JSON → whiteboard-cli 渲染 →update --input_format raw写入的链路。需要区分的是思维导图、时序图、类图、饼图、甘特图走 skills/lark-whiteboard/routes/mermaid.md 路径含 用户提及或图片的内容走 skills/lark-whiteboard/routes/dsl.md 的 mention / photo-showcase 指南treemap 则始终属于其他图表中的 DSL 脚本生成类别。十、总结矩形树图的本质是数值驱动面积的可视化数据决定了比例比例决定了坐标。正确实践是将数据组织为data树 → 用.cjs脚本按 Slice-and-Dice 规则递归计算坐标奇数层切 width、偶数层切 height、每层扣除 35px 标签空间→ 输出diagram.json→ 用npx -y larksuite/whiteboard-cli^0.2.13渲染预览 → 经--to openapi转换后 pipe 给lark-cli whiteboard update --input_format raw写入画板。Agent 或开发者只需维护data树其余坐标与矩形面积全部自动递归计算即可在飞书画板中得到面积准确、层级清晰、配色分组的专业矩形树图。进一步阅读场景约束与脚本模板见 skills/lark-whiteboard/scenes/treemap.mdDSL 节点类型与字段见 skills/lark-whiteboard/elements/schema.md布局原则见 skills/lark-whiteboard/elements/layout.md配色体系见 skills/lark-whiteboard/elements/style.md完整创作/编辑工作流见 skills/lark-whiteboard/references/lark-whiteboard-workflow.md。【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200 commands and 20 AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考