超越 Mermaid：使用 Vega-Lite 与 Markdown 创建丰富的图表

为什么图表在文档中至关重要

当您向阅读文档的人解释数据时，一图胜千言。图表有助于读者一目了然地发现趋势、理解分布并掌握模式。在 2026 年 6 月 30 日，随着越来越多团队自动化其文档和知识库，直接在 Markdown 中嵌入丰富可视化效果的能力正变得不可或缺。

挑战在于，许多图表工具的设计要么追求简单，要么追求强大，但很少两者兼顾。您需要的是易于生成、外观专业且能自然融入文档工作流的工具。

Mermaid 的优势（以及它的局限）

Mermaid 在其擅长的领域表现出色：流程图、时序图、甘特图、饼图和基础柱状图。如果您的图表需求较简单，Mermaid 是合适的选择。它得到了广泛支持，易于编写，且能在大多数 Markdown 环境中渲染。

但 Mermaid 并不是为统计可视化设计的。尝试创建一个显示两个变量之间关系的散点图。尝试一个显示跨类别强度的热力图。尝试一个比较分布的箱线图。Mermaid 要么做不到，要么做得不好。如果您需要超越 Mermaid 内置图表类型集的功能，就会陷入困境。

这一局限性很重要，因为数据可视化在技术文档中越来越普遍。无论您是要展示 API 响应时间、功能采用率，还是用户参与度模式，您都会很快超出 Mermaid 所能提供的范围。

介绍 Vega-Lite：一种更强大的方法

Vega-Lite 是一种用于创建交互式可视化效果的声明式语法。您无需手动绘制图表，而是使用 JSON 对其进行描述。您指定数据，将列映射到视觉属性（X 轴、Y 轴、颜色、大小），Vega-Lite 便会为您渲染出可视化效果。

这种方法有几个优点。首先，它很灵活：Vega-Lite 支持柱状图、折线图、散点图、热力图、箱线图、面积图以及数十种其他类型。其次，它是数据驱动的：您为其提供数据集并告诉它如何对数据进行视觉编码。第三，它能很好地与 Markdown 结合：您可以将 Vega-Lite 规范直接嵌入到文档中。

理解 Vega-Lite JSON 规范

Vega-Lite 规范是一个用于描述图表的 JSON 对象。以下是一个创建散点图的简单示例：

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "title": "Product Sales vs Marketing Spend",
  "data": {
    "values": [
      {"spend": 1000, "sales": 5000},
      {"spend": 2000, "sales": 8000},
      {"spend": 3000, "sales": 12000}
    ]
  },
  "mark": "point",
  "encoding": {
    "x": {"field": "spend", "type": "quantitative"},
    "y": {"field": "sales", "type": "quantitative"}
  }
}

该规范表明：提取提供的数据，将每行绘制为一个点，将 spend 值放在 X 轴上，并将 sales 值放在 Y 轴上。Vega-Lite 会处理渲染。

您可以使其变得更加复杂：添加颜色、大小、多图层、过滤或交互式功能。但即使是像这样简单的规范，也能涵盖 Mermaid 无法处理的使用场景。

在 Markdown 中嵌入 Vega-Lite

要在 Markdown 中嵌入 Vega-Lite 图表，您通常使用带有特殊渲染器的代码块。某些 Markdown 环境支持 vega-lite 作为语言标识符：

{"$schema": "https://vega.github.io/schema/vega-lite/v5.json", "data": {"values": [{"x": 1, "y": 2}, {"x": 2, "y": 4}]}, "mark": "line", "encoding": {"x": {"field": "x"}, "y": {"field": "y"}}}

其他平台则要求您使用渲染 Vega-Lite 规范的服务。某些文档工具原生支持 Vega-Lite；其他工具则需要插件或封装器。

相比静态图像的优势在于：这些图表是交互式的。读者可以悬停查看精确值、放大细节，或切换数据系列的显示与隐藏。

与 AI 和自动化的集成

Vega-Lite 适用于 AI 驱动文档的原因之一在于，JSON 格式非常易于语言模型生成。当您要求 AI 代理“创建一个展示此数据的图表”时，它可以无歧义地输出有效的 Vega-Lite 规范。

这开启了全新的工作流。想象一下某种文档生成技能，它接收原始数据并自动生成恰当的可视化效果，然后将其嵌入到 Markdown 中。或者一个能接收新数据集并按需重新生成图表的文档流水线。

