VitePress Mermaid Pan & Zoom Plugin

一个为 VitePress 设计的插件，为 Mermaid 图表添加平移、缩放和全屏查看功能。让复杂的图表变得更易于浏览和查看。

⚠️ 前置要求

重要：使用本插件前，必须先正确安装和配置以下依赖：

• mermaid - Mermaid 图表库
• vitepress-plugin-mermaid - VitePress 的 Mermaid 集成插件

本插件是在 vitepress-plugin-mermaid 基础上的增强插件，不能独立使用。

✨ 特性

• 🔄 平移与缩放: 使用鼠标滚轮缩放，拖拽平移图表
• 🖥️ 全屏模式: 点击全屏按钮进入沉浸式查看体验
• 📊 缩放比例显示: 实时显示当前缩放比例
• 🎯 一键重置: 点击缩放比例快速重置到初始状态
• ⚡ 自动集成: 无需修改 Markdown 内容，自动应用到所有 Mermaid 图表
• 🎨 主题适配: 完美适配 VitePress 的明暗主题
• 📱 响应式设计: 支持移动端和桌面端
• 🪶 轻量级: 基于 svg-pan-zoom，性能优异

📦 安装

1. 安装必需的依赖

首先需要安装 Mermaid 相关的依赖包：

# npm
npm install mermaid vitepress-plugin-mermaid vitepress-plugin-mermaid-pan-zoom

# yarn
yarn add mermaid vitepress-plugin-mermaid vitepress-plugin-mermaid-pan-zoom

# pnpm
pnpm add mermaid vitepress-plugin-mermaid vitepress-plugin-mermaid-pan-zoom

2. 版本要求

• mermaid: ^11.6.0
• vitepress-plugin-mermaid: ^2.0.17
• vitepress-plugin-mermaid-pan-zoom: ^1.0.0

🚀 快速开始

1. 配置 VitePress

首先需要在 VitePress 配置文件中启用 Mermaid 支持：

// .vitepress/config.mts
import { defineConfig } from "vitepress";
import { withMermaid } from "vitepress-plugin-mermaid";

export default withMermaid(
  defineConfig({
    vite: {
      optimizeDeps: {
        include: [
          "mermaid",
          "dayjs",
          "debug",
          "@braintree/sanitize-url",
          "cytoscape",
          "cytoscape-cose-bilkent",
        ],
        exclude: ["vitepress"],
      },
    },
    mermaid: {
      // mermaid 配置选项
      // theme: 'default' // 可选：设置主题
    },
  })
);

2. 在 VitePress 主题中配置

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { useMermaidPanZoom } from 'vitepress-plugin-mermaid-pan-zoom'
import 'vitepress-plugin-mermaid-pan-zoom/dist/style.css'

export default {
  ...DefaultTheme,
  setup() {
    useMermaidPanZoom()
  }
}

3. 在 Markdown 中使用

现在你可以在 Markdown 文件中正常使用 Mermaid 图表，插件会自动为所有图表添加平移缩放功能：

```mermaid
graph TD
    A[开始] --> B{是否需要缩放?}
    B -->|是| C[使用鼠标滚轮缩放]
    B -->|否| D[直接查看]
    C --> E[拖拽平移图表]
    D --> F[点击全屏按钮]
    E --> F
    F --> G[享受更好的查看体验]
```

🎮 使用指南

基本操作

| 操作 | 功能 | |------|------| | 鼠标滚轮 | 缩放图表 | | 拖拽 | 平移图表 | | 点击全屏按钮 | 进入全屏模式 | | 点击缩放比例 | 重置缩放和位置 | | ESC 键 | 退出全屏模式 | | 点击模态框外部 | 退出全屏模式 |

界面元素

• 缩放比例显示: 显示当前缩放百分比，点击可重置
• 全屏按钮: 右上角的全屏图标，点击进入全屏模式
• 关闭按钮: 全屏模式下的关闭图标，点击退出全屏
• 缩放控件: 全屏模式下的 +/- 按钮，用于精确控制缩放

🔧 技术细节

重要说明

⚠️ 必须先安装并配置 vitepress-plugin-mermaid：本插件依赖于 vitepress-plugin-mermaid 来渲染 Mermaid 图表，然后在其基础上添加平移缩放功能。如果缺少基础的 Mermaid 配置，项目将无法正常启动。

核心依赖

• svg-pan-zoom: 提供 SVG 平移缩放功能
• VitePress: 静态站点生成器
• Mermaid: 图表渲染引擎
• vitepress-plugin-mermaid: VitePress 的 Mermaid 集成插件

缩放范围

• 最小缩放: 50% (0.5x)
• 最大缩放: 500% (5x)
• 默认状态: 自适应容器大小并居中

兼容性

• VitePress: ^1.0.0
• Vue: ^3.5.13
• 浏览器: 支持现代浏览器 (Chrome, Firefox, Safari, Edge)

依赖项

• svg-pan-zoom: ^3.6.1 - 提供核心的平移缩放功能

🎨 自定义样式

如果你需要自定义插件的样式，可以覆盖以下 CSS 类：

/* 内联模式的缩放显示 */
.mermaid-inline-zoom-display {
  /* 自定义样式 */
}

/* 全屏按钮 */
.mermaid-fullscreen-btn {
  /* 自定义样式 */
}

/* 模态框样式 */
.mermaid-modal-overlay {
  /* 自定义样式 */
}

/* 模态框内容 */
.mermaid-modal-content {
  /* 自定义样式 */
}

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• svg-pan-zoom - 提供核心的 SVG 平移缩放功能
• VitePress - 优秀的静态站点生成器
• Mermaid - 强大的图表绘制工具