yixiong/MorphDoc
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity
Files
main
MorphDoc/samples/tutorials/echarts-tutorial.md
T

13 KiB
Raw Permalink Blame History

title, author, keywords
title author keywords
Markdown ECharts 图表教程 墨呈
ECharts
Markdown
图表
教程

Markdown ECharts 图表教程

本教程介绍如何在 Markdown 中通过 echarts 围栏插入可打印的 ECharts 图表。围栏内容使用 YAML，图表会以 SVG 渲染，并与正文一起进入快速 预览、精确预览和最终 PDF。

echarts 围栏不是普通的 yaml 代码块。请保留开头和结尾的三个反引号， 并将开头写成 echarts。

一、最小可用示例

下面的内容可以直接复制到 Markdown 正文中：

```echarts
version: 1
caption: 各部门季度完成量
height: 58mm
theme: document
option:
  xAxis:
    type: category
    data: [研发, 产品, 设计, 运营]
  yAxis:
    type: value
  series:
    - name: 完成量
      type: bar
      data: [28, 22, 17, 25]
```

实际渲染效果如下：

version: 1
caption: 各部门季度完成量
height: 58mm
theme: document
option:
  xAxis:
    type: category
    data: [研发, 产品, 设计, 运营]
  yAxis:
    type: value
  series:
    - name: 完成量
      type: bar
      data: [28, 22, 17, 25]

二、围栏外层字段

围栏最外层只支持下表中的字段，其他字段必须放入 option。

字段 类型 必填 功能 默认值 示例
version 整数 否 ECharts 围栏协议版本，目前只能是 1 1 version: 1
height 长度字符串 否 固定图表高度，支持 mm、cm、in、px 80mm height: 65mm
aspectRatio 正数 否 按内容宽度计算宽高比，最大为 10 无 aspectRatio: 1.6
theme 枚举 否 图表配色，可选 document、light、dark document theme: light
caption 字符串 否 显示在图表下方的图注，最长 500 个字符 无 caption: 图1 月度趋势
option 对象 是 ECharts 的纯数据配置对象 无 option: { ... }

尺寸规则：

  • 未设置 height 和 aspectRatio 时，高度默认为 80mm；
  • 同时设置两者时，以显式 height 作为固定高度；
  • 普通统计图建议使用 50mm～85mm；
  • 关系图或层级图可使用 80mm～120mm；
  • 图表超过单页内容区时，系统会等比例缩小到一页内。

三、option 常用字段

option 使用 ECharts 官方的纯数据结构。下表列出正式文档最常用的字段， 不是 ECharts 全部能力的穷举。

字段 类型 功能 示例
title 对象 图内标题、副标题及位置 title: { text: 月度趋势, left: center }
legend 对象 系列图例、方向和位置 legend: { top: 0 }
tooltip 对象 浏览器预览中的提示方式 tooltip: { trigger: axis }
grid 对象 直角坐标图的绘图区边距 grid: { left: 48, right: 24 }
xAxis 对象或数组 横轴类型、类目和标签 xAxis: { type: category }
yAxis 对象或数组 纵轴类型、范围和名称 yAxis: { type: value }
dataset 对象或数组 多系列共享的表格型数据源 dataset: { source: [...] }
series 数组 图表系列；每项必须有受支持的 type series: [{ type: line, data: [...] }]
radar 对象 雷达图指标名称和最大值 radar: { indicator: [...] }
visualMap 对象 热力图等数值到颜色的映射 visualMap: { min: 0, max: 100 }

建议用 caption 表示“图 1、数据来源、统计口径”等打印说明；title 适合需要在图形内部显示的标题。两者同时使用时会分别显示。

三种标题不要混用

位置 写法 用途
文档章节标题 Markdown 的 ## 标题 组织整篇文档的章节层级
图表内部标题 option.title.text 显示在 SVG 图形内部，可带副标题
图表下方图注 围栏外层的 caption 图号、数据来源、统计口径和补充说明

option.title 常用字段：

字段 功能 示例
text 图内主标题 text: 上半年项目交付趋势
subtext 主标题下方的副标题 subtext: 统计周期：2026年1—6月
left 水平位置，可用像素、百分比、left、center、right left: center
top 垂直位置，可用像素、百分比、top、middle、bottom top: 4
textStyle 主标题字体样式 textStyle: { fontSize: 18 }
subtextStyle 副标题字体样式 subtextStyle: { fontSize: 12 }

