argon-theme/.kiro/specs/mermaid-codeblock-magic/user-guide.md

# Mermaid 图表渲染使用指南

## 简介

Argon 主题内置了强大的 Mermaid 图表渲染引擎，支持在文章中插入各种类型的流程图、时序图、甘特图等。本指南将帮助你快速上手使用。

## 基本用法

### 方法 1: 使用代码块（推荐）

在 Markdown 编辑器中，使用代码块语法插入 Mermaid 图表：

````markdown
```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
```
````

### 方法 2: 使用 Shortcode

如果你的 WordPress 编辑器支持 Shortcode，可以使用：

```
[mermaid]
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
[/mermaid]
```

### 方法 3: 使用 Markdown 容器语法

```markdown
::: mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
:::
```

## 支持的图表类型

### 1. 流程图 (Flowchart)

```mermaid
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
    C --> D
```

**语法说明:**
- `graph TD`: 从上到下的流程图（Top Down）
- `graph LR`: 从左到右的流程图（Left Right）
- `A[文本]`: 矩形节点
- `B{文本}`: 菱形节点（判断）
- `C((文本))`: 圆形节点
- `-->`: 箭头连接
- `-->|文本|`: 带标签的箭头

### 2. 时序图 (Sequence Diagram)

```mermaid
sequenceDiagram
    participant A as 用户
    participant B as 服务器
    A->>B: 发送请求
    B-->>A: 返回响应
```

**语法说明:**
- `participant`: 定义参与者
- `->>`: 实线箭头
- `-->>`: 虚线箭头
- `as`: 别名

### 3. 甘特图 (Gantt Chart)

```mermaid
gantt
    title 项目计划
    dateFormat YYYY-MM-DD
    section 阶段1
    任务1 :a1, 2024-01-01, 30d
    任务2 :after a1, 20d
    section 阶段2
    任务3 :2024-02-01, 12d
```

### 4. 类图 (Class Diagram)

```mermaid
classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
```

### 5. 状态图 (State Diagram)

```mermaid
stateDiagram-v2
    [*] --> 待处理
    待处理 --> 处理中
    处理中 --> 已完成
    处理中 --> 失败
    失败 --> 待处理
    已完成 --> [*]
```

### 6. ER 图 (Entity Relationship Diagram)

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

### 7. 饼图 (Pie Chart)

```mermaid
pie title 市场份额
    "产品A" : 45
    "产品B" : 30
    "产品C" : 15
    "其他" : 10
```

### 8. Git 图 (Git Graph)

```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
```

### 9. 用户旅程图 (User Journey)

```mermaid
journey
    title 用户购物旅程
    section 浏览
      浏览商品: 5: 用户
      查看详情: 3: 用户
    section 购买
      加入购物车: 4: 用户
      结算: 2: 用户
```

## 交互功能

### 缩放控制

1. **鼠标滚轮缩放**: 按住 `Ctrl` (Windows) 或 `Cmd` (Mac) + 滚轮
2. **缩放按钮**: 点击工具栏的 `+` 和 `-` 按钮
3. **重置缩放**: 点击工具栏的 `⟲` 按钮
4. **双击缩放**: 双击图表智能缩放（默认大小 → 2倍 → 默认大小）

### 拖拽移动

- **鼠标拖拽**: 按住鼠标左键拖动图表
- **触摸拖拽**: 在移动设备上单指拖动

### 全屏查看

1. 点击工具栏的 `⛶` 按钮进入全屏
2. 按 `ESC` 键或再次点击按钮退出全屏
3. 全屏模式下仍可缩放和拖拽

### 导出图表

1. 点击工具栏的 `⬇` 按钮打开导出菜单
2. 选择导出格式：
   - **PNG**: 导出为图片文件（适合插入文档）
   - **SVG**: 导出为矢量图（适合编辑和打印）
3. 导出的图表会保持当前的缩放级别

## 主题支持

Mermaid 图表会自动跟随网站主题切换：

- **浅色模式**: 使用 Mermaid 默认主题
- **深色模式**: 使用 Mermaid 深色主题

切换主题时，图表会自动重新渲染，并保持当前的缩放级别和位置。

## 移动端支持

在移动设备上，Mermaid 图表支持：

1. **双指缩放**: 使用两根手指进行缩放
2. **单指拖拽**: 使用一根手指拖动图表
3. **响应式工具栏**: 工具栏会自动适配移动端屏幕

