Mermaid.js指南：使用文本创建图表（流程图、时序图和甘特图）

1 1. 什么是 Mermaid？
- 1.1 Mermaid 的概述和关键特性
- 1.2 Mermaid 的主要使用场景和优势
  - 1.2.1 使用场景
  - 1.2.2 优势
2 2. Mermaid 的基础用法
3 3. 使用 Mermaid.js 创建图表
4 4. 在 WordPress 中使用 Mermaid
5 5. 使用 Mermaid 的最佳实践
6 6. 总结

1. 什么是 Mermaid？

Mermaid 的概述和关键特性

Mermaid 是一个 JavaScript 库，允许你使用基于文本的定义来创建图表和流程图。借助此工具，只需编写代码即可轻松生成可视化图形。由于它能够快速创建流程图、时序图、甘特图等，因而被软件开发者、项目经理以及其他众多用户广泛使用。

Mermaid 最大的优势在于可以仅通过代码来定义图表。这使得在不依赖 GUI 的情况下，编辑和管理图表变得非常方便。Mermaid 还集成在 GitHub、Notion 等平台中，具备在多种场景下使用的灵活性。

Mermaid 的主要使用场景和优势

使用场景

为软件开发创建流程图和时序图。
为项目规划创建甘特图。
为 Markdown 文件和 Wiki 文档添加可视化展示。

优势

简洁语法： 像编写代码一样编写图表，即使是初学者也能轻松上手。
基于代码的管理： 可使用源码管理工具（如 Git）进行版本控制。
快速创建与更新： 只需编辑代码，图表的更改即可立即生效。
可扩展且可定制： 可通过 CSS 自定义样式，亦可使用 JavaScript 扩展功能。

2. Mermaid 的基础用法

如何安装

Mermaid.js 有两种安装方式：使用 CDN 链接或使用 npm。

1. 使用 CDN 链接

在你的 HTML 文件中添加以下 script 标签。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <div class="mermaid">
    graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
  </div>
</body>
</html>

2. 使用 npm

如果已经准备好 Node.js 环境，可使用以下命令进行安装。

npm install mermaid

采用这种方式后，Mermaid 可以作为 JavaScript 项目的一部分进行集成。

基础语法与语法规则

使用 Mermaid.js，你可以通过直观的基于文本的语法来创建图表。下面列出了一些常见示例。

1. 流程图

下面是一个流程图定义的示例。

graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]

2. 时序图

展示系统工作流的时序图可以这样编写。

sequenceDiagram
  participant A as User
  participant B as Server
  A->>B: Send request
  B-->>A: Return response

3. 甘特图

用于项目管理的甘特图可以如下编写。

gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Planning
  Task A :a1, 2024-01-01, 10d
  Task B :a2, after a1, 7d
  Task C :a3, after a2, 5d

支持的图表类型

Mermaid.js 支持以下类型的图表和图形。

流程图：展示过程的流向。
时序图：可视化通信协议和流程。
甘特图：用于项目管理和排程。
类图：用于面向对象设计。
状态图：表示状态转移。
饼图：可视化数据比例。

3. 使用 Mermaid.js 创建图表

如何在 HTML 中嵌入 Mermaid

Mermaid.js 可以轻松嵌入到 HTML 中。按照以下步骤即可创建图表。

1. 基本 HTML 结构

下面的代码展示了在 HTML 文件中使用 Mermaid.js 的最小示例。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Mermaid Diagram</title>
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
    mermaid.initialize({ startOnLoad: true });
  </script>
</head>
<body>
  <h1>Flowchart Example</h1>
  <div class="mermaid">
    graph TD;
      A[Start] --> B[Process 1]
      B --> C[Process 2]
      C --> D[End]
  </div>
</body>
</html>

2. 显示多个图表

如果您想显示多个图表，请在 HTML 中添加多个 div 标签，如下所示。

<div class="mermaid">
  graph TD;
    A --> B;
    B --> C;
</div>
<div class="mermaid">
  sequenceDiagram
    participant A as User
    participant B as Server
    A->>B: Send request
    B-->>A: Return response
</div>

使用 JavaScript 进行初始化和配置

1. 初始化设置

以下代码以编程方式初始化 Mermaid.js。

mermaid.initialize({
  startOnLoad: true,
  theme: 'forest',
  flowchart: { curve: 'basis' },
});

使用此配置后，主题更改为 forest，并且流程图的线条被自定义为使用曲线边缘。

2. 动态添加图表

以下示例展示了如何使用 JavaScript 动态生成图表。

const code = `
graph LR;
  X[Start] --> Y[Next step];
  Y --> Z[End];
`;
const element = document.querySelector('#dynamicChart');
element.innerHTML = code;
mermaid.init(undefined, element);

实用代码示例与说明

示例 1：创建序列图

<div class="mermaid">
  sequenceDiagram
    participant User as User
    participant Server as Server
    User->>Server: Data request
    Server-->>User: Data response
</div>

示例 2：创建甘特图

<div class="mermaid">
  gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Development Phase
      Design :done, 2024-01-01, 2024-01-07
      Implementation :active, 2024-01-08, 2024-01-20
      Testing :2024-01-21, 2024-01-30
</div>

4. 在 WordPress 中使用 Mermaid

插件介绍与设置

如果您想在 WordPress 中使用 Mermaid.js，最简便的方法是安装专用插件。以下是一些流行的选项。

1. Mermaid 插件 – “Mermaid Markdown 语法高亮”

此插件允许您在文章中直接使用 Mermaid 语法。

安装步骤