option.legend 会从 series[].name 或 dataset 列名生成图例。多系列 图表应为每个系列设置清晰的 name，并给标题、图例和绘图区留出互不 重叠的空间。

四、图表标题与顶部图例：折线图

```echarts
version: 1
caption: 图1 项目交付统计；数据来源：项目管理系统
height: 76mm
option:
  title:
    text: 上半年项目交付趋势
    subtext: 统计周期：2026年1—6月
    left: center
    top: 4
    textStyle:
      fontSize: 18
    subtextStyle:
      fontSize: 12
  tooltip:
    trigger: axis
  legend:
    data: [计划, 实际]
    top: 48
  grid:
    left: 48
    right: 24
    bottom: 32
    top: 82
    containLabel: true
  xAxis:
    type: category
    boundaryGap: false
    data: [一月, 二月, 三月, 四月, 五月, 六月]
  yAxis:
    type: value
    name: 项目数
  series:
    - name: 计划
      type: line
      smooth: true
      data: [12, 15, 18, 20, 24, 28]
    - name: 实际
      type: line
      smooth: true
      data: [10, 16, 17, 22, 23, 31]
```

version: 1
caption: 图1 项目交付统计；数据来源：项目管理系统
height: 76mm
option:
  title:
    text: 上半年项目交付趋势
    subtext: 统计周期：2026年1—6月
    left: center
    top: 4
    textStyle:
      fontSize: 18
    subtextStyle:
      fontSize: 12
  tooltip:
    trigger: axis
  legend:
    data: [计划, 实际]
    top: 48
  grid:
    left: 48
    right: 24
    bottom: 32
    top: 82
    containLabel: true
  xAxis:
    type: category
    boundaryGap: false
    data: [一月, 二月, 三月, 四月, 五月, 六月]
  yAxis:
    type: value
    name: 项目数
  series:
    - name: 计划
      type: line
      smooth: true
      data: [12, 15, 18, 20, 24, 28]
    - name: 实际
      type: line
      smooth: true
      data: [10, 16, 17, 22, 23, 31]

五、底部图例：使用 dataset 的柱状图

dataset.source 适合把数据集中写成一张表，多个系列再按列读取。

```echarts
version: 1
caption: 图2 分区域合同额与回款额（单位：万元）
height: 70mm
option:
  title:
    text: 分区域合同执行情况
    left: center
    top: 4
  legend:
    bottom: 2
  tooltip:
    trigger: axis
  grid:
    left: 48
    right: 24
    top: 48
    bottom: 52
    containLabel: true
  dataset:
    source:
      - [区域, 合同额, 回款额]
      - [东区, 820, 690]
      - [南区, 760, 610]
      - [西区, 540, 480]
      - [北区, 680, 570]
  xAxis:
    type: category
  yAxis:
    type: value
  series:
    - type: bar
    - type: bar
```

version: 1
caption: 图2 分区域合同额与回款额（单位：万元）
height: 70mm
option:
  title:
    text: 分区域合同执行情况
    left: center
    top: 4
  legend:
    bottom: 2
  tooltip:
    trigger: axis
  grid:
    left: 48
    right: 24
    top: 48
    bottom: 52
    containLabel: true
  dataset:
    source:
      - [区域, 合同额, 回款额]
      - [东区, 820, 690]
      - [南区, 760, 610]
      - [西区, 540, 480]
      - [北区, 680, 570]
  xAxis:
    type: category
  yAxis:
    type: value
  series:
    - type: bar
    - type: bar

六、饼图：名称与数值

饼图数据项使用 { name, value } 结构。正式文档中建议控制分类数量， 避免标签过密。

```echarts
version: 1
caption: 图3 年度预算构成
height: 68mm
option:
  title:
    text: 年度预算构成
    subtext: 单位：%
    left: "62%"
    top: 6
    textAlign: center
  tooltip:
    trigger: item
  legend:
    orient: vertical
    left: left
  series:
    - name: 预算
      type: pie
      radius: ["35%", "68%"]
      center: ["62%", "50%"]
      data:
        - { name: 软件采购, value: 36 }
        - { name: 基础设施, value: 28 }
        - { name: 运维服务, value: 22 }
        - { name: 培训推广, value: 14 }
```

