指令

警告

指令已從 v10.5.0 開始棄用。請使用前置元數據中的 config 鍵來傳遞設定。請參閱設定以了解更多詳細資訊。

指令

指令讓圖表的作者能夠在渲染前透過變更套用的設定來更改圖表的外觀。

擁有指令的重要性在於，您可以在撰寫圖表時使用它們，並修改預設的全域和圖表特定的設定。因此，指令會在預設設定之上套用。指令的好處在於，您可以使用它們來變更特定圖表的設定，也就是說，在個別層級上變更。

雖然指令允許您變更大多數的預設設定，但基於安全性考量，有些設定無法使用。此外，您可以*選擇定義一組設定*，讓圖表作者可以使用指令覆寫。

指令選項的類型

Mermaid 基本上支援兩種設定選項，可由指令覆寫。

一般/頂層設定：這些設定可供使用，並套用於所有圖表。一些最重要的頂層設定為
- 主題
- 字型系列
- 日誌等級
- 安全等級
- 開始時載入
- 安全
圖表特定設定：這些設定可供使用，並套用於特定圖表。對於每個圖表，都有特定的設定會變更該特定圖表的外觀和行為。例如，mirrorActors 是 SequenceDiagram 特有的設定，會變更是否鏡像執行者。因此，此設定僅適用於 SequenceDiagram 類型。

注意： 並非所有設定選項都列在此處。若要取得所有設定選項，請參閱原始碼中的 defaultConfig.ts。

資訊

我們計劃很快在文件中發佈一份完整的頂層設定和圖表特定設定及其可能值的清單。

宣告指令

既然我們已經定義了可用的設定類型，我們可以學習如何宣告指令。指令始終以 %% 符號開始和結束，中間包含指令文字，例如 %% {directive_text} %%。

這裡的指令文字結構類似巢狀鍵值對應或 JSON 物件，根目錄為 init。所有一般設定都定義在頂層，而所有圖表特定設定都定義在更深一層，以圖表類型作為該區段的鍵/根。

以下程式碼片段顯示指令的結構

%%{
  init: {
    "theme": "dark",
    "fontFamily": "monospace",
    "logLevel": "info",
    "flowchart": {
      "htmlLabels": true,
      "curve": "linear"
    },
    "sequence": {
      "mirrorActors": true
    }
  }
}%%

您也可以在一行中定義指令，如下所示

%%{init: { **insert configuration options here** } }%%

例如，以下程式碼片段

%%{init: { "sequence": { "mirrorActors":false }}}%%

注意事項： 作為 {argument} 傳遞的 JSON 物件必須是有效的鍵值對，並用引號括住，否則將會被忽略。有效的鍵值對可以在 config 中找到。

簡單圖表示例

此處的指令宣告會將渲染的 Mermaid 圖表的 logLevel 設定為 debug，並將 theme 設定為 dark，從而變更圖表本身的外觀。

注意：您可以使用 'init' 或 'initialize'，因為兩者都可接受作為 init 指令。另請注意，%%init%% 和 %%initialize%% 指令會在剖析後分組在一起。

例如，剖析上述內容會產生一個單一的 %%init%% JSON 物件，如下所示，結合兩個指令並帶入為 loglevel 給定的最後一個值

json

{
  "logLevel": "fatal",
  "theme": "dark",
  "startOnLoad": true
}

然後，這將會傳送至 mermaid.initialize(...) 進行渲染。

指令範例

既然已經說明了指令的概念，讓我們看看更多指令使用的範例

透過指令變更主題

以下程式碼片段會將 theme 變更為 forest

%%{init: { "theme": "forest" } }%%

可能的主題值為：default、base、dark、forest 和 neutral。預設值為 default。

範例

透過指令變更字型系列

以下程式碼片段會將字型系列變更為 Trebuchet MS, Verdana, Arial, Sans-Serif

%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%

範例

透過指令變更日誌等級

以下程式碼片段會將 logLevel 變更為 2

%%{init: { "logLevel": 2 } }%%

可能的 logLevel 值為

1 代表 *debug*，
2 代表 *info*
3 代表 *warn*
4 代表 *error*
5 代表 *僅嚴重錯誤*

預設值為 5。

範例

透過指令變更流程圖設定

一些常見的流程圖設定為

htmlLabels：true/false
curve：linear/curve
diagramPadding：數字
useMaxWidth：數字

如需完整的流程圖設定清單，請參閱原始碼中的 defaultConfig.ts。我們計劃很快在文件中發佈一份所有圖表特定設定的完整清單。

以下程式碼片段會變更流程圖設定

%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%

這裡我們僅覆寫流程圖設定，而不是一般設定，將 htmlLabels 設定為 true，並將 curve 設定為 linear。

透過指令變更循序圖設定

一些常見的循序圖設定為

width：數字
height：數字
messageAlign：left、center、right
mirrorActors：布林值
useMaxWidth：布林值
rightAngles：布林值
showSequenceNumbers：布林值
wrap：布林值

如需完整的循序圖設定清單，請參閱原始碼中的 defaultConfig.ts。我們計劃很快在文件中發佈一份所有圖表特定設定的完整清單。

因此，預設情況下，wrap 對於循序圖的值為 false。

讓我們來看一個範例

現在讓我們啟用循序圖的 wrap。

以下程式碼片段會將循序圖的 wrap 設定變更為 true

%%{init: { "sequence": { "wrap": true} } }%%

將該程式碼片段套用到上面的圖表後，將會啟用 wrap

指令 ​

指令 ​

指令選項的類型 ​

宣告指令 ​

指令範例 ​

透過指令變更主題 ​

透過指令變更字型系列 ​

透過指令變更日誌等級 ​

透過指令變更流程圖設定 ​

透過指令變更循序圖設定 ​

指令

指令