用途:生成 .excalidraw 纯 JSON 白板文件,用于 Obsidian Excalidraw 插件 2.0+(基于 Excalidraw JSON v2 / v0.17+)绘制架构图、流程图、思维导图。
主要能力:
- 文件结构:顶级字段含 type、version、source、elements、appState、files。elements 数组索引决定渲染层级,0 为最底层。
- 元素通用字段:id(唯一,短随机 8-12 位)、type、x/y/width/height(建议 Math.round 避免亚像素模糊)、angle(弧度)、strokeColor、backgroundColor、fillStyle、strokeWidth、strokeStyle、roughness、opacity、groupIds、roundness、seed、version、versionNonce、isDeleted、boundElements、updated、link、locked、frameId。
- 容器类:rectangle、diamond、ellipse;roundness 支持 null、{type:1}(旧版)、{type:2}(自适应,推荐)、{type:3,value:n}(固定像素)。
- 文本:需 fontSize、fontFamily(1=Virgil、2=Helvetica、3=Cascadia)、lineHeight、text(需显式 \n)、textAlign、verticalAlign、containerId、baseline,且宽度高度按实际渲染计算。
- 箭头/连线:points 首点必须为 [0,0],后续为相对偏移;width/height 由 points 计算;lastCommittedPoint 等于最后一点;startArrowhead/endArrowhead 可取值;startBinding/endBinding 含 elementId、focus、gap(推荐 4-12);strokeSharpness 用 round 或 sharp。
- 双向绑定:容器 boundElements 必须含 {id, type},文本 containerId 或箭头 startBinding/endBinding 指向容器,缺一即“假绑定”。删除容器必须级联删除绑定文本。
- Obsidian 集成:link 支持 [[Note]]、[[Note|别名]]、[[Note#标题]]、[[Note#^块]]、exec:脚本名;仅 .excalidraw.md 中 link 可点击。
- 图片:使用 image 元素时必须在顶级 files 中提供对应 fileId 的 DataURL,type 与 mimeType 一致。
用法:先创建容器 → 再创建文本/箭头(保证绑定依赖 ID 已存在);优先用 .excalidraw 纯 JSON 格式,避免 .excalidraw.md 的 compressed-json 易错问题;嵌入写法如 ![[Diagram.excalidraw|600x400]]。
限制:未提供基准测试、收费、性能数据或安装命令;文本宽高与 baseline 建议用 Excalidraw Automate 的 measureText()/getTextSize() 或导出实测值确定,勿依赖硬编码近似;禁止 #000/#fff,禁止注释、占位符与非法负数格式。