Mermaid 图表

Mermaid 图表语法参考

Tentarc 将 Mermaid 图表原生渲染为精美的主题化 SVG。使用本参考了解语法详情。

流程图

头部： graph LR（从左到右，推荐）或 graph TD（从上到下） 方向： LR（推荐）、RL、TD、TB、BT

节点形状

语法	形状
`A[text]`	矩形
`A(text)`	圆角矩形
`A{text}`	菱形（决策）
`A([text])`	体育场形
`A((text))`	圆形
`A[[text]]`	子程序
`A[(text)]`	圆柱体（数据库）
`A{{text}}`	六边形
`A>text]`	不对称旗帜
`A[/text\]`	梯形
`A[\text/]`	梯形（反向）
`A(((text)))`	双圆形

箭头类型

语法	样式
`-->`	实线箭头
`---`	实线（无箭头）
`-.->`	虚线箭头
`-.-`	虚线
`==>`	粗线箭头
`===`	粗线
`<-->`	双向实线
`<-.->`	双向虚线
`<==>`	双向粗线

边标签

graph LR
    A -->|label text| B
    C -- label text --> D

子图

graph LR
    subgraph Backend
        API --> DB
    end
    subgraph Frontend
        UI --> API
    end
    Client --> UI

带 ID 的子图

graph TD
    subgraph backend-services [Backend Services]
        direction LR
        API --> Cache
        API --> DB
    end

样式

graph LR
    A[Start]:::highlight --> B[End]
    classDef highlight fill:#f9f,stroke:#333
    style B fill:#bbf,stroke:#333

链式边

graph LR
    A --> B --> C --> D

并行链接

graph LR
    A & B --> C & D

状态图

头部： stateDiagram-v2

基本状态

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Complete: done
    Processing --> Error: fail
    Complete --> [*]
    Error --> Idle: retry

状态描述

stateDiagram-v2
    state "Waiting for input" as Waiting
    Waiting --> Processing

复合状态

stateDiagram-v2
    state "Active" as Active {
        Running --> Paused: pause
        Paused --> Running: resume
    }
    [*] --> Active
    Active --> [*]: complete

方向覆盖

stateDiagram-v2
    direction LR
    [*] --> A --> B --> [*]

时序图

头部： sequenceDiagram

消息类型

语法	含义
`->>`	实线，实心箭头
`-->>`	虚线，实心箭头
`-)`	实线，空心箭头（异步）
`--)`	虚线，空心箭头
`-x`	实线带 X（丢失消息）
`--x`	虚线带 X

参与者

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database

    C->>S: POST /api/users
    S->>DB: INSERT user
    DB-->>S: OK
    S-->>C: 201 Created

激活

sequenceDiagram
    Client->>+Server: Request
    Server->>+Database: Query
    Database-->>-Server: Results
    Server-->>-Client: Response

注释

sequenceDiagram
    Alice->>Bob: Hello
    Note right of Bob: Bob thinks
    Bob-->>Alice: Hi!
    Note over Alice,Bob: Conversation complete

循环

sequenceDiagram
    loop Every minute
        Client->>Server: Heartbeat
        Server-->>Client: ACK
    end

条件分支

sequenceDiagram
    Client->>Server: Request
    alt Success
        Server-->>Client: 200 OK
    else Failure
        Server-->>Client: 500 Error
    end

可选

sequenceDiagram
    opt If cached
        Server-->>Client: Cached response
    end

并行

sequenceDiagram
    par Parallel requests
        Client->>ServiceA: Request A
    and
        Client->>ServiceB: Request B
    end

类图

头部： classDiagram

带成员的类

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
        +move(distance) void
    }

可见性修饰符

符号	含义
`+`	公开
`-`	私有
`#`	受保护
`~`	包/内部

关系

语法	含义
`<\|--`	继承（extends）
`*--`	组合（contains）
`o--`	聚合（has）
`-->`	关联
`..>`	依赖
`..\|>`	实现（implements）
`--`	链接（实线）
`..`	链接（虚线）

基数

classDiagram
    Customer "1" --> "*" Order : places
    Order "1" *-- "1..*" LineItem : contains

完整示例

classDiagram
    class Animal {
        <<abstract>>
        +String name
        +int age
        +makeSound()* void
    }

    class Dog {
        +String breed
        +bark() void
    }

    class Cat {
        +bool indoor
        +meow() void
    }

    Animal <|-- Dog
    Animal <|-- Cat

注解

classDiagram
    class Service {
        <<interface>>
        +start() void
        +stop() void
    }

    class Logger {
        <<singleton>>
        -instance Logger
        +log(msg) void
    }

ER 图

头部： erDiagram

基本关系

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "is in"

基数表示法

左侧	右侧	含义
`\|\|`	`\|\|`	恰好一对一
`\|\|`	`o\|`	恰好一对零或一
`\|\|`	`o{`	恰好一对零或多
`\|\|`	`\|{`	恰好一对一或多
`o\|`	`o\|`	零或一对零或一
`o\|`	`o{`	零或一对零或多
`o{`	`o{`	零或多对零或多

实体属性

erDiagram
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        date created_at
    }

    USER ||--o{ ORDER : places

属性类型

常用属性标记：

PK - 主键
FK - 外键
UK - 唯一键

完整示例

erDiagram
    CUSTOMER {
        int id PK
        string email UK
        string name
        string phone
    }

    ORDER {
        int id PK
        int customer_id FK
        date order_date
        string status
    }

    PRODUCT {
        int id PK
        string name
        decimal price
        int stock
    }

    LINE_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
        decimal unit_price
    }

    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "included in"

最佳实践

优先使用水平（横向）布局

重要：尽可能使用水平布局（LR、RL）。水平图表在 UI 中更容易查看和导航。

流程图：使用 graph LR（从左到右）而不是 graph TD（从上到下）
状态图：在头部后添加 direction LR
时序图：天然水平，无需更改
类图：对于宽层次结构，考虑拆分为多个水平图表
ER 图：天然水平，无需更改

仅在以下情况使用垂直布局（TD、BT）：

图表本质上是层次结构的（组织架构图、树形结构）
垂直布局明显比水平布局更清晰
图表节点很少（最多 3-4 个）

保持图表专注

一个图表一个概念。如果图表变得复杂，将其拆分为多个图表。

使用描述性标签

graph LR
    A[User submits form] --> B{Validation}
    B -->|Valid| C[Save to database]
    B -->|Invalid| D[Show errors]

选择正确的方向

水平（推荐）：

LR（从左到右）：默认 - 用于流程、管道、状态机、过程和大多数图表
RL（从右到左）：反向流程（当语义上有意义时）

垂直（谨慎使用）：

TD（从上到下）：仅用于层次结构、继承、组织架构图等垂直结构必不可少的场景
BT（从下到上）：仅用于依赖关系向上指向的场景

验证复杂图表

使用 mermaid_validate 工具在输出复杂图表前检查语法：

mermaid_validate({ code: "graph TD\n  A --> B" })

故障排除

常见错误

缺少方向：流程图中始终包含方向（graph TD，不是只有 graph）
括号不平衡：确保所有 [、(、{ 都正确关闭
标签中的特殊字符：对包含特殊字符的标签使用引号
无效箭头语法：检查上面的箭头类型表

转义特殊字符

对于包含特殊字符的标签，用引号包裹：

graph LR
    A["Label with (parentheses)"] --> B["Label with [brackets]"]