## 常见问题

### Q: 图表不显示怎么办？

**A:** 检查以下几点：
1. 确保 Mermaid 语法正确
2. 检查浏览器控制台是否有错误信息
3. 尝试刷新页面
4. 确保主题设置中启用了 Mermaid 支持

### Q: 图表渲染失败显示错误提示

**A:** 点击错误提示下方的"查看原始代码"，检查 Mermaid 语法是否正确。常见错误：
- 箭头语法错误（使用 `->` 而不是 `-->`）
- 节点 ID 重复
- 缺少必要的关键字

### Q: PJAX 页面切换后图表不显示

**A:** 这个问题已经修复。如果仍然遇到，请：
1. 清除浏览器缓存
2. 刷新页面
3. 检查主题是否是最新版本

### Q: 图表太大或太小

**A:** 使用以下方法调整：
1. 使用缩放按钮或滚轮缩放
2. 双击图表智能缩放
3. 在 Mermaid 代码中调整节点数量和布局

### Q: 导出的图片质量不好

**A:** 
1. 在导出前先放大图表
2. 导出 SVG 格式（矢量图，无损质量）
3. 使用专业的图片编辑软件进一步处理

### Q: 移动端无法缩放或拖拽

**A:** 
1. 确保图表已经渲染完成
2. 对于缩放，使用双指手势
3. 对于拖拽，确保图表已经放大（完全可见的图表不支持拖拽）

## 高级技巧

### 1. 自定义样式

在 Mermaid 代码中可以使用 `classDef` 定义自定义样式：

```mermaid
graph TD
    A[开始]:::highlight --> B[处理]
    B --> C[结束]:::highlight
    
    classDef highlight fill:#f9f,stroke:#333,stroke-width:4px
```

### 2. 添加链接

可以为节点添加点击链接：

```mermaid
graph TD
    A[首页] --> B[文章]
    click A "https://example.com" "访问首页"
    click B "https://example.com/post" "查看文章"
```

### 3. 添加注释

在 Mermaid 代码中使用 `%%` 添加注释：

```mermaid
graph TD
    %% 这是注释，不会显示在图表中
    A[开始] --> B[结束]
```

### 4. 子图

使用 `subgraph` 创建子图：

```mermaid
graph TD
    subgraph 模块A
        A1[功能1] --> A2[功能2]
    end
    subgraph 模块B
        B1[功能3] --> B2[功能4]
    end
    A2 --> B1
```

## 性能优化建议

1. **避免过于复杂的图表**: 节点数量建议不超过 50 个
2. **使用批量渲染**: 多个图表会自动批量渲染，避免阻塞页面
3. **优先渲染可见图表**: 视口外的图表会延迟渲染
4. **合理使用缩放**: 大图表建议先缩小再查看细节

## 调试模式

如果需要调试 Mermaid 渲染问题，可以在浏览器控制台中启用调试模式：

```javascript
// 启用调试模式
window.argonMermaidConfig.debugMode = true;

// 重新渲染所有图表
MermaidRenderer.renderAllCharts();
```

调试模式会在控制台输出详细的渲染日志。

## 参考资源

- [Mermaid 官方文档](https://mermaid-js.github.io/mermaid/)
- [Mermaid 在线编辑器](https://mermaid.live/)
- [Mermaid 语法速查表](https://mermaid-js.github.io/mermaid/#/./flowchart)

## 更新日志

### v1.0.0 (2026-01-22)
- ✅ 修复 PJAX 页面切换后图表不渲染的问题
- ✅ 修复 Mermaid 语法解析错误
- ✅ 添加错误处理和友好提示
- ✅ 实现工具栏和缩放控制
- ✅ 实现鼠标拖拽移动
- ✅ 实现图表导出（PNG、SVG）
- ✅ 实现全屏查看模式
- ✅ 实现主题自动同步
- ✅ 优化渲染性能（批量渲染、延迟加载）
- ✅ 添加移动端触摸手势支持
- ✅ 完善生命周期管理

## 技术支持

如果遇到问题或有建议，请：
1. 查看本文档的"常见问题"部分
2. 在主题 GitHub 仓库提交 Issue
3. 联系主题作者

---

**提示**: 本文档会随着功能更新而更新，建议收藏以便查阅。