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

最新推荐文章于 2025-09-19 21:54:48 发布

原创最新推荐文章于 2025-09-19 21:54:48 发布 · 983 阅读

23 ·

CC 4.0 BY-SA版权

文章标签：

#echarts #编辑器 #前端

VibeCoding·九月创作之星挑战赛 10w+人浏览 1.7k人参与

本文教你如何用 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 TD
    A[开始] --> 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 TD
    A --> 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 协议，可用于商业项目
响应式设计	自动适配移动端

💡 应用场景建议：

技术博客平台
内部知识库系统（如 Confluence 替代品）
学生作业提交系统
AI 笔记助手界面

📚 参考资料

Vditor 官网：https://b3log.org/vditor/
GitHub 仓库：https://github.com/Vanessa219/vditor
Mermaid 文档：https://mermaid.js.org/
ECharts 示例库：https://echarts.apache.org/examples/zh/index.html