version: 1
caption: 图3 年度预算构成
height: 68mm
option:
  title:
    text: 年度预算构成
    subtext: 单位：%
    left: "62%"
    top: 6
    textAlign: center
  tooltip:
    trigger: item
  legend:
    orient: vertical
    left: left
  series:
    - name: 预算
      type: pie
      radius: ["35%", "68%"]
      center: ["62%", "50%"]
      data:
        - { name: 软件采购, value: 36 }
        - { name: 基础设施, value: 28 }
        - { name: 运维服务, value: 22 }
        - { name: 培训推广, value: 14 }

七、雷达图：指标与最大值

雷达图必须提供非空的 radar.indicator。每组 series.data[].value 至少要包含与指标数量相同的数值。

```echarts
version: 1
caption: 图4 项目综合评价
height: 72mm
option:
  legend:
    data: [项目甲, 项目乙]
  radar:
    indicator:
      - { name: 进度, max: 100 }
      - { name: 质量, max: 100 }
      - { name: 成本, max: 100 }
      - { name: 风险, max: 100 }
      - { name: 满意度, max: 100 }
  series:
    - type: radar
      data:
        - name: 项目甲
          value: [86, 92, 78, 81, 90]
        - name: 项目乙
          value: [91, 84, 88, 76, 85]
```

八、关系图：节点与连线

关系图使用 data 或 nodes 描述节点，使用 links 或 edges 描述关系。 连线的 source、target 必须引用已存在的节点名称或 ID。

```echarts
version: 1
caption: 图5 项目协同关系
height: 78mm
option:
  series:
    - type: graph
      layout: force
      roam: false
      label:
        show: true
      force:
        repulsion: 260
        edgeLength: 90
      data:
        - { id: pm, name: 项目经理, symbolSize: 58 }
        - { id: dev, name: 研发组, symbolSize: 48 }
        - { id: test, name: 测试组, symbolSize: 48 }
        - { id: ops, name: 运维组, symbolSize: 48 }
      links:
        - { source: pm, target: dev, value: 3 }
        - { source: pm, target: test, value: 2 }
        - { source: dev, target: ops, value: 1 }
        - { source: test, target: ops, value: 2 }
```

九、系列类型与数据形状

当前支持 17 种系列。下表重点说明每种系列最容易写错的数据结构。

series[].type 主要数据结构 示例或要求
line、bar 数值数组或 dataset.source data: [12, 18, 24]
scatter 坐标二元数组 data: [[12, 18], [16, 25]]
pie、funnel、gauge 名称和有限数值 { name: 已完成, value: 72 }
radar 指标值数组 { name: 项目甲, value: [86, 92, 78] }
heatmap x、y、值三元数组 data: [[0, 0, 32], [1, 0, 48]]
boxplot 最小值、Q1、中位数、Q3、最大值 data: [[5, 12, 18, 24, 36]]
candlestick 开盘、收盘、最低、最高 data: [[20, 24, 18, 28]]
tree 递归 children 节点 data: [{ name: 总部, children: [...] }]
treemap、sunburst 带数值的递归叶节点 { name: 产品线A, value: 36 }
graph 节点和关系边 data: [...] 配合 links: [...]
sankey、chord 节点和带权关系边 关系边需要有限数值 value
pictorialBar 与柱状图相同 可使用安全的内嵌 path:// 矢量路径

每个系列必须直接提供非空 series[].data，或者通过有效的 dataset.source 提供数据。部分关系图使用 nodes 和 links，不采用 普通 data 数组。

十、安全与错误处理

为了确保离线、可复现和安全渲染，配置只能包含纯数据：

  • 不支持 JavaScript 函数、自定义脚本或 HTML formatter；
  • 不允许外部图片、跳转链接和远程资源；
  • 不支持 custom 系列；
  • YAML 锚点、别名和自定义标签会被拒绝；
  • option 中的原型污染属性会被拒绝；
  • 单个围栏 YAML 不能超过 512 KiB；
  • 配置错误只会显示局部错误占位，不会中断整篇文档。

下面是一个会产生局部错误提示的示例，请勿在正式文档中使用：

```echarts
version: 1
option:
  series:
    - type: pie
      data: []
```

错误信息会指出类似 option.series.0.data 的配置路径，便于定位问题。

十一、排版建议

  1. caption 用于图号、数据来源和统计口径，正文标题用于章节结构。
  2. 正式报告优先使用少量稳定颜色，并确保黑白打印仍能区分系列。
  3. 横轴类目过多时，优先拆图、旋转标签或改用横向柱状图。
  4. 图表、图注会作为一个不可拆分媒体块参与分页。
  5. 导出前使用“精确”预览检查最终分页、图例和标签。
Reference in New Issue View Git Blame Copy Permalink