使用方式

Mermaid 是一個 JavaScript 工具，使用基於 Markdown 的語法來呈現可自訂的圖表、圖形和視覺化效果。

可以透過修改其描述來重新呈現/修改圖表。

CDN

https://www.jsdelivr.com/package/npm/mermaid

請注意，您可以透過右上角的下拉式選單切換版本。

使用 mermaid

對於大多數使用者來說，使用線上編輯器就已足夠，不過您也可以選擇將 mermaid 作為相依性部署，或使用Mermaid API。

我們彙整了一些關於如何使用 Mermaid 線上編輯器的教學影片。

在網頁上安裝和託管 Mermaid

使用 npm 套件

需求

Node >= 16

bash

# NPM
npm install mermaid
# Yarn
yarn add mermaid
# PNPM
pnpm add mermaid

在網頁上託管 mermaid

注意：本主題在初學者使用者指南中有更深入的探討

在網頁上整合 mermaid 的最簡單方法需要兩個元素

一個圖形定義，在標示為 class=mermaid 的 <pre> 標籤內。

範例

html

<pre class="mermaid">
    graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</pre>

mermaid js 指令碼。使用 script 標籤作為 ESM 匯入新增。

範例

html

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

按照這些指示，mermaid 會在頁面載入時啟動，並且（當頁面載入後）它會找到 pre 標籤中具有 class="mermaid" 的圖形定義，並按照給定的定義傳回 SVG 格式的圖表。

簡單完整範例：

html

<!doctype html>
<html lang="en">
  <body>
    <pre class="mermaid">
  graph LR
      A --- B
      B-->C[fa:fa-ban forbidden]
      B-->D(fa:fa-spinner);
    </pre>
    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    </script>
  </body>
</html>

注意事項：

也會將 id 屬性新增至沒有 id 屬性的 mermaid 標籤。

Mermaid 可以載入同一個頁面中的多個圖表。

試試看，將此程式碼儲存為 HTML 並使用任何瀏覽器載入。（Internet Explorer 除外，請勿使用 Internet Explorer。）

在節點中啟用點擊事件和標籤

必須先清除 securityLevel 設定。securityLevel 設定剖析圖表的信任程度並限制點擊功能。此功能在 8.2 版中作為安全性改進而引入，旨在防止惡意使用。

網站擁有者有責任區分可信任和不可信任的使用者群，我們鼓勵謹慎使用。

securityLevel

參數	描述	類型	必要	值
securityLevel	剖析圖表的信任程度	字串	選用	'sandbox'、'strict'、'loose'、'antiscript'

值

strict：（預設）文字中的 HTML 標籤會被編碼，且點擊功能會停用。
antiscript：文字中的 HTML 標籤允許使用（僅移除 script 元素），且點擊功能已啟用。
loose：文字中的 HTML 標籤允許使用，且點擊功能已啟用。
sandbox：在這個安全等級下，所有呈現都會在沙箱化的 iframe 中進行。這會防止任何 JavaScript 在內容中執行。這可能會妨礙圖表的互動功能，例如指令碼、循序圖中的彈出視窗、連至其他索引標籤或目標的連結等等。

資訊

這會變更 mermaid 的預設行為，讓升級到 8.2 版後，除非變更 securityLevel，否則流程圖中的標籤會編碼為標籤，且點擊功能會停用。sandbox 安全等級仍處於 Beta 版。

如果您要承擔圖表來源的安全責任，則可以將 securityLevel 設定為您選擇的值。這允許使用點擊和標籤。

若要變更 securityLevel，您必須呼叫 mermaid.initialize

javascript

mermaid.initialize({
  securityLevel: 'loose',
});

標籤超出範圍

如果您使用透過 CSS 載入的動態載入字型（例如字型），mermaid 應該等待整個頁面載入完畢（dom + 資產，尤其是字型檔案）。

javascript

$(document).ready(function () {
  mermaid.initialize();
});

如果沒有這樣做，很可能會導致 mermaid 呈現出標籤超出範圍的圖表。mermaid 中的預設整合會使用 window.load 事件開始呈現。

如果您的頁面主體中有其他字型，可能會使用這些字型來取代 mermaid 字型。在樣式中指定字型是此問題的解決方法。

css

