开源工具利器：Mermaid助力知识图谱可视化与分享

news2025/3/15 6:00:42

在现代 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 TD
    A[开始] --> 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, // 抑制错误
});