登录 WordPress 管理后台。
在菜单中点击插件 → 安装插件。
在搜索框中输入 Mermaid Markdown Syntax Highlighting。
安装插件并激活。

配置步骤

激活后，您可以在设置界面调整基本选项。
自定义设置，例如主题和 启动时自动加载。

如何在文章中显示图表

安装插件后，您可以使用如下短代码在文章中显示图表。

示例：插入流程图

[mermaid]
graph TD;
  A[Start] --> B[Process 1]
  B --> C[Process 2]
  C --> D[End]
[/mermaid]

示例：插入序列图

[mermaid]
sequenceDiagram
  participant User
  participant Server
  User->>Server: Send request
  Server-->>User: Return response
[/mermaid]

示例：插入甘特图

[mermaid]
gantt
  title Project Plan
  dateFormat YYYY-MM-DD
  section Development
    Design :done, 2024-01-01, 2024-01-07
    Implementation :active, 2024-01-08, 2024-01-20
    Testing :2024-01-21, 2024-01-30
[/mermaid]

注意事项与故障排除

1. 图表未渲染时的处理方法

原因 1： 插件未正确激活。→ 重新检查插件设置，确保已启用。
原因 2： Mermaid.js 脚本未加载。→ 可能与您的主题或其他插件冲突，请逐个禁用插件以定位冲突。

2. 不使用插件的手动设置

如果您不想使用插件，也可以通过手动将以下代码添加到主题的 functions.php 来嵌入 Mermaid.js。

function add_mermaid_script() {
    echo '<script type="module">
        import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
        mermaid.initialize({ startOnLoad: true });
    </script>';
}
add_action('wp_footer', 'add_mermaid_script');

5. 使用 Mermaid 的最佳实践

如何管理复杂图表

1. 拆分并组织代码

在创建复杂图表时，遵循以下技巧来保持代码的有序性。

为每个部分添加注释

%% Start of the flowchart
graph TD;
    A[Start] --> B[Process 1]
%% Branching logic
    B --> C[Process 2]
    B --> D[Process 3]

创建模板并重复使用 对于大型项目，准备模板并在多个图表之间保持一致性非常重要。

2. 在外部文件中管理图表

不要将 Mermaid 代码直接嵌入 HTML 或 Markdown 文件中，而是将其存放在外部文件里。这有助于提升可维护性。

示例：将 Mermaid 代码保存为 diagram.mmd 文件，并在 HTML 中加载它。

<div id="diagram-container"></div>
<script>
  fetch('diagram.mmd')
    .then(response => response.text())
    .then((text) => {
      const container = document.getElementById('diagram-container');
      container.innerHTML = text;
      mermaid.init(undefined, container);
    });
</script>

自定义与主题设置

1. 应用主题

Mermaid.js 包含多种内置主题，您可以轻松切换到视觉上更吸引的样式。

主题列表

默认
暗色
森林
霓虹

配置示例

mermaid.initialize({
  theme: 'dark',
});

2. 应用自定义 CSS

如果需要更细致的设计调整，可以使用 CSS 定义样式。

.mermaid text {
  font-family: Arial, sans-serif;
  fill: #333;
}

性能考虑因素

1. 调整初始化时机

不要在页面加载时就初始化图表，而是仅在用户需要时才初始化 Mermaid。这可以降低处理负载。

const config = {
  startOnLoad: false,
};

mermaid.initialize(config);

// Render only when needed
document.getElementById('render-btn').addEventListener('click', () => {
  mermaid.init();
});

2. 转换为静态图片

如果性能尤为重要，您可以将 Mermaid 生成的图表导出为图片文件，并作为静态图片使用。这可以最大程度地减轻浏览器的负担。

6. 总结

Mermaid.js 的价值与便利性

Mermaid.js 是一个强大的 JavaScript 库，允许您使用基于代码的定义来创建图表。由于它能够轻松渲染多种类型的图表——如流程图、时序图和甘特图——因此对开发者和项目经理来说是极其有用的工具。

该库最大的优势之一在于其简洁的语法，使您能够高效地创建复杂图表。它还能与 WordPress 等 CMS 平台集成，是在博客文章和技术文档中呈现可视化信息的绝佳方式。

各章节回顾

什么是 Mermaid 我们阐述了 Mermaid.js 的基本概述、使用场景以及采用它的好处。
Mermaid 的基本使用 我们介绍了实用的基础知识，从安装方法到基本语法。
使用 Mermaid.js 创建图表 我们提供了在 HTML 和 JavaScript 中创建图表的详细步骤。
在 WordPress 中使用 Mermaid 我们讲解了如何将 Mermaid 与 WordPress 集成，包括插件使用和文章中的实际示例。
使用 Mermaid 的最佳实践 我们给出了代码管理、性能优化和设计自定义的实用建议。

Mermaid.js 的未来可能性

Mermaid.js 是一个开源项目，未来可能会继续添加新功能和支持的格式。它也在 GitHub、Notion 和 WordPress 等众多平台上得到越来越多的支持，因此其潜在用例预计将进一步扩展。

因为它可以应用于多种用途——例如商业文档、演示文稿以及增强项目管理工具——继续学习和练习 Mermaid.js 将帮助您更有效地使用它。

最终说明

在本文中，我们从基础到实际使用涵盖了 Mermaid.js。由于它对初学者友好，并且对专业文档也很有用，请务必尝试使用它。

在需要时，参考本指南，并开始将 Mermaid.js 集成到您的实际项目和技术写作中。

Prev

2026-01-19
JavaScript数组splice()详解：删除、插入、替换元素（附实用示例）
Next
記事がありません