pre.mermaid {
  font-family: 'trebuchet ms', verdana, arial;
}

使用 `mermaid.run`

mermaid.run 是在 v10 中新增，是處理更複雜整合的慣用方式。依預設，mermaid.run 會在文件準備就緒時呼叫，呈現具有 class="mermaid" 的所有元素。

您可以透過呼叫 await mermaid.run(<config>) 自訂該行為。

mermaid.initialize({startOnLoad: false}) 會防止 mermaid.run 在載入後自動呼叫。

使用 querySelector ".someOtherClass" 呈現所有元素

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  querySelector: '.someOtherClass',
});

呈現作為陣列傳遞的所有元素

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  nodes: [document.getElementById('someId'), document.getElementById('anotherId')],
});
await mermaid.run({
  nodes: document.querySelectorAll('.yetAnotherClass'),
});

呈現所有 .mermaid 元素，同時抑制任何錯誤

mermaid.initialize({ startOnLoad: false });
await mermaid.run({
  suppressErrors: true,
});

呼叫 `mermaid.init` - 已棄用

警告

mermaid.init 在 v10 中已棄用，將在未來的版本中移除。請改用 mermaid.run。

依預設，mermaid.init 會在文件準備就緒時呼叫，尋找具有 class="mermaid" 的所有元素。如果您在載入 mermaid 後新增內容，或以其他方式需要更精細地控制此行為，您可以自己呼叫具有以下項目的 init：

一個設定物件
一些節點，如
- 一個節點
- 節點的類陣列
- 或會找到您節點的 W3C 選取器

範例

javascript

mermaid.init({ noteMargin: 10 }, '.someOtherClass');

或沒有設定物件，以及 jQuery 選取

javascript

mermaid.init(undefined, $('#someId .yetAnotherClass'));

與 webpack 搭配使用

mermaid 完全支援 webpack。以下是運作中的範例。

API 使用方式

API 的主要概念是能夠以字串形式使用圖形定義來呼叫呈現函數。呈現函數會呈現圖形，並使用產生的 SVG 程式碼來呼叫回呼。透過此方法，網站建立者可以自行從網站中擷取圖形定義（可能是從文字區域），呈現圖形並將圖形放在網站中的某個位置。

下面的範例示範如何使用此方法。此範例只會將產生的 SVG 記錄到 JavaScript 主控台。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  mermaid.initialize({ startOnLoad: false });

  // Example of using the render function
  const drawDiagram = async function () {
    element = document.querySelector('#graphDiv');
    const graphDefinition = 'graph TB\na-->b';
    const { svg } = await mermaid.render('graphDiv', graphDefinition);
    element.innerHTML = svg;
  };

  await drawDiagram();
</script>

若要判斷指定文字中存在的圖表類型，您可以使用 mermaid.detectType 函數，如下方範例所示。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  const graphDefinition = `sequenceDiagram
    Pumbaa->>Timon:I ate like a pig.
    Timon->>Pumbaa:Pumbaa, you ARE a pig.`;
  try {
    const type = mermaid.detectType(graphDefinition);
    console.log(type); // 'sequence'
  } catch (error) {
    // UnknownDiagramError
  }
</script>

繫結事件

有時產生的圖形也會定義互動，例如工具提示和點擊事件。使用 API 時，必須在將圖形插入 DOM 後新增這些事件。

下方的範例程式碼是 mermaid 在使用 API 時執行的動作摘錄。此範例示範如何在搭配 API 使用以進行呈現時，將事件繫結至 SVG。

javascript

// Example of using the bindFunctions
const drawDiagram = async function () {
  element = document.querySelector('#graphDiv');
  const graphDefinition = 'graph TB\na-->b';
  const { svg, bindFunctions } = await mermaid.render('graphDiv', graphDefinition);
  element.innerHTML = svg;
  // This can also be written as `bindFunctions?.(element);` using the `?` shorthand.
  if (bindFunctions) {
    bindFunctions(element);
  }
};

圖形是使用 render 呼叫產生。
產生後，render 函數會呼叫提供的回呼函數，在此情況下稱為 insertSvg。
回呼函式會被呼叫並帶有兩個參數，產生的圖表的 SVG 程式碼和一個函式。此函式會在 SVG 插入 DOM 之後將事件繫結到 SVG。
將 SVG 程式碼插入 DOM 中以進行呈現。
呼叫繫結事件的繫結函式。

