Mermaid.js 图表和流程图

flowchart TD
    A[开始] --> B[处理]
    B --> C[结束]

渲染效果将自动呈现一个简单的流程图。

### 核心语法结构

所有 Mermaid 图表的定义都以图表类型声明开头，随后跟随方向或样式信息，最后是节点和连线的定义。基本格式如下：

```
图表类型 [方向]
    节点定义
    连线定义
```

下面我们将逐一解析最常用的图表类型。

## 流程图（Flowchart）

流程图是最常用的图表之一，用于表达步骤、决策和过程流向。

### 节点类型与形状

在 Mermaid 中，节点通过不同的括号组合来定义形状，例如：

| 形状         | 语法示例              |
|--------------|-----------------------|
| 矩形         | `A[矩形内容]`         |
| 圆角矩形     | `B(圆角矩形)`         |
| 菱形（判断） | `C{条件判断}`         |
| 圆形         | `D((圆形))`           |
| 非对称形状   | `E>不对称形状]`       |
| 子程序/块    | `F[[子程序]]`         |

### 连线与箭头

连线使用 `-->` 或 `---` 定义，可在连线上添加文字标签：

- 实线箭头：`A --> B`
- 不带箭头实线：`A --- B`
- 带文字箭头：`A -- 是 --> B`
- 粗箭头：`A ==> B`
- 虚线箭头：`A -.-> B`

### 方向控制

流程图的方向通过图表类型声明后的两个字母指定：

- `flowchart TD` 或 `TB`：自上而下（Top Down/Bottom）
- `flowchart LR`：从左到右（Left Right）
- `flowchart RL`：从右到左
- `flowchart BT`：自下而上

### 完整示例

```mermaid
flowchart LR
    A[用户登录] --> B{验证密码}
    B -- 正确 --> C[进入主页]
    B -- 错误 --> D[显示错误信息]
    D --> A
```

这个例子展示了一个登录流程，包含判断节点和循环结构。

## 序列图（Sequence Diagram）

序列图用于展示对象之间交互的时间顺序，特别适合描述 API 调用、消息传递过程。

### 参与者定义

使用 `participant` 关键字声明参与者，别名采用驼峰式命名：

```
sequenceDiagram
    participant 客户端 as 客户端
    participant 服务器 as 服务器
```

也可以直接使用 `participant 客户端` 的简写形式。

### 消息传递

- 实线同步消息：`客户端->>服务器: 发送请求`
- 虚线异步消息：`客户端-->>服务器: 异步通知`
- 返回消息（带激活框）：`服务器-->>客户端: 返回响应`

激活框（生命线）可使用 `activate` 和 `deactivate` 显式控制，或自动管理。

### 逻辑控制

Mermaid 支持在序列图中添加 `alt`-`else` 条件分支、`opt` 可选操作、`loop` 循环：

```
alt 登录成功
    客户端->>客户端: 保存令牌
else 登录失败
    客户端->>客户端: 提示重试
end
```

### 实战：OAuth 2.0 授权流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant C as 客户端
    participant S as 授权服务器
    U->>C: 点击登录
    C->>S: 请求授权码(code)
    S-->>C: 返回授权码
    C->>S: 携带授权码请求令牌(token)
    S-->>C: 返回access_token
    C->>C: 存储令牌，完成登录
```

## 类图（Class Diagram）

类图用于面向对象设计，描述类、接口、属性、方法及类之间的关系。

### 定义类

类使用 `class` 关键字定义，属性和方法直接在下方列出，`+` 表示公共，`-` 表示私有，`#` 表示保护：

```
classDiagram
    class 动物 {
        +String 名称
        +int 年龄
        +void 发出声音()
    }
```

### 继承与实现

关系类型通过特定的箭头语法表达：

- 继承（泛化）：`鸟类 --|> 动物`
- 实现接口：`企鹅 ..|> 可飞行` （虚线空心三角）
- 关联：`学生 --> 课程`
- 依赖：`人类 ..> 工具`
- 聚合：`汽车 o-- 发动机`
- 组合：`人 *-- 大脑`

### 示例：简单 Zoo 系统

