用途:创建和编辑遵循 JSON Canvas Spec 1.0 的 .canvas 文件,用于在 Obsidian 中构建可视化画布,如思维导图、项目看板、研究画布和流程图。
文件结构:.canvas 文件包含两个顶层数组 nodes 和 edges,均为可选。nodes 为节点对象数组,edges 为连接节点的连线对象数组。
主要能力:
- 新建画布:以 {"nodes": [], "edges": []} 为基础结构,为每个节点生成唯一的 16 位十六进制 ID,添加必填字段 id、type、x、y、width、height,并通过 fromNode 和 toNode 添加连线。
- 向已有画布添加节点:解析现有文件,生成不冲突的 ID,选择避免重叠的位置(留 50-100px 间距),追加节点并可添加连线。
- 连接两个节点:生成唯一连线 ID,设置 fromNode 和 toNode,可选设置 fromSide/toSide(top、right、bottom、left)锚点及 label 标签。
- 编辑已有画布:按 id 定位节点或连线,修改属性后写回文件。
节点类型:text(含 Markdown 文本)、file(文件路径,可选 subpath 指向标题或块)、link(外部 URL)、group(视觉容器,可选 label、background、backgroundStyle)。数组顺序决定 z-index,首个节点在最底层。
连线属性:id、fromNode、toNode 为必填;fromSide、toSide、fromEnd、toEnd、color、label 可选。fromEnd 默认 none,toEnd 默认 arrow。
颜色:canvasColor 接受预设 "1"-"6"(红、橙、黄、绿、青、紫)或十六进制值如 "#FF0000"。预设值本身未定义,由应用使用品牌色。
ID 生成:16 位小写十六进制字符串(64 位随机值)。
布局建议:坐标可为负,x 向右增大,y 向下增大,位置为左上角;节点间距 50-100px,组内留 20-50px 内边距;建议对齐到 10 或 20 的倍数。
校验清单:所有 id 在 nodes 和 edges 中唯一;fromNode/toNode 引用存在的节点;各节点类型必填字段齐全;type 为 text、file、link、group 之一;fromSide/toSide 为 top、right、bottom、left 之一;fromEnd/toEnd 为 none、arrow 之一;颜色预设为 "1"-"6" 或有效十六进制;JSON 可解析。
限制:文本换行需使用 \n,不可使用字面量 \n,否则 Obsidian 会渲染为字符 \ 和 n。校验失败时检查重复 ID、悬空连线引用或格式错误的 JSON 字符串(尤其是未转义的换行符)。完整示例见 references/EXAMPLES.md。