幕雪

mermaid图表深入了解文本绘图的强大工具

在软件开发、系统设计、项目管理乃至日常文档编写中，图表是极其重要的沟通工具。它们能够将复杂的概念、流程或结构以直观的方式呈现。传统的图表绘制工具通常是图形界面的，需要通过拖拽、点击来完成，这在某些场景下会带来一些不便。而 **Mermaid** 提供了一种完全不同的思路：**使用文本代码来生成图表**。

Mermaid 图表是什么？

Mermaid 是一个基于 JavaScript 的图表绘制工具，它允许用户使用类似 Markdown 的简单文本语法来定义图表，然后将其渲染成 SVG 或 PNG 等图像格式。

想象一下，你不需要打开一个图形编辑器，不需要在画布上一点点绘制节点和连接线，而是直接在一份文本文件里写下类似这样的代码：

graph TD
A[开始] –> B{判断}
B –>|是| C[执行操作]
B –>|否| D[结束]
C –> D

Mermaid 引擎就会自动将这段代码解析并渲染成一个漂亮的流程图。它支持多种常见的图表类型，包括但不限于：

  • 流程图 (Flowchart): 描绘步骤和决策流程。
  • 时序图/序列图 (Sequence Diagram): 展示不同对象之间交互的时间顺序。
  • 类图 (Class Diagram): 表示类、接口及其关系。
  • 状态图 (State Diagram): 描述对象在其生命周期内的状态变化。
  • 甘特图 (Gantt Chart): 用于项目管理，展示任务的时间安排。
  • 饼图 (Pie Chart): 展示数据的比例构成。
  • 需求图 (Requirement Diagram): 用于描述需求、模块和它们之间的关系。
  • Git 图 (Gitgraph Diagram): 可视化 Git 提交历史。
  • 用户旅程图 (User Journey Diagram): 描绘用户与产品或服务的交互过程。
  • 思维导图 (Mindmap): 以树状结构组织信息。
  • 时间线 (Timeline): 按照时间顺序展示事件。

核心在于，Mermaid 将图表的定义与可视化表示分离，定义是文本，可视化是渲染结果。

为什么选择使用 Mermaid 图表？

相比传统的图形化图表工具，Mermaid 提供了许多独特的优势：

  • 版本控制友好： 图表的定义是纯文本，可以轻松地与代码、文档一起纳入版本控制系统（如 Git）。每一次修改都可以清晰地追踪、比较和合并，这对于多人协作和历史记录非常重要。传统的二进制图表文件则很难进行有效的版本控制和比较。
  • 易于集成和自动化： 文本格式使得 Mermaid 图表能够方便地嵌入到各种文档、维基百科、博客、Markdown 文件甚至代码注释中。许多平台和工具原生支持 Mermaid，无需额外插件即可渲染。开发者还可以通过脚本生成 Mermaid 代码，实现图表的自动化更新。
  • 维护和更新更便捷： 修改图表通常只需要编辑几行文本代码，比在图形界面中拖拽、调整位置、连接线要快得多，尤其对于大型或复杂的图表。修改节点文本、增删节点或调整连接关系都非常高效。
  • 协作效率高： 文本内容易于复制、粘贴和共享。团队成员可以直接在代码或文档中看到图表定义，方便讨论和修改，减少了文件格式不兼容或需要特定软件才能打开的问题。
  • 专注内容： 文本输入让你更专注于图表的内容和结构逻辑，而不是排版和样式（尽管 Mermaid 也支持基本的样式控制）。这有助于快速原型设计和迭代。

总而言之，选择 Mermaid 更多是出于对效率、版本控制、易维护性和集成性的需求，特别是在软件开发和技术文档领域。

Mermaid 图表可以在哪里使用？

