Note-Gen 项目中 Mermaid 图表支持的技术解析与升级实践

背景介绍

Note-Gen 是一款基于 Vditor 开发的 Markdown 编辑器，近期用户反馈其内置的 Mermaid 图表渲染功能存在语法支持不足的问题。具体表现为某些 Mermaid 语法（特别是柱状图语法）无法正确渲染，这影响了用户创建数据可视化内容的能力。

问题分析

在 Note-Gen 的早期版本中，Mermaid 图表渲染存在以下技术限制：

1. 语法兼容性问题：用户尝试使用 bar 语法创建柱状图时，系统无法正确解析和渲染
2. 版本滞后：内置的 Mermaid 版本较旧，不支持新引入的图表类型和语法特性
3. 渲染机制差异：Mermaid 不同版本间存在语法解析和渲染实现的差异

技术解决方案

项目维护者采取了以下技术措施来解决这些问题：

1. 版本升级：将 Mermaid 从旧版本升级到 11.4.1 版本，这是当时的最新稳定版
2. 语法适配：针对新版 Mermaid 的语法规范，提供了替代的柱状图实现方案
3. 本地化加载优化：保持 Mermaid 资源的本地加载方式，而非依赖 CDN，确保稳定性和隐私性

新版实现示例

升级后，用户可以使用以下语法创建柱状图：

```mermaid
xychart-beta
    x-axis ["2024: 8%", "2029: 12.5%"]
    y-axis "福利支出预测" 0 --> 20
    bar [8, 12.5]
```

这种语法结构更加清晰：

• x-axis 定义X轴标签
• y-axis 定义Y轴范围和标题
• bar 指令定义具体数据值

技术影响与建议

1. 向后兼容性：虽然新版支持更多语法，但部分旧语法可能不再适用，建议用户迁移到新语法
2. 性能考量：Mermaid 11.4.1 在渲染复杂图表时性能有所提升
3. 开发建议：对于数据可视化需求，建议优先使用新版支持的图表类型

总结

Note-Gen 通过升级 Mermaid 版本显著增强了图表渲染能力，为用户提供了更丰富的数据可视化选项。这一改进体现了项目对用户体验的持续关注和技术栈的及时更新。用户现在可以更灵活地使用各种 Mermaid 图表来增强文档的表现力。