vibe-coding-cn/skills/canvas-dev/references/canvas-json-spec.md

Obsidian Canvas JSON 规范

文件格式

Canvas 文件是 .canvas 扩展名的 JSON 文件。

顶层结构

{
  "nodes": [],
  "edges": []
}

节点 (nodes)

通用属性

属性	类型	必需	说明
id	string	✅	唯一标识符
type	string	✅	节点类型
x	number	✅	X 坐标
y	number	✅	Y 坐标
width	number	✅	宽度
height	number	✅	高度
color	string	❌	颜色编号 (1-6)

文本节点 (text)

{
  "id": "node-1",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 200,
  "height": 100,
  "text": "# 标题\n\n内容支持 Markdown"
}

文件节点 (file)

{
  "id": "node-2",
  "type": "file",
  "x": 300,
  "y": 0,
  "width": 200,
  "height": 100,
  "file": "path/to/file.md"
}

链接节点 (link)

{
  "id": "node-3",
  "type": "link",
  "x": 600,
  "y": 0,
  "width": 200,
  "height": 100,
  "url": "https://example.com"
}

分组节点 (group)

{
  "id": "group-1",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 500,
  "height": 300,
  "label": "分组名称"
}

连线 (edges)

属性

属性	类型	必需	说明
id	string	✅	唯一标识符
fromNode	string	✅	起始节点 id
toNode	string	✅	目标节点 id
fromSide	string	❌	起始边 (top/right/bottom/left)
toSide	string	❌	目标边 (top/right/bottom/left)
fromEnd	string	❌	起始端样式 (none/arrow)
toEnd	string	❌	目标端样式 (none/arrow)
label	string	❌	连线标签

示例

{
  "id": "edge-1",
  "fromNode": "node-1",
  "toNode": "node-2",
  "fromSide": "right",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "调用"
}

颜色编码

color	颜色	建议用途
1	红色	缓存、热点、警告
2	橙色	消息队列、异步
3	黄色	上游依赖、外部输入
4	绿色	数据库、持久化
5	蓝色	搜索、外部服务
6	紫色	注释、设计决策

布局建议

三层架构布局

x: -400    x: 0      x: 400    x: 800
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ 前端   │→│ API    │→│ 服务   │→│ 数据   │
└────────┘ └────────┘ └────────┘ └────────┘

间距建议

• 节点宽度: 200-280
• 节点高度: 80-150
• 水平间距: 100-150
• 垂直间距: 120-150

完整示例

{
  "nodes": [
    {
      "id": "group-api",
      "type": "group",
      "x": -50,
      "y": -50,
      "width": 300,
      "height": 200,
      "label": "API 层"
    },
    {
      "id": "api-user",
      "type": "text",
      "x": 0,
      "y": 0,
      "width": 200,
      "height": 100,
      "text": "# UserAPI\n\n- GET /users\n- POST /users"
    },
    {
      "id": "svc-user",
      "type": "text",
      "x": 350,
      "y": 0,
      "width": 200,
      "height": 100,
      "text": "# UserService\n\n- get_user()\n- create_user()"
    },
    {
      "id": "db",
      "type": "text",
      "x": 700,
      "y": 0,
      "width": 200,
      "height": 80,
      "text": "# PostgreSQL",
      "color": "4"
    }
  ],
  "edges": [
    {
      "id": "e1",
      "fromNode": "api-user",
      "toNode": "svc-user",
      "fromSide": "right",
      "toSide": "left",
      "label": "调用"
    },
    {
      "id": "e2",
      "fromNode": "svc-user",
      "toNode": "db",
      "fromSide": "right",
      "toSide": "left"
    }
  ]
}