Mermaid 的应用场景非常广泛，只要是支持集成 JavaScript 或支持 Markdown 渲染的平台，通常都能使用 Mermaid：

  • 各类 Markdown 编辑器和文档工具：

    • VS Code (通过插件)
    • Typora
    • Obsidian
    • Haroopad
    • 等等支持扩展 Markdown 语法的编辑器。
  • 代码托管平台和项目管理工具：

    • GitHub (在 README.md, .md 文件, Issue, Pull Request 中)
    • GitLab (在 Markdown 文件, Issue, Merge Request, Wiki 中)
    • Gitea / Gogs
    • Azure DevOps
    • Jira (通常需要安装插件，如 Atlassian Marketplace 上的应用)
    • Confluence (通常需要安装插件)
  • 静态网站生成器：

    • MkDocs
    • Hugo
    • Jekyll
    • GitBook
    • 等等，通过配置集成 JavaScript 库或使用主题/插件。
  • 在线文档和维基系统：

    • DokuWiki (通过插件)
    • Docsify
    • VuePress
  • 在线演示工具：

    • Reveal.js (通过插件)
  • 在线 Mermaid 编辑器：

    • Mermaid Live Editor (官方提供的在线沙盒，用于编写、预览和导出图表)
  • 任何网页：

    • 通过在 HTML 页面中引入 Mermaid JavaScript 库，并将图表代码放入特定标记的容器中。

只要你工作的平台支持在文本中嵌入代码块并能解释 Mermaid 语法（或允许你引入 JavaScript 库），你就可以在其中使用 Mermaid 绘制图表。

使用 Mermaid 图表需要多少成本？

使用 Mermaid 本身，**绝大多数情况下是免费的**。

  • 核心库： Mermaid 的核心 JavaScript 库是开源的，遵循 MIT 许可协议，可以免费下载、使用、修改和分发。
  • Mermaid Live Editor： 官方提供的在线编辑器是免费使用的。
  • 命令行工具 (Mermaid CLI)： 用于将 Mermaid 代码转换成静态图表文件（如 SVG, PNG）的命令行工具也是免费的。

成本可能体现在：

  • 平台或工具的费用： 如果你在使用一个需要付费的平台（如 Jira、Confluence），并且这个平台通过付费插件支持 Mermaid，那么这部分费用是平台的费用，而不是 Mermaid 本身的费用。不过许多平台（如 GitHub、GitLab）是原生免费支持的。
  • 学习曲线： 虽然 Mermaid 语法相对简单，但掌握不同图表类型的语法规则、节点形状、连接方式等仍需要一些学习时间。复杂图表的编写和调试也需要投入精力。
  • 集成和部署： 如果你需要将 Mermaid 集成到一个自定义的网站或应用中，可能需要花费一些开发时间来引入库、配置渲染等。

总的来说，Mermaid 是一个非常经济高效的图表解决方案，尤其适合个人和团队在日常文档和开发流程中使用。

如何创建 Mermaid 图表（入门）？

创建 Mermaid 图表的基本步骤非常简单：

  1. 确定你要绘制的图表类型。
  2. 使用对应的关键字开始 Mermaid 代码块。
  3. 定义图表中的节点和元素。
  4. 定义节点/元素之间的连接或关系。
  5. 将代码放入支持 Mermaid 渲染的环境中。

以下是几种常见图表类型的基本语法结构和示例：

流程图 (Flowchart)

以 `graph` 关键字开始，后面跟着图表的方向（如 `TD` 顶部到底部，`LR` 左到右）。

  • 定义节点：`节点ID[节点文本]`。方括号表示默认矩形节点。也可以使用其他形状，如 `(文本)` 圆角矩形，`{文本}` 菱形，`((文本))` 圆形等。
  • 定义连接：`节点ID1 –> 节点ID2`。可以使用箭头 `–>`、虚线 `-.->`、加粗箭头 `==>` 等。可以在连接线上添加文本：`节点ID1 — 文本 –> 节点ID2`。

graph LR
A(用户) –> B[登录页面]
B –> C{验证用户}
C –>|成功| D[主页]
C –>|失败| B
D –> E[退出]

