json-canvas

JSON Canvas 技能

檔案結構

一個 canvas 檔案（.canvas）包含兩個頂層陣列，遵循 JSON Canvas Spec 1.0：

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

• nodes（選填）：節點物件陣列
• edges（選填）：連接節點的邊線物件陣列

常見工作流程

1. 建立新 Canvas

1. 建立一個 .canvas 檔案，包含基本結構 {"nodes": [], "edges": []}
2. 為每個節點產生唯一的 16 字元十六進位 ID（例如 "6f0ad84f44ce9c17"）
3. 加入節點，需包含必要欄位：id、type、x、y、width、height
4. 加入邊線，透過 fromNode 與 toNode 參照有效的節點 ID
5. 驗證：解析 JSON 確認格式正確。確認所有 fromNode/toNode 值都存在於 nodes 陣列中

2. 在現有 Canvas 中加入節點

1. 讀取並解析現有的 .canvas 檔案
2. 產生一個不與現有節點或邊線 ID 衝突的唯一 ID
3. 選擇位置（x、y），避免與現有節點重疊（保留 50-100px 間距）
4. 將新節點物件附加到 nodes 陣列
5. 可選：加入邊線連接新節點與現有節點
6. 驗證：確認所有 ID 唯一，且所有邊線參照都指向存在的節點

3. 連接兩個節點

1. 識別來源與目標節點 ID
2. 產生唯一的邊線 ID
3. 將 fromNode 與 toNode 設為來源與目標 ID
4. 可選：設定 fromSide/toSide（top、right、bottom、left）作為錨點
5. 可選：設定 label 作為邊線上的描述文字
6. 將邊線附加到 edges 陣列
7. 驗證：確認 fromNode 與 toNode 都參照存在的節點 ID

4. 編輯現有 Canvas

1. 將 .canvas 檔案讀取並解析為 JSON
2. 透過 id 定位目標節點或邊線
3. 修改所需的屬性（文字、位置、顏色等）
4. 將更新後的 JSON 寫回檔案
5. 驗證：編輯後重新檢查所有 ID 唯一性與邊線參照完整性

節點

節點是放置在畫布上的物件。陣列順序決定 z-index：第一個節點為底層，最後一個節點為頂層。

通用節點屬性

屬性	必要	類型	說明
id	是	string	唯一的 16 字元十六進位識別碼
type	是	string	text、file、link 或 group
x	是	integer	X 位置（像素）
y	是	integer	Y 位置（像素）
width	是	integer	寬度（像素）
height	是	integer	高度（像素）
color	否	canvasColor	預設 "1"-"6" 或十六進位（例如 "#FF0000"）

文字節點

屬性	必要	類型	說明
text	是	string	純文字，支援 Markdown 語法

{
  "id": "6f0ad84f44ce9c17",
  "type": "text",
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "text": "# Hello World\n\nThis is **Markdown** content."
}

換行陷阱：在 JSON 字串中使用 \n 表示換行。不要使用字面上的 \\n——Obsidian 會將其渲染為字元 \ 和 n。

檔案節點

屬性	必要	類型	說明
file	是	string	系統內的檔案路徑
subpath	否	string	連結到標題或區塊（以 # 開頭）

{
  "id": "a1b2c3d4e5f67890",
  "type": "file",
  "x": 500,
  "y": 0,
  "width": 400,
  "height": 300,
  "file": "Attachments/diagram.png"
}

連結節點

屬性	必要	類型	說明
url	是	string	外部 URL

{
  "id": "c3d4e5f678901234",
  "type": "link",
  "x": 1000,
  "y": 0,
  "width": 400,
  "height": 200,
  "url": "https://obsidian.md"
}

群組節點

群組是用於組織其他節點的視覺容器。將子節點放置在群組邊界內。

屬性	必要	類型	說明
label	否	string	群組的文字標籤
background	否	string	背景圖片路徑
backgroundStyle	否	string	cover、ratio 或 repeat

{
  "id": "d4e5f6789012345a",
  "type": "group",
  "x": -50,
  "y": -50,
  "width": 1000,
  "height": 600,
  "label": "Project Overview",
  "color": "4"
}

邊線

邊線透過 fromNode 與 toNode ID 連接節點。

屬性	必要	類型	預設值	說明
id	是	string	-	唯一識別碼
fromNode	是	string	-	來源節點 ID
fromSide	否	string	-	top、right、bottom 或 left
fromEnd	否	string	none	none 或 arrow
toNode	是	string	-	目標節點 ID
toSide	否	string	-	top、right、bottom 或 left
toEnd	否	string	arrow	none 或 arrow
color	否	canvasColor	-	線條顏色
label	否	string	-	文字標籤

{
  "id": "0123456789abcdef",
  "fromNode": "6f0ad84f44ce9c17",
  "fromSide": "right",
  "toNode": "a1b2c3d4e5f67890",
  "toSide": "left",
  "toEnd": "arrow",
  "label": "leads to"
}

顏色

canvasColor 類型可接受十六進位字串或預設數字：

預設值	顏色
"1"	紅色
"2"	橙色
"3"	黃色
"4"	綠色
"5"	青色
"6"	紫色

預設顏色值刻意未定義——應用程式使用各自的品牌顏色。

ID 產生

產生 16 字元小寫十六進位字串（64 位元隨機值）：

"6f0ad84f44ce9c17"
"a3b2c1d0e9f8a7b6"

佈局指南

• 座標可為負數（畫布無限延伸）
• x 向右增加，y 向下增加；位置為左上角
• 節點間距 50-100px；群組內保留 20-50px 內距
• 對齊網格（10 或 20 的倍數）以獲得較整潔的佈局

節點類型	建議寬度	建議高度
小型文字	200-300	80-150
中型文字	300-450	150-300
大型文字	400-600	300-500
檔案預覽	300-500	200-400
連結預覽	250-400	100-200

驗證檢查清單

建立或編輯 canvas 檔案後，請確認：

1. 所有 id 值在節點與邊線中皆唯一
2. 每個 fromNode 與 toNode 都參照存在的節點 ID
3. 每個節點類型都有必要欄位（文字節點需有 text，檔案節點需有 file，連結節點需有 url）
4. type 為以下之一：text、file、link、group
5. fromSide/toSide 值為以下之一：top、right、bottom、left
6. fromEnd/toEnd 值為以下之一：none、arrow
7. 顏色預設值為 "1" 到 "6" 或有效的十六進位（例如 "#FF0000"）
8. JSON 格式正確且可解析

若驗證失敗，請檢查是否有重複 ID、懸空的邊線參照，或格式錯誤的 JSON 字串（尤其是文字內容中未跳脫的換行符）。

完整範例

請參閱 references/EXAMPLES.md 取得完整的 canvas 範例，包括心智圖、專案看板、研究畫布與流程圖。

參考資料

• JSON Canvas Spec 1.0
• JSON Canvas GitHub