当前位置：首页 > news >正文

打造一款支持 Mermaid 与 ECharts 的 Markdown 编辑器：基于 Vditor 的实战指南

news 2025/9/19 5:27:41

本文教你如何用 Vditor 快速搭建一个支持流程图、饼图等可视化图表的现代 Markdown 编辑器，无需复杂配置，开箱即用。

✅ 为什么选择 Vditor？

Markdown 是开发者和写作者最常用的轻量级标记语言，但传统编辑器对图表渲染（如 Mermaid 流程图、ECharts 数据可视化）支持薄弱。Vditor 是一款功能强大、开源免费的 Markdown 编辑器，原生支持：

Mermaid 图表（流程图、时序图、甘特图等）
ECharts 图表（饼图、柱状图、折线图等）
数学公式（KaTeX）
代码高亮、暗黑模式、拖拽上传等

更重要的是，它无需后端依赖，纯前端实现，可直接嵌入网页中，非常适合用于文档系统、知识库、笔记应用等场景。

🛠️ 实现效果预览

最终我们将实现一个如下功能的编辑器：

功能	支持情况
Markdown 编辑	✅
Mermaid 流程图渲染	✅
ECharts 饼图渲染	✅
代码高亮	✅
分屏预览	✅
响应式布局	✅

⚠️ 注意：实际运行时，图表会真实渲染，非占位图。

💡 完整代码实现（可直接复制使用）

🔧 第一步：HTML 结构

<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="UTF-8"><title>Markdown 编辑器 (支持 Mermaid & ECharts)</title><!-- 引入自定义样式 --><link rel="stylesheet" href="/static/css/index.css" /><style>body {font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;margin: 0;padding: 20px;background-color: #f5f5f5;}#editor-container {display: flex;height: 80vh;gap: 20px;}#vditor {flex: 1;border: 1px solid #ddd;border-radius: 4px;background-color: white;}</style>
</head>
<body><h1>Markdown 编辑器 (支持 Mermaid & ECharts)</h1><div id="editor-container"><div id="vditor"></div></div><!-- 引入 Vditor 的 JS 文件（本地部署） --><script src="/static/js/index.min.js"></script><script>document.addEventListener("DOMContentLoaded", () => {const vditor = new Vditor('vditor', {height: '100%',toolbarConfig: {pin: true // 固定工具栏},cache: {id: 'preview_id' // 缓存 ID，避免重复初始化},after: () => {// 初始化完成后自动填充示例内容vditor.setValue(`# 欢迎使用 Markdown 编辑器## Mermaid 流程图示例\`\`\`mermaid
graph TDA[开始] --> B{条件判断}B -->|是| C[执行操作1]B -->|否| D[执行操作2]C --> E[结束]D --> E
\`\`\`## ECharts 饼图示例\`\`\`echarts
{"title": {"text": "示例饼图","left": "center"},"tooltip": {"trigger": "item"},"legend": {"orient": "vertical","left": "left"},"series": [{"name": "访问来源","type": "pie","radius": "50%","data": [{ "value": 1048, "name": "搜索引擎" },{ "value": 735, "name": "直接访问" },{ "value": 580, "name": "邮件营销" },{ "value": 484, "name": "联盟广告" },{ "value": 300, "name": "视频广告" }],"emphasis": {"itemStyle": {"shadowBlur": 10,"shadowOffsetX": 0,"shadowColor": "rgba(0, 0, 0, 0.5)"}}}]
}
\`\`\`## 普通 Markdown 内容- **加粗文本**
- *斜体文本*
- [链接](https://github.com/Vanessa219/vditor)> 这是一个引用块。\`\`\`python
def hello_world():print("Hello, World!")
\`\`\`
`);},preview: {delay: 500, // 延迟 500ms 渲染，提升体验// mode: 'both' // 默认分屏模式，也可设为 'preview' 单独预览}});});</script>
</body>
</html>

📦 文件结构说明（推荐项目结构）

为便于部署，请按如下结构组织文件：

your-project/
├── index.html             ← 主页面
├── static/
│   ├── css/
│   │   └── index.css      ← 可选自定义样式
│   └── js/
│       └── index.min.js   ← Vditor 的压缩版 JS（见下方获取方式）

✅ 重要提示：
index.min.js 不是自己写的，而是从 Vditor 官方 GitHub 发布页下载的 dist/index.min.js。
你也可以改用 CDN 加载（适合快速测试）：
<script src="https://unpkg.com/vditor@3.10.8/dist/index.min.js"></script>

⚠️ 若使用 CDN，记得移除本地 <script src="/static/js/index.min.js"></script>，避免冲突。

🎯 核心特性详解

1. Mermaid 支持

只需用三重反引号包裹 mermaid，即可渲染：

```mermaid
graph TDA --> B
```

Vditor 会自动识别并调用 Mermaid.js 渲染为 SVG 图形。

2. ECharts 支持

ECharts 图表通过 JSON 格式定义，同样用三重反引号包裹 echarts：

```echarts
{"title": { "text": "示例" },"series": [{ "type": "pie", "data": [...] }]
}
```

Vditor 内置了 ECharts 加载逻辑，无需手动引入。

3. 延迟渲染（preview.delay）

设置 delay: 500 让编辑器在你停止输入 500ms 后才重新渲染，大幅减少卡顿，提升体验。

4. 固定工具栏（pin: true）

让工具栏始终可见，即使滚动也能随时使用，特别适合长文档编辑。

🚀 如何部署？

方案一：静态网站部署（推荐新手）

下载 Vditor v3.10.8
解压后，复制 dist/index.min.js 到你的项目 /static/js/
创建 index.html，粘贴上方完整代码
使用任意静态服务器打开（如 VSCode Live Server、Python python -m http.server）

方案二：集成到 Vue/React 项目

Vditor 也支持作为组件集成进主流框架，详情请参考官方文档：
👉 https://b3log.org/vditor/

📌 常见问题解答

❓ 为什么我的图表不显示？

确保使用的是 Vditor ≥ 3.8.0 版本（Mermaid/ECharts 支持从该版本起加入）
检查浏览器控制台是否有报错（如跨域、JS 加载失败）
确认代码块语言标识为 mermaid 或 echarts，不是 javascript 或 json

❓ 能否自定义主题？

可以！通过 preview.theme 配置自定义 CSS 主题路径：

preview: {theme: {current: 'light',path: '/static/css/content-theme'}
}

❓ 是否支持数学公式？

支持！启用 math.engine: 'KaTeX' 即可：

math: {engine: 'KaTeX'
}

然后输入 $E=mc^2$ 就能渲染 LaTeX 公式！

✅ 总结：为什么这个方案值得推荐？

维度	优势
易用性	一行 JS 即可集成，无需后端
功能丰富	Mermaid + ECharts + KaTeX 一应俱全
性能优秀	延迟渲染 + 缓存机制，流畅不卡顿
开源免费	MIT 协议，可用于商业项目
响应式设计	自动适配移动端