这段代码会绘制一个从左到右的流程图，包含用户、登录页面、验证用户、主页和退出节点，并定义了它们之间的连接和条件分支。

时序图 (Sequence Diagram)

以 `sequenceDiagram` 关键字开始。

  • 定义参与者：`participant 参与者名称`。
  • 定义消息：`发送者 –> 接收者: 消息文本`。可以使用不同的箭头类型，如实线箭头 `–>`，虚线箭头 `–>>`，实线开放箭头 `->`，虚线开放箭头 `->>` 等。
  • 可以添加激活框、循环、选择等结构。

sequenceDiagram
participant 客户端
participant 服务器
客户端–>>服务器: 发送请求
activate 服务器
服务器–>服务器: 处理请求
deactivate 服务器
服务器–>>客户端: 返回响应

这段代码描述了客户端和服务器之间的一次简单的请求-响应交互过程，并展示了服务器的激活状态。

更多图表类型和详细语法可以参考 Mermaid 的官方文档，但基本原理都是类似的：用结构化的文本来描述图表的元素和关系。

如何将 Mermaid 图表集成到不同环境？

将你写好的 Mermaid 代码渲染成图表，取决于你在哪个环境中使用它。

在支持 Mermaid 的 Markdown 环境中

这是最常见的使用方式。在这些平台或编辑器中，你只需要将 Mermaid 代码放在一个特定的代码块中，通常使用 `mermaid` 作为代码块的语言标识符。

例如，在 GitHub 或 GitLab 的 Markdown 文件中：

mermaid
graph TD
A[项目启动] –> B{计划制定}
B –>|完成| C[开发阶段]
B –>|延迟| A
C –> D[测试阶段]
D –> E[发布]

当你保存或预览这个 Markdown 文件时，平台会自动调用内置的 Mermaid 渲染器将这段文本代码转换成流程图显示出来。

在自定义网页中集成

如果你想在自己的网站或博客中显示 Mermaid 图表，你需要引入 Mermaid 的 JavaScript 库并执行初始化。

基本步骤：

  1. 在你的 HTML 页面中引入 Mermaid 库：通常是通过 CDN 或下载到本地。

    <script src=”https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js”></script>

  2. 在页面加载完成后初始化 Mermaid：

    <script>
    mermaid.initialize({ startOnLoad: true });
    </script>

    `startOnLoad: true` 表示页面加载完毕后自动查找并渲染图表。

  3. 将你的 Mermaid 代码放在一个带有 `class=”mermaid”` 的 HTML 元素（如 `div` 或 `pre`）中：

    <div class=”mermaid”>
    graph LR
    A –> B
    B –> C
    </div>

当页面加载时，Mermaid 库会找到所有 `class=”mermaid”` 的元素，读取其中的文本内容，并将其渲染成 SVG 图表替换掉原来的文本内容。

使用命令行工具 (Mermaid CLI)

如果你需要生成静态的图表文件（如用于报告、邮件附件或不在线渲染的文档），可以使用 Mermaid CLI 工具。

首先你需要安装 Node.js 和 Mermaid CLI (使用 npm 或 yarn)。

npm install -g @mermaid-js/mermaid-cli

然后，将你的 Mermaid 代码保存到一个 `.mmd` 文件中（例如 `my_flowchart.mmd`）。

graph TD
开始 –> 结束

最后，使用命令行工具生成图片文件：

mmdc -i my_flowchart.mmd -o my_flowchart.png

这条命令会将 `my_flowchart.mmd` 文件中的 Mermaid 代码渲染成一个 PNG 格式的图片文件 `my_flowchart.png`。

Mermaid 还支持一些配置选项，比如调整主题、字体、图表大小等，可以通过初始化参数（JavaScript 集成）或命令行参数（CLI）来控制。

总而言之，Mermaid 提供了一种灵活、高效、易于维护的图表绘制方式，特别适合集成到现代的文档和开发工作流程中。

mermaid图表