```mermaid
classDiagram
    动物 <|-- 哺乳动物
    动物 <|-- 鸟类
    哺乳动物 <|-- 猫
    哺乳动物 <|-- 狗
    鸟类 <|-- 企鹅
    动物 : +String 名称
    动物 : +void 移动()
    鸟类 : +void 飞行()
    猫 : +void 喵喵叫()
    狗 : +void 汪汪叫()
```

## 状态图（State Diagram）

状态图用于描述对象在其生命周期内的状态变化及触发条件。

### 定义状态

使用 `state` 关键字或直接写状态名：

```
stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付 : 用户付款
    已支付 --> 已发货 : 商家发货
    已发货 --> 已完成 : 用户签收
    已完成 --> [*]
```

`[*]` 表示初始状态或最终状态，也可以添加 `<<fork>>` 复合状态。

### 复合状态

复合状态内部可以包含子状态图：

```
stateDiagram-v2
    state 正常状态 {
        [*] --> 空闲
        空闲 --> 忙碌 : 接到任务
        忙碌 --> 空闲 : 任务结束
    }
    正常状态 --> 故障状态 : 异常发生
    故障状态 --> 正常状态 : 修复完毕
```

## 甘特图（Gantt Chart）

甘特图用于展示项目计划、任务时间线和依赖关系。

### 基本结构

`gantt` 关键字后跟日期格式和标题，每个任务使用 `section` 分组：

```
gantt
    title 网站开发计划
    dateFormat  YYYY-MM-DD
    section 设计阶段
    UI设计           :a1, 2025-04-01, 7d
    评审             :after a1, 2d
    section 开发阶段
    前端开发         :2025-04-10, 10d
    后端开发         :2025-04-10, 12d
```

### 任务依赖

- `:after taskID` 表示在某个任务之后开始
- 可以使用 `:crit` 表示关键任务，显示为红色
- 可指定持续时间（如 `7d`）或具体结束日期

### 示例：迭代冲刺

```mermaid
gantt
    title Sprint 1 规划
    dateFormat  YYYY-MM-DD
    axisFormat %m-%d

    section 需求
    需求收集       :active, req, 2025-04-01, 3d
    需求评审       :after req, 1d

    section 开发
    用户注册模块   :dev1, after req, 5d
    登录模块       :dev2, after dev1, 3d
    测试           :after dev2, 2d
```

## 饼图（Pie Chart）

饼图语法极其简洁，适合快速展示占比。

### 语法

```
pie title 产品销量占比
    "手机" : 45
    "电脑" : 30
    "平板" : 15
    "其他" : 10
```

数值不需要加百分号，Mermaid 会自动计算百分比并生成图例。

### 完整示例

```mermaid
pie
    title 网站访问来源
    "直接访问" : 40
    "搜索引擎" : 25
    "社交媒体" : 20
    "邮件营销" : 15
```

## 其它常用图表速览

### 用户旅程图（Journey）

用于描述用户完成目标的步骤与情绪变化：

```
journey
    title 在线购物旅程
    section 浏览商品
      打开首页: 3: 用户
      搜索商品: 4: 用户
      查看详情: 5: 用户
    section 下单购买
      加入购物车: 4: 用户
      支付: 2: 用户
      收到确认: 5: 用户
```

每个步骤后跟 `数字: 参与者`，数字表示满意度（1-5）。

### Git 图（Gitgraph）

展示分支、合并和提交历史：

```
gitGraph
    commit
    branch develop
    checkout develop
    commit
    branch feature-a
    checkout feature-a
    commit
    commit
    checkout develop
    merge feature-a
    commit
    checkout main
    merge develop
    commit
```

## 样式与主题定制

Mermaid 允许通过初始化配置或 CSS 自定义图表外观。

### 调整主题

在 `mermaid.initialize` 中设置 `theme` 属性：

```javascript
mermaid.initialize({
  startOnLoad: true,
  theme: 'forest', // 可选: default, forest, dark, neutral, base
});
```

### 节点自定义样式

可以直接为节点添加类名，然后在 CSS 中定义样式。Mermaid 也支持内联表达式定义填充色：

```
flowchart LR
    A[普通节点]
    style A fill:#f9f,stroke:#333,stroke-width:4px
```

### 主题变量

使用 `themeVariables` 可以精细控制主题颜色：

```javascript
mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#1E90FF',
    primaryTextColor: '#fff',
    primaryBorderColor: '#000',
    lineColor: '#F00',
  }
});