Mermaid.js 方塊圖語法與網格佈局指南

方塊圖是一種結構化佈局引擎，用於表示複雜的軟體架構、硬體平台或組織模型。Mermaid.js 原生支援此功能，方塊引擎將佈局畫布視為絕對的數學網格矩陣。這可精確控制欄位對齊、獨立的佈局巢狀邊界、結構性間距區塊，以及明確的邊緣埠連結設定。

理解網格矩陣策略

與動態猜測佈局軌道的標準自由形式流程圖不同，方塊圖建立在嚴格的線性座標網格系統之上：

  • 欄位上限：您可使用欄位修飾符設定嚴格的水平上限。當網格填滿方塊時，額外的元素會自動乾淨地換行至下一列。
  • 依網格欄位調整大小：預設情況下，每個方塊佔用單一座標位置（$1 times 1$）。您可透過指定明確的欄寬，讓元素完美跨過多個軌道。

基本語法結構

每個佈局均以方塊宣告標頭開始。接著使用欄位關鍵字設定列寬容量，並在連續的行上宣告方塊。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
方塊
  欄位 3
  componentA["第一個方塊"]
  componentB["中間方塊"]
  componentC["右側方塊"]
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

語法參考

下表分解了方塊解析器原生識別的基礎資料參數、自訂樣式關鍵字與結構容器。

語法元件 類型需求 描述與視覺佈局規則
宣告 關鍵字識別符 初始化矩陣網格方塊畫布。必須使用精確的區塊 標題字串。
欄位組 關鍵字 + 整數 定義換行前的總水平槽位數（例如，欄位 4).
標準區塊 ID + 可選標籤 建立一個標準資料框：id["標籤文字"]。形狀修飾符符合流程圖語法（例如，(()) 用於圓形，[()] 用於資料庫）。
區塊尺寸覆蓋 冒號參數區塊 透過明確指定自訂欄位寬度區塊，覆蓋預設的 $1 times 1$ 排版比例網格佔位空間：id:寬度.
空間元素 保留關鍵字 使用精確的 space 關鍵字，插入一個隱形的結構性 $1 times 1$ 空白間距方塊至活躍列中。您可以在內聯中乘以寬度跨度，例如space:2.
區塊箭頭 專用實體 ID 在格子槽內渲染一個粗厚、結構化的過渡箭頭方塊：arrowId<["標籤"]>(方向)。方向包括上, 下, 左, 右.
複合包裝器 區塊 / 結束容器 將一個獨立的孤立子格子矩陣直接嵌套在父區塊槽內：block:子ID ... end。子區塊可以宣告自己的獨立欄位限制。

進階功能：明確的區塊尺寸與空間修飾符

對於非對稱佈局，您可以使用冒號符號分隔符，直接將明確的水平尺寸指標傳遞給標準區塊或空間分隔符：:寬度。這會強制元素乾淨地跨越多個格子位置。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  欄位 4
  wideComponent["寬版儀表板標題"]:4
  leftBar["側邊欄"] space:2 rightBar["主面板"]
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

進階功能：邊類型、方向與連結選項

在 區塊引擎內的連接被分為標準語義線與結構佈局區塊箭頭。標準連接線支援指定明確的方向約束，以決定線條如何包繞元素。

1. 標準線連接器

區塊連接使用標準連結運算子（-->, --, <-->). 然而，您可以在括號內附加方向或修飾符來控制路由：

  • A --> B：從元件 A 畫出一條標準的定向線至元件 B。
  • A -- x B：畫出一條以「X」標記結尾的連接路徑，表示該路徑已被阻斷。
  • A -- o B：畫出一條以開放圓形連接點結尾的連接路徑。

2. 動態佈局方塊箭頭

方塊箭頭被視為實際的佈局元件，佔據您列預算矩陣中的實際座標索引區塊。它們使用大於和小於語法屬性來映射實際的流程路徑：

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  columns 3
  producer["資料生產者"]
  midArrow<["轉換流量"]>(right)
  consumer["資料消費者"]
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

進階功能：子方塊矩陣巢狀（複合分組）

這個block:id包裝器作為一個獨立的佈局方塊上下文環境。應用程式群組容器可以在子方塊內建立自己的獨特水平欄位數，使複雜元件能夠緊密分組，而不影響全域父畫布範本網格的間距。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
block
  columns 2
  rootGateway["全域閘道"]
  
  block:microserviceCluster
    columns 3
    auth["驗證節點"]
    api["核心 API"]
    worker["工作引擎"]
  end
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

現實世界藍圖：具備快取的多層次基礎架構

這個全面的多列藍圖展示了乾淨的生產級基礎架構設定。它建立了一個三欄處理網格佈局，使用結構性空間元件來隔離資料庫層，繪製一條粗的向下方塊箭頭，並使用嵌套的內部子系統容器隔離出一個獨立的內部子系統容器block:id ... end綜合包裝器。

Mermaid


在 VPasCode 中編輯 Mermaid
Mermaid Edit Mermaid in VPasCode 
方塊
  欄位 3

  %% 第 1 行：入口服務
  dnsClient(("Web 客戶端"))
  loadBalancer["邊緣負載平衡器"]
  space

  %% 第 2 行：向下連接至微服務的流程
  space
  downRoute<["轉發流量"]>(down)
  space

  %% 第 3 行：綜合應用環境叢集
  block:appCluster
    欄位 2
    authService["驗證"]
    apiEngine["核心 API 工作人員"]
  end
  space
  database[("PostgreSQL 資料庫")]

  %% 建立明確的矩陣對矩陣結構線對齊
  loadBalancer --> appCluster
  appCluster --> database
Edit Mermaid in VPasCode



在 VPasCode 中編輯 Mermaid

常見語法陷阱與系統限制

在編譯精確的網格矩陣地圖時，請記住這些驗證檢查，以避免解析錯誤：

  • 欄位預算執行：請仔細追蹤您的欄位數量。如果您指定欄位 3，並在一行上寫下 4 個連續的方塊，第四個方塊將自動降為第 2 行，這可能會破壞預期的從左到右連接路徑。
  • 綜合嵌套順序：當使用block:id建立內部容器時，您必須始終使用end關鍵字在獨立的一行上封閉子網格工作區，然後再宣告後續元素。未能關閉方塊將會中止圖表的建立。
  • 方塊箭頭目標限制：方塊箭頭後括號內封閉的方向屬性（例如，(up), (down)）必須是完全符合系統關鍵字的小寫字面值。將方向大寫將導致處理錯誤。
  • 標籤邊界碰撞：標準流程圖形狀修飾符（例如括號()用於圓形方框或大括號{} 針對鑽石）完全支援。請確保形狀內的所有顯示文字標籤都使用乾淨的雙引號，以避免字元被刪除。
返回頂端