標記渲染器的範例

這是用於將 Markdown 文件轉換為 HTML 並在 HTML 中包含 mermaid 圖表的渲染器。

javascript

const renderer = new marked.Renderer();
renderer.code = function (code, language) {
  if (code.match(/^sequenceDiagram/) || code.match(/^graph/)) {
    return '<pre class="mermaid">' + code + '</pre>';
  } else {
    return '<pre><code>' + code + '</code></pre>';
  }
};

另一個 CoffeeScript 的範例，其中也包含了在產生的標記中的 mermaid script 標籤。

coffee

marked = require 'marked'

module.exports = (options) ->
  hasMermaid = false
  renderer = new marked.Renderer()
  renderer.defaultCode = renderer.code
  renderer.code = (code, language) ->
    if language is 'mermaid'
      html = ''
      if not hasMermaid
        hasMermaid = true
        html += '<script src="'+options.mermaidPath+'"></script>'
      html + '<pre class="mermaid">'+code+'</pre>'
    else
      @defaultCode(code, language)

  renderer

進階用法

不渲染的語法驗證

mermaid.parse(text, parseOptions) 函式會驗證圖表定義，而不會渲染圖表。

函式 mermaid.parse(text, parseOptions) 接收一個文字字串作為參數，如果定義符合 mermaid 的語法，則會回傳 { diagramType: string }。

如果定義無效，如果 parseOptions.suppressErrors 設定為 true，則函式會回傳 false。否則，它會拋出錯誤。

當解析函式拋出錯誤時，將會呼叫 parseError 函式。如果 parseOptions.suppressErrors 設定為 true，則不會呼叫它。

可以覆寫此函式，以便以應用程式特定的方式處理錯誤。

下面的 meta code 中的程式碼範例說明了這如何運作

javascript

mermaid.parseError = function (err, hash) {
  displayErrorInGui(err);
};

const textFieldUpdated = async function () {
  const textStr = getTextFromFormField('code');

  if (await mermaid.parse(textStr)) {
    reRender(textStr);
  }
};

bindEventHandler('change', 'code', textFieldUpdated);

組態設定

您可以將所需的組態傳遞給 mermaid.initialize 呼叫。這是設定 mermaid 的首選方式。組態物件的清單在mermaidAPI 文件中說明。

html

<script type="module">
  import mermaid from './mermaid.esm.mjs';
  let config = { startOnLoad: true, flowchart: { useMaxWidth: false, htmlLabels: true } };
  mermaid.initialize(config);
</script>

資訊

這是設定 mermaid 的首選方式。

以下方法已過時，僅為了向後相容性而保留。

使用 mermaid 物件

可以透過 mermaid 物件設定一些組態。使用此方法支援的兩個參數為

mermaid.startOnLoad
mermaid.htmlLabels

javascript

mermaid.startOnLoad = true;

警告

這種設定組態的方式已過時。相反地，首選的方式是使用 initialize 方法。此功能僅為了向後相容性而保留。

使用方式 ​

CDN ​

使用 mermaid ​

在網頁上安裝和託管 Mermaid ​

簡單完整範例：​

注意事項：​

在節點中啟用點擊事件和標籤 ​

securityLevel ​

標籤超出範圍 ​

使用 mermaid.run ​

呼叫 mermaid.init - 已棄用 ​

與 webpack 搭配使用 ​

API 使用方式 ​

繫結事件 ​

標記渲染器的範例 ​

進階用法 ​

不渲染的語法驗證 ​

組態設定 ​

以下方法已過時，僅為了向後相容性而保留。​

使用 mermaid 物件 ​

使用方式

CDN

使用 mermaid

在網頁上安裝和託管 Mermaid

簡單完整範例：

注意事項：

在節點中啟用點擊事件和標籤

securityLevel

標籤超出範圍

使用 `mermaid.run`

呼叫 `mermaid.init` - 已棄用

與 webpack 搭配使用

API 使用方式

繫結事件

標記渲染器的範例

進階用法

不渲染的語法驗證

組態設定

以下方法已過時，僅為了向後相容性而保留。

使用 mermaid 物件