这是本节的多页打印视图。 .

Apache ECharts

使用结构化 JSON 或 YAML 创建响应式、本地优先图表。

1: ECharts 图表示例集
2: ECharts 回调与可信代码

echarts 短代码使用 Oink 随主题分发的固定版本 Apache ECharts 运行时渲染选项对象。Hugo 在构建阶段解析 JSON 或 YAML，把结果序列化到页面中，并且只在实际使用该组件的页面加载 ECharts。

当定量图表需要精确控制坐标轴、视觉编码、提示或序列时，请使用 ECharts。图表旁边仍要提供文字摘要，不能让结论依赖颜色、指针交互或 JavaScript。

快速开始

{{< echarts height="300px" >}}
xAxis:
  type: category
  data: [草稿, 评审, 发布]
yAxis:
  type: value
series:
  - type: bar
    data: [12, 9, 4]
{{< /echarts >}}

这个示例表示有 12 页草稿、9 页正在评审，另有 4 页可以发布。

Oink 如何加载图表

短代码会创建唯一的图表容器，并把解析后的选项保存到 application/json 元素中。即使同一页包含多个图表，页面也只会加入一次本地 ECharts 运行时与 Oink 初始化脚本。

未设置 theme 时，Oink 会按照站点当前配色模式初始化图表，并在读者切换模式时重新绘制。ResizeObserver 会让图表随容器缩放。显式指定 ECharts 主题后，该图表不再自动跟随站点配色模式。

短代码参数

参数	默认值	行为
`height`	`400px`	接受非负数字与 `px`、`rem`、`em`、`vh`、`vw` 或 `%` 单位
`theme`	未设置	使用指定的 ECharts 主题；未设置时跟随站点的深色或浅色模式
`full`	`false`	设为 `true` 后移除 Oink 的常规正文宽度限制

无效高度会让 Hugo 构建失败。短代码正文必须能够解析成 ECharts 选项对象；格式错误的 JSON 或 YAML 同样会在构建期报错，而不是静默生成空白图表。

选择指南

图表示例集演示数据集、柱状图、折线图、面积图、饼图、散点图、图例与视觉编码；
回调与可信代码解释格式化函数、数据驱动样式、$fn:name 桥接方式及其安全边界。

请先使用声明式 JSON 或 YAML；只有 ECharts 选项无法用数据表达时，才添加 JavaScript 回调。

创作检查清单

在正文中说明图表结论与数据范围；
明确标注坐标轴、单位、序列与时间范围；
不要只依靠颜色区分重要数值；
在站点深浅两种配色模式中检查图例与提示；
使用窄屏和较长译文标签测试图表；
多个序列共用记录时，优先使用共享 dataset；
非演示数据应注明来源与观察日期；
动画无助于理解时不要启用，自定义效果还应尊重减少动态效果偏好。

延伸参考

OINK 负责记录包装层与交付行为，完整选项 Schema 则以 Apache ECharts 为准。图表专用配置请查阅 ECharts 概念手册、数据集指南与选项参考。主题发行版随附的准确运行时版本与许可证记录在 VENDOR.json 中。

1 - ECharts 图表示例集

复制适合文档页面的声明式 ECharts 实用模式。

本页示例只使用结构化 YAML，不需要回调代码，因此处于最简单的 ECharts 创作与审查边界内。所有数字均为演示数据。

复用数据集

ECharts dataset 把记录与视觉编码分开。序列可以按名称引用维度，比重复维护多组平行数组更容易审查。

从数据集创建柱状图

{{< echarts height="320px" >}}
dataset:
  source:
    - [stage, minutes]
    - [草稿, 18]
    - [评审, 11]
    - [发布, 4]
xAxis: { type: category }
yAxis: { type: value, name: 分钟 }
series:
  - type: bar
    encode: { x: stage, y: minutes }
{{< /echarts >}}

示例表示中位耗时从撰写草稿的 18 分钟，逐步下降到发布阶段的 4 分钟。

折线与面积对比

多个序列描述同一组时间区间时，可以共用分类轴。面积填充突出总量，折线则保留各序列的趋势。

{{< echarts height="340px" >}}
tooltip: { trigger: axis }
legend: { data: [英文, 中文] }
xAxis:
  type: category
  data: [周一, 周二, 周三, 周四, 周五]
yAxis: { type: value, name: 页面 }
series:
  - name: 英文
    type: line
    smooth: true
    areaStyle: { opacity: 0.12 }
    data: [5, 8, 7, 11, 13]
  - name: 中文
    type: line
    smooth: true
    areaStyle: { opacity: 0.12 }
    data: [4, 6, 8, 9, 13]
{{< /echarts >}}

