在現代 web 開發中，可視化工具對于展示流程、結構和數據關系至關重要。Mermaid 是一款強大的 JavaScript 工具，它使用基于 Markdown 的語法來呈現可定制的圖表、圖表和可視化。對于展示流程、結構和數據關系至關重要。通過簡單的文本描述，你可以輕松創建流程圖、思維導圖、序列圖等多種圖表類型。本文將帶你了解 Mermaid 的核心功能，并展示如何在 Vue 3 項目中集成和使用它。
本博文旨在幫助初學者快速掌握開發技能，同時解決在學習和實踐過程中可能遇到的常見問題，如舊版代碼兼容性問題和錯誤配置等。博文將兼顧基礎知識的講解和實用技巧的應用，確保讀者能夠順利上手并提高開發效率。2025版最新避坑文章
一、Mermaid 簡介
Mermaid 是一款開源工具，使用 MIT 協議授權。它支持多種圖表類型，包括但不限于：
- 流程圖（flowchart）
- 序列圖（sequence diagram）
- 甘特圖（gantt）
- 類圖（class diagram）
- Git 圖（git graph）
- 思維導圖（mindmap）
- 數據包圖（packet diagram）
- ER 圖（er diagram）
- 餅圖（pie chart）
- 象限圖（quadrant chart）
- 需求圖（requirement diagram）
你可以通過修改圖的描述來重新呈現或修改圖。這種基于文本的圖表定義方式，使得圖表的維護和版本控制變得更加容易。
二、集成 Mermaid
CDN 引入
最簡單的方式是通過 CDN 引入 Mermaid。jsDelivr 提供了 Mermaid 的 CDN 服務，你可以通過以下鏈接引入：
<script type="module">import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>
你也可以通過右上角的下拉框切換版本，以適應你的項目需求。
npm 安裝
對于需要離線使用或更穩定依賴的項目，可以通過 npm 安裝 Mermaid：
npm install mermaid
# 或
yarn add mermaid
# 或
pnpm add mermaid
安裝完成后，你可以在項目中通過 import 引入 Mermaid。
三、Vue 3 中的集成示例
以下是一個在 Vue 3 項目中使用 Mermaid 的完整示例，采用 setup 語法：
<template><div className="mermaid-container"><pre className="mermaid" ref="mermaidRef"></pre></div>
</template><script setup>
import {ref, onMounted, nextTick} from 'vue';
import mermaid from 'mermaid';
const mermaidRef = ref(null);const mermaidCode = `
flowchart TDA[開始] --> B[步驟 1]B --> C[步驟 2]C --> D[結束]
`;onMounted(async () => {// 初始化 mermaid 配置mermaid.initialize({startOnLoad: false, // 禁用自動渲染，手動控制securityLevel: 'loose', // 啟用點擊事件和 HTML 標簽});// 確保 DOM 已經更新await nextTick();// 將 mermaid 代碼設置到 pre 標簽中if (mermaidRef.value) {mermaidRef.value.textContent = mermaidCode;}// 手動渲染 mermaid 圖表await mermaid.run({querySelector: '.mermaid',});
});
</script><style>
.mermaid-container {width: 100%;height: 400px;display: flex;justify-content: center;align-items: center;
}pre.mermaid {font-family: 'trebuchet ms', verdana, arial;width: 100%;height: 100%;
}
</style>運行效果：
代碼說明
-
模板部分：定義了一個容器 div 和一個 pre 標簽，pre 標簽的類名是 mermaid，這是 Mermaid 識別圖表定義的關鍵。
-
腳本部分：
- 引入了 Mermaid 的 ESM 模塊。
- 定義了一個 ref 來引用 pre 標簽。
- 在 onMounted 生命周期鉤子中，初始化 Mermaid 配置，并在 DOM 更新后設置 pre 標簽的內容，最后手動渲染圖表。
-
樣式部分：為容器和 pre 標簽設置了基本的樣式，確保圖表能夠正確顯示。
四、配置與高級用法
安全配置
Mermaid 提供了 securityLevel 配置項，用于設置已解析圖表的信任級別：
- ‘strict’（默認）：對文本中的 HTML 標記進行編碼，并禁用單擊功能。
- ‘antiscript’：允許在文本中使用 HTML 標記（僅刪除腳本元素），并啟用單擊功能。
- ‘loose’：允許在文本中使用 HTML 標記，并啟用單擊功能。
- ‘sandbox’：使用沙盒化 iframe 渲染，阻止 JavaScript 運行。
你可以通過 mermaid.initialize 方法設置 securityLevel：
mermaid.initialize({securityLevel: 'loose',
});
高級渲染控制
除了默認的自動渲染，你還可以使用 mermaid.run 方法進行更復雜的渲染控制：
mermaid.initialize({ startOnLoad: false });await mermaid.run({querySelector: '.someOtherClass', // 渲染特定類名的元素
});await mermaid.run({nodes: [document.getElementById('someId'), document.getElementById('anotherId')], // 渲染特定節點
});await mermaid.run({suppressErrors: true, // 抑制錯誤
});
API 使用
Mermaid 提供了豐富的 API，例如：
- render：使用圖形定義作為字符串來渲染圖形。
- detectType：確定給定文本中存在的圖表類型。
- parse：在不呈現圖形的情況下驗證圖形定義。
五、總結
通過本文，你已經了解了如何在 Vue 3 項目中集成 Mermaid，并利用其強大的圖表生成功能。Mermaid 的簡潔語法和豐富功能使其成為 web 開發中不可或缺的可視化工具。無論是簡單的流程圖還是復雜的序列圖，Mermaid 都能輕松應對，為你的項目增添專業性和可視化魅力。
相關鏈接：
https://mermaid.js.org/config/usage.html
協同工作)
