ER Diagram Renderer

ER Diagram Renderer（id er-diagram-renderer，目前版本 1.2.0）把一份描述資料表、欄位與外鍵的 JSON，畫成三部分：左側導覽樹、Wiki 文件頁，以及可縮放的實體關聯圖。需要 NoteCraftApp 0.6.0 以上。

安裝與映射

npx notecraftapp install-plugin er-diagram-renderer --apply "**/*.er.json"

--apply 會順便寫好映射規則。不帶的話，自己在 .notecraft/plugins.json 加一條：

{
  "plugins": [
    { "plugin": "er-diagram-renderer", "files": ["**/*.er.json"] }
  ]
}

慣例是資料檔以 .er.json 結尾，之後新增的檔案就會自動被接手。檔名本身沒有限制，files 也可以直接寫某個檔案的路徑。planning/orders.er.json 會變成 /view/planning/orders.er 這一頁。

安裝流程見安裝來源，規則寫法見映射規則 plugins.json。

資料檔格式

一份能 build 的最小資料檔：兩張表，orders.customer_id 指向 customer。

{
  "$schema": "https://raw.githubusercontent.com/SteveLin100132/notecraft/main/plugins/er-diagram-renderer/schema.json",
  "meta": {
    "title": "訂單資料庫",
    "description": "訂單模組的資料表。先看 `customer`，再看 `orders`。",
    "backTo": "/notes/orders/overview"
  },
  "requirement": [
    { "key": "required", "label": "必填", "marker": "solid" },
    { "key": "nullable", "label": "可空", "marker": "hollow" }
  ],
  "flags": [
    { "key": "pk", "badge": "PK", "tone": "danger", "label": "主鍵" },
    { "key": "fk", "badge": "FK", "tone": "info", "label": "外鍵" }
  ],
  "derivations": [],
  "groups": [{ "key": "order", "label": "訂單" }],
  "layout": { "columns": [{ "key": "c1", "groups": ["order"] }] },
  "tables": [
    {
      "name": "customer",
      "label": "客戶",
      "group": "order",
      "columns": [
        { "name": "id", "type": "bigint", "required": "required", "pk": true },
        { "name": "name", "type": "text", "required": "required", "note": "客戶名稱" }
      ]
    },
    {
      "name": "orders",
      "label": "訂單",
      "group": "order",
      "columns": [
        { "name": "id", "type": "bigint", "required": "required", "pk": true },
        { "name": "customer_id", "type": "bigint", "required": "required", "fk": "customer" },
        { "name": "memo", "type": "text", "required": "nullable" }
      ]
    }
  ]
}

$schema 那一行是選用的，加了之後編輯器能依 schema 檢查與補全。

頂層欄位

欄位（tables[].columns）

完整規格見 repo 裡的 schema.json，含 3 個 schema、14 張表的範例見 example/schema.json。

Wiki 說明可用的 Markdown

meta.description、schemas[].description、groups[].description、tables[].description 會出現在 Wiki 頁，支援的語法只有：##／### 標題、段落、-／1. 清單、> 引言、**粗體**、`code`、[文字](url)。表格、圖片、HTML 一律當文字顯示。

• 反引號裡恰好是表名，會連到該表；恰好是 schema 的 key，會連到該 schema。兩者撞名時表名優先，要明確指定就寫 `table:customer` 或 `schema:crm`
• 連結只接受 http(s):、mailto:、/ 開頭的站內路徑與 # 錨點，其他一律當文字

選項

options 可以寫在資料檔裡，也可以寫在 plugins.json 的規則上：

同名設定的優先順序由低到高：內建預設、資料檔的 options、plugins.json 規則的 options、<PluginView> 的 options。同一份資料被不同專案引用時，引用的一方可以覆寫。

頁面上能做什麼

1234

1Wiki／Diagram 分頁2回到來源筆記3導覽樹：篩選、分群、資料表4總覽：統計與分群卡片

1. 1Wiki／Diagram 分頁
2. 2回到來源筆記
3. 3導覽樹：篩選、分群、資料表
4. 4總覽：統計與分群卡片

導覽樹

Schema → 分群 → 資料表三層，可以收合。上方的篩選框比對表名、表的 label 與欄位名，並顯示「命中／總數」。沒有寫 schemas 時省略 Schema 那一層。

Wiki 分頁

description 全部選填，沒寫的地方顯示空狀態。

Diagram 分頁

• 縮放與平移：拖曳平移；⌘／Ctrl＋滾輪縮放，觸控板捏合也可以。單純滾輪會捲動頁面。雙擊空白處或按右下的還原鈕回到起點
• 聚焦：點一張表，它的父表與子表保持清楚，其他變淡，並列出指向幾張父表、被幾張子表指向。再點一次、點空白處或按 Esc 取消
• 搜尋：比對表名、label 與欄位名，顯示命中數；命中欄位的表會自動展開
• 展開欄位：卡片只顯示 defaultRows 個欄位，點「展開全部 N 欄」看完整欄位
• 範圍：有寫 schemas 時，可以只畫某個 schema 的表；跨範圍的連線不畫，但會註明有幾條
• 共用表連線：hubTables 的連線預設收起，有一個開關可以顯示

Wiki 與 Diagram 互相跳轉：Table 頁有「在 Diagram 聚焦」，聚焦列有「開啟 Wiki」。

記住上次的位置

目前看的頁面、分頁與範圍存在瀏覽器，依資料檔分開記，重新整理會回到原處（先閃一下總覽再跳過去）。資料改名後對不到的位置會回到總覽。這個 plugin 不使用網址 hash。

鍵盤操作見快捷鍵的「ER Diagram Renderer」。

嵌進筆記

import PluginView from "@/components/PluginView.astro";

<PluginView src="planning/orders.er.json" caption="訂單模組的資料表關聯" />

內嵌和 /view/ 頁的差別：

• 內嵌和 /view/ 頁各自記住上次的位置，互不影響
• options 可以逐處覆寫，例如 options={{ defaultRows: 10 }}
• anchor 對這個 plugin 沒有作用，因為它不讀網址 hash
• 外框的「開啟完整檢視頁」與放大檢視由 NoteCraftApp 提供，見映射規則 plugins.json

meta：標題、描述與回到筆記

backTo 只接受 / 開頭的站內路徑，例如 /notes/orders/overview。寫成完整網址或 //host 會被忽略，build 時印警告，不會失敗。