两种语言的评审队列都在周五达到 13 页；中文队列起点少一页，随后逐步追平。

环形占比图

环形图适合类别较少的部分与整体对比。请限制类别数量、直接显示标签，并在正文中给出总数。

{{< echarts height="340px" >}}
tooltip: { trigger: item }
legend: { bottom: 0 }
series:
  - name: 文档页面
    type: pie
    radius: [42%, 68%]
    avoidLabelOverlap: true
    label: { formatter: "{b}: {c}" }
    data:
      - { name: 指南, value: 28 }
      - { name: 参考, value: 17 }
      - { name: 教程, value: 11 }
      - { name: 概念, value: 8 }
{{< /echarts >}}

这组 64 页文档包含 28 页指南、17 页参考、11 页教程与 8 页概念说明。

使用视觉编码的散点图

visualMap 无需回调即可编码第三个维度。下面把构建规模同时映射为点的大小与颜色。

{{< echarts height="360px" >}}
tooltip: { trigger: item }
xAxis: { type: value, name: 构建秒数 }
yAxis: { type: value, name: 页面数 }
visualMap:
  - type: continuous
    dimension: 2
    min: 10
    max: 50
    inRange: { symbolSize: [10, 32], color: ["#60a5fa", "#f97316"] }
    right: 0
    top: middle
series:
  - type: scatter
    encode: { x: 0, y: 1, tooltip: [0, 1, 2] }
    data:
      - [1.8, 24, 12]
      - [2.6, 41, 22]
      - [3.9, 67, 35]
      - [5.1, 92, 48]
{{< /echarts >}}

在这组演示数据中，页面较多的站点构建时间也更长。点的大小和颜色同时编码第三个数值，因此颜色不是唯一线索。

生产环境说明

数据量较小且属于编辑内容时，可以把示例数据放在图表旁边。对于大型或生成的数据集，应在站点内容流水线中生成选项，并审查最终页面源码。Oink不会自动从远程端点获取图表数据；增加网络请求属于站点主动选择的集成，也会改变本地优先与隐私边界。

2 - ECharts 回调与可信代码

结构化选项不足时，使用经过审查的格式化与样式函数。

大多数 ECharts 选项都应保持为声明式 JSON 或 YAML。自定义格式化器、数据驱动样式等合法选项需要函数时，Oink 可以通过 JavaScript 围栏代码块与 $fn:name 引用支持这些场景。

可信作者边界

回调代码会在每位访问者的浏览器中执行，拥有页面同源环境下的常规 JavaScript 权限。Oink 会安全序列化结构化图表选项，但不会沙箱隔离作者提供的回调。只有可信的项目作者才能添加或审查这类代码。

短代码会输出行内注册脚本，因此回调还可能改变站点的内容安全策略（CSP）要求。能够用声明式选项表达同一行为时，请不要使用回调。

注册并引用函数

在短代码中加入一个或多个 js 或 javascript 围栏。使用具名 var、let、const 赋值或函数声明定义每个函数，再从 YAML 或 JSON 中通过 $fn:name 引用。

{{< echarts height="320px" >}}
```js
var formatMinutes = function (value) {
  return value + ' 分钟';
};
```

```yaml
yAxis:
  type: value
  axisLabel: { formatter: $fn:formatMinutes }
```
{{< /echarts >}}

Oink 会先移除 JavaScript 围栏，再解析剩余选项；初始化图表时注册具名函数，并在调用 chart.setOption() 前替换 $fn:name 值。

示例：标签与颜色

下面的图表会格式化耗时标签，并突出显示最慢阶段。演示数据表示撰写耗时 18 分钟、评审耗时 11 分钟、发布耗时 4 分钟。

回调检查清单

函数应保持确定性，而且只负责图表呈现；
不得读取 Cookie、凭据、存储或无关页面内容；
不得从格式化或样式回调中获取远程数据；
同一页包含多个图表时，使用唯一且含义清晰的函数名；
从外部示例复制的代码仍属于源码，必须审查并核对许可证；
按实际输入范围测试缺失值、null、字符串与数字；
检查站点深浅配色、窄屏、打印与减少动态效果行为。

故障排查

如果 $fn:name 没有解析，请确认拼写与同一页面中的具名声明完全一致，并确认围栏语言是 js 或 javascript。没有赋给名称的匿名表达式无法注册。

如果 Hugo 在渲染前失败，请先把正文缩减为有效 JSON 或 YAML，再逐个加入回调。浏览器控制台报错则表示结构化选项已经解析成功，但回调执行或某个 ECharts 选项仍需检查。