AI 代理还可以为您的数据选择合适的图表类型。语言模型可以查看您的数据集并决定：“这看起来像一个分布——我将使用直方图。”或者“这是时间序列数据——我将使用折线图。”这省去了手动决定使用哪种图表的步骤。

构建图表生成工作流

步骤 1：准备您的数据

以结构化格式收集数据。JSON 数组效果很好，但 CSV 或其他格式也没问题。请确保每个记录都有清晰的字段名称。

[
  {"month": "January", "revenue": 45000, "expenses": 32000},
  {"month": "February", "revenue": 52000, "expenses": 35000},
  {"month": "March", "revenue": 58000, "expenses": 38000}
]

步骤 2：设计您的可视化

思考您的数据传达了什么故事。您展示的是趋势？对比？还是分布？这决定了您的图表类型。

步骤 3：生成 Vega-Lite 规范

编写 JSON 规范，或使用 AI 工具生成它。指定数据源、图表类型以及列如何映射到视觉属性。

步骤 4：嵌入到 Markdown 中

将规范插入到 Markdown 文档中的代码块中。验证其是否正确渲染。

步骤 5：说明图表

简要说明该图表展示的内容及其重要性。上下文能将可视化转化为有价值的信息。

常见图表类型及其适用场景

散点图非常适合展示两个连续变量之间的关系。热力图在展示跨两个维度的强度方面表现出色。箱线图可以比较不同组别之间的分布。折线图用于跟踪随时间变化的情况。柱状图则跨类别比较数值。正确的选择取决于您的数据和您要解答的问题。

局限性与权衡

Vega-Lite 功能强大，但并不适合所有使用场景。极大的数据集（数百万行）可能会降低渲染速度。一些专门的图表类型超出了 Vega-Lite 的范围。此外，对于复杂的可视化，Vega-Lite 规范可能会变得有些冗长。

此外，并非所有 Markdown 查看器都支持 Vega-Lite。GitHub 的 Markdown 渲染器原生不支持它，不过 GitHub-Flavored Markdown wiki 和某些文档平台支持。如果您的读者在不支持 Vega-Lite 的平台上阅读您的文档，图表将无法渲染。

结论

Vega-Lite 填补了文档工具链中的重要空白。它能够处理统计可视化，与 Markdown 无缝集成，与 AI 驱动的自动化良好协同，并能生成交互式图表。如果您已经超出了 Mermaid 的功能范围，它自然是下一步的理想选择。

优点

• 支持数十种超出 Mermaid 所提供范围的图表类型
• 声明式 JSON 格式简单直观且对 AI 友好
• 悬停提示框和缩放等交互式功能提高了可读性
• 干净地嵌入到 Markdown 中，无需外部图像文件
• 免费且开源
• 可在浏览器中运行，无需后端渲染

缺点

• 并非所有 Markdown 渲染器都原生支持（尤其是 GitHub）
• 对于复杂图表，学习曲线比 Mermaid 更陡峭
• 大型数据集可能会影响渲染性能
• 与其他声明式图表语言相比，JSON 规范较为冗长
• 需要平台支持才能渲染；否则会退化为未渲染的代码块

注意事项

本文中的数据、字段名称和示例值均为示意性占位符。在生产文档中使用 Vega-Lite 之前，请在读者将要查看它们的平台上测试您的图表。某些环境需要额外的配置或插件才能渲染 Vega-Lite。请务必验证缩放和过滤等交互功能是否按预期工作。请自行承担风险，并根据您具体的文档平台和读者群体调整方法。

常见问题

• 如何将现有的 Mermaid 图表转换为 Vega-Lite？
• Vega-Lite 能否处理实时数据或流数据？
• 在一页中嵌入多个 Vega-Lite 图表对性能有什么影响？
• 如何设置 Vega-Lite 图表的样式以匹配我的文档主题？
• Vega-Lite 与 Vega 相同吗？它们有什么区别？
• Vega-Lite 能否生成适用于 PDF 的可打印图表？
• 如何使 Vega-Lite 图表在移动设备上具备响应式能力？
• Vega-Lite 中的哪些图表类型最适合用于组间比较？

标签

#dataviz #vega-lite #markdown #documentation #charts #visualization #json #webdev #tutorial #analytics