MorphDoc/packages/markdown-echarts

@md-to-pdf/markdown-echarts

为 Markdown 增加安全、可验证、可复用的 ECharts YAML 围栏， 并在浏览器中渲染为 SVG。

该包不依赖 React、Paged.js 或特定 PDF 引擎。宿主可以将生成的 HTML 用于网页预览，也可以在图表完成渲染后交给 Chromium 输出 PDF。

基本语法

```echarts
height: 80mm
caption: 年度收入
option:
  xAxis:
    type: category
    data: [2023, 2024]
  yAxis:
    type: value
  series:
    - type: bar
      data: [120, 180]
```

围栏内容必须使用 YAML，并包含一个 ECharts option 对象。YAML 会先转换为安全的纯数据对象，再交给 ECharts；不能使用函数、 YAML 锚点、别名或自定义标签。

围栏字段

字段	类型	默认值	说明
version	1	1	围栏协议版本
height	CSS 长度	80mm	支持 mm、cm、in、px
aspectRatio	正数	无	与 height 二选一；指定后不补默认高度
theme	document、light、dark	document	ECharts 主题
caption	字符串	无	图表标题说明
option	对象	必填	经过安全和语义验证的 ECharts 配置

数据来源

每个系列必须从以下任一位置获得有效数据：

• 非空的 series[].data；
• 非空的 dataset.source；
• 引用具有有效上游数据源的内置 filter 或 sort transform。

只有表头的二维数组、所有列均为空的对象以及空数组不属于有效 数据。使用 dataset 时保留 ECharts 的默认维度映射，也可以通过 series.encode 显式声明映射。

option:
  dataset:
    source:
      - [year, sales]
      - [2025, 120]
      - [2026, 180]
  series:
    - type: line
      encode:
        x: year
        y: sales

系列验证规则

当前首版支持以下系列：

系列	主要规则
line	需要有效数据；支持直角坐标系和极坐标系
bar	需要有效数据；支持直角坐标系和极坐标系
scatter	直接数据至少包含两个坐标值
pie	直接数据项的 value 必须是有限数值
radar	必须提供非空 radar.indicator；数据维数不得少于指标数
heatmap	直角坐标数据为 [x, y, value]；日历数据为 [date, value]
boxplot	直接数据为 [min, Q1, median, Q3, max]
candlestick	直接数据为 [open, close, lowest, highest]

直角坐标系列缺少 xAxis 或 yAxis 时会补充空对象，让 ECharts 使用自身的轴默认值。极坐标、雷达和日历坐标系表达了明确语义， 因此不会猜测配置，缺少对应组件时会报告错误。

使用 dataset 时，验证器只验证数据源是否存在，不重复实现 ECharts 的维度推断和 encode 映射规则。

错误行为

配置错误不会中断整篇 Markdown。对应围栏会变成局部错误占位：

<div class="md-echarts-error" role="alert">
  ECharts 图表配置无效：option.series.0.data 必须是非空数组……
</div>

错误消息包含配置路径，便于用户或 AI Agent 定位并修正 YAML。 宿主还可以通过 onError 收集结构化错误。

markdown.use(markdownItECharts, {
  onError(error, context) {
    console.warn(error.code, error.message, context.tokenIndex);
  }
});

Markdown-it 接入

import MarkdownIt from "markdown-it";
import {
  markdownItECharts
} from "@md-to-pdf/markdown-echarts";

const markdown = new MarkdownIt().use(markdownItECharts);
const html = markdown.render(source);

如果宿主还会对 HTML 做安全过滤，需要保留包生成的 figure、 figcaption、隐藏配置节点及 data-echarts-* 属性。

浏览器渲染

import {
  renderEChartsBlocks
} from "@md-to-pdf/markdown-echarts/browser";
import "@md-to-pdf/markdown-echarts/styles.css";

const outcomes = await renderEChartsBlocks(document, {
  outputMode: "inline-svg",
  animation: false,
  concurrency: 2,
  timeoutMs: 5000
});

输出模式：

• interactive：保留 ECharts 实例和响应式尺寸监听；
• inline-svg：冻结为内联 SVG，适合打印和 PDF；
• svg-image：冻结为 SVG Data URL 图片。

PDF 输出前应等待所有图表、字体和图片完成，再开始分页或调用 Chromium page.pdf()。

安全边界

默认策略会拒绝：

• custom 系列及 renderItem；
• JavaScript、HTTP、文件和 Data URL 外部资源；
• HTML formatter；
• 原型污染属性；
• 未允许的 toolbox 功能；
• 非内置数据转换；
• 超过节点数、深度、字符串、数组和系列数量上限的配置。

这些限制适用于不受信任的 Markdown。宿主如需扩大能力，应在明确 风险后扩展验证器，而不是直接执行 YAML 中的 JavaScript。

扩展系列验证

各系列规则注册在 echartsSeriesValidators。新增图形时需要同步：

1. 将系列类型加入协议支持列表；
2. 在浏览器引擎中注册对应 ECharts Chart；
3. 注册该系列的语义验证器；
4. 增加有效、缺少数据、错误数据结构和真实 SVG 渲染测试。

参考：

• ECharts 配置参考
• ECharts Dataset
• ECharts Data Transform