Mermaid 画图教程

Mermaid 是一种用于生成图表和可视化的开源标记语言。其目标是通过简单的文本描述快速创建复杂的图表，使得开发者和文档编写者能够更方便地展示信息和流程。

Mermaid 最常见的应用是生成流程图、序列图、类图、状态图、甘特图等。它使用一种简洁的语法，使得即使是不熟悉图表绘制的用户也能快速上手。

主要特性

简单易用的语法：Mermaid 的语法设计简洁明了，用户可以通过少量的文本描述生成复杂的图表。
多种图表类型：支持流程图、序列图、类图、状态图、实体关系图、甘特图、用户旅程图等多种图表类型。
开源免费：Mermaid 是一个开源项目，任何人都可以免费使用和贡献代码。
广泛的集成：Mermaid 可以与多种工具和平台集成，如 GitHub、GitLab、Obsidian、Notion 等。
动态渲染：支持在浏览器中动态渲染图表，方便即时预览和修改。

语法示例

流程图

基本语法

Mermaid 的流程图使用 graph 关键字开始。接下来可以选择图的方向，常用的方向有以下几种：

TD (Top to Down)：从上到下
LR (Left to Right)：从左到右
BT (Bottom to Top)：从下到上
RL (Right to Left)：从右到左

例如：

graph TD
    A --> B
    B --> C
    C --> D

节点

节点是流程图的基本单元。节点可以用方括号 [ ] 表示普通节点，用圆括号 ( ) 表示圆形节点，用大括号 { } 表示判定节点，用尖括号 > > 表示子流程节点，还可以用 (( )) 表示带有圆角的节点。

例如：

graph TD
    A[普通节点] --> B(圆形节点)
    B --> C{判定节点}
    C --> D>子流程节点>
    D --> E((带圆角的节点))

连线

连线用箭头表示。箭头的方向和样式可以通过不同的符号表示：

-->：普通箭头
-.->：虚线箭头
==>：加粗箭头
-->|text|：带标签的箭头

例如：

graph TD
    A --> B
    B -.-> C
    C ==> D
    D -->|带标签的箭头| E

子图（子流程）

子图可以使用 subgraph 关键字来定义。子图帮助组织和分类复杂的图表。

例如：

graph TD
    subgraph 子图1
        A --> B
    end
    subgraph 子图2
        C --> D
    end
    B --> C

样式自定义

Mermaid 提供了一些方法来定制节点和连线的样式。可以使用 style 关键字和 classDef 关键字来自定义样式。

例如：

graph TD
    A --> B
    B --> C
    C --> D
    style A fill:#f9f,stroke:#333,stroke-width:4px
    classDef green fill:#9f6,stroke:#333,stroke-width:2px;
    class C,D green

以下是一个包含多种元素和自定义样式的完整示例：

graph LR
    subgraph 主流程
        A[开始] --> B{是否有效?}
        B -->|是| C[处理]
        B -->|否| D[结束]
        C --> E[完成]
    end
    subgraph 子流程
        C --> F[子流程开始]
        F --> G[子流程处理]
        G --> H[子流程结束]
        H --> E
    end
    style A fill:#f9f,stroke:#333,stroke-width:4px
    style E fill:#ff9,stroke:#333,stroke-width:2px
    classDef green fill:#9f6,stroke:#333,stroke-width:2px;
    class F,G,H green

时序图

用于描述对象之间交互过程的图表

基本语法

在 Mermaid 中，时序图使用 sequenceDiagram 关键字开始。以下是一些基本元素和语法：

参与者（Participants）

参与者是时序图中的实体，通常是对象或类。参与者通过 participant 关键字定义。

sequenceDiagram
    participant Alice
    participant Bob

消息（Messages）

消息表示参与者之间的交互。它们可以是同步或异步的。基本消息语法如下：

->>：同步消息
-->>：异步消息

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good thanks!

自调用（Self-call）

一个参与者可以调用自己的方法。

sequenceDiagram
    participant Alice
    Alice->>Alice: Think about it

激活（Activation）

激活用于表示某个参与者在处理某个操作时的活动时间。可以通过 activate 和 deactivate 关键字来表示。

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Do something
    activate Bob
    Bob-->>Alice: Done
    deactivate Bob

备注（Notes）

备注用于添加额外的信息。可以放在参与者的旁边或消息上方。

sequenceDiagram
    participant Alice
    participant Bob
    note right of Alice: Alice thinks
    Alice->>Bob: Hello Bob, how are you?
    note over Alice,Bob: A shared note

高级语法

循环（Loops）

循环用于表示重复的操作。

sequenceDiagram
    participant Alice
    participant Bob
    loop Every day
        Alice->>Bob: Hello Bob, how are you?
        Bob-->>Alice: I am good thanks!
    end

选择（Alternatives）

选择用于表示条件分支。

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Do you want to go out?
    alt Success
        Bob-->>Alice: Yes!
    else Failure
        Bob-->>Alice: No.
    end

并行（Parallel）

并行用于表示并发的消息。

sequenceDiagram
    participant Alice
    participant Bob
    participant Carol
    Alice->>Bob: Message 1
    Alice->>Carol: Message 2
    par
        Bob-->>Alice: Response 1
    and
        Carol-->>Alice: Response 2
    end

以下是一个包含多个元素的完整时序图示例：

sequenceDiagram
    participant User
    participant Server
    participant Database

    User->>Server: Request data
    activate Server
    Server->>Database: Query
    activate Database
    Database-->>Server: Result
    deactivate Database
    Server-->>User: Response
    deactivate Server

    note over User,Server: Interaction completed

使用方法

在线工具：可以在 Mermaid 官方网站或其他支持 Mermaid 的在线工具中直接编写和预览 Mermaid 代码。
本地安装：通过 npm 安装 Mermaid 并在本地使用。例如：npm install -g @mermaid-js/mermaid-cli
集成到文档：在支持 Mermaid 的文档工具中如 GitHub、GitLab、Obsidian、Notion 等直接使用 Mermaid 代码块。

Obsidian 下使用

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

优势与局限

优势

快速简洁：通过简单的文本描述即可生成复杂的图表。
可读性高：相比于手工绘制的图表，Mermaid 代码更具可读性和可维护性。
易于集成：与多种平台和工具的良好集成，使得 Mermaid 成为文档编写和项目管理的利器。

局限

自定义功能有限：虽然 Mermaid 提供了丰富的图表类型，但在某些复杂的自定义需求上可能不如专业的绘图工具。
性能问题：在处理非常复杂的大型图表时，可能会遇到性能问题。

Mermaid 作为一款轻量级的图表生成工具，非常适合用于日常文档编写和项目管理，尤其是在需要快速、动态生成图表的场景下。