ice-chart · 交互式图表库（当前 v0.23.4）

🧩 应用层 · 基于 ice-render 引擎 v2.14.1 封装（当前 v0.23.4）

本页属于 ice-render 家族的应用层产品：图表层只声明「数据 → 像素 → 语义事件」，命中测试与事件派发全部交给引擎内核。想了解底层引擎本身，请看左侧「ice-render 引擎」分组。

ice-chart 是构建在 ice-render 引擎之上的交互式图表库（当前 @damoqiongqiu/ice-chart v0.23.4）。 它不是「把数据画成图」的又一个图表库——命中测试、事件派发、嵌套坐标系、脏矩形局部重绘全部交给 ice-render 引擎，图表层只负责把「数据 ↔ 像素 ↔ 语义事件」这三件事打通。

于是悬停高亮、点击下钻、框选缩放、缩放平移、图例联动、跨图联动、键盘导航都是内建能力，而不是事后打补丁的插件——因为每一个系列组件都实现了 containsLocalPoint，把「画出来什么样」和「点得到哪里」统一在同一份像素缓存里。

MIT License · 作者：大漠穷秋（damoqiongqiu@126.com）

一个完整的实时大屏例子（就是仓库里的 `examples/dashboard-market.html`）

下面这个例子直接由文档静态托管的 ice-render + ice-chart UMD 运行时在文档页里画出（无需联网）：行情监控大屏（K 线、深度、资金流、板块、委托队列等一整屏图表），所有交互（悬停十字准星、框选缩放、图例联动、键盘导航）都由引擎内建。

这就是 ice-chart 的核心卖点：图表层不碰 DOM 事件，只声明「数据 → 像素 → 语义事件」，命中与派发全部由引擎承担。 同一份引擎实例池还能让多张图共享统一的事件语义，跨图联动因此水到渠成。

核心能力

能力	说明
图表类型	折线 / 面积 / 柱状 / 堆叠柱 / 饼 / 玫瑰 / 雷达 / 仪表盘 / 漏斗 / 水位球 / 散点 / 气泡 / 箱线 / 桑基 / 关系图 / 树图 / 热力 / K 线 / 时序等，均基于 ice-render 图元
内建交互	悬停高亮 + 压暗其它系列、点击下钻、框选缩放、滚轮缩放、拖拽平移、图例联动、跨图联动、键盘导航——命中由引擎承担，0 插件成本
设计语言	直接采用 Bootstrap 5 调色板与令牌（`--bs-border-radius`、`--bs-body-font-family` 等）；数据系列配色与引擎共用一份（`CHART_PALETTE` 直接 import 引擎的 `FAMILY_PALETTE`），换肤只需覆盖 `theme.colorPalette` 或派生 `BOOTSTRAP_TOKENS`
大屏脚手架	`dash-kit` 1~12 列栅格 + 一套空间利用率审计（墨迹横向占宽 / 图形直径占分配直径门禁），避免「右侧浪费太多」
像素契约	`rebuildPixels()` 重算一次点集，`render()` 与 `hitTestIndex()` 消费同一份缓存——「看得见的点」与「点得到的点」不可能漂移
标注图层	`option.annotation`：目标线 / 阈值线、异常点、目标区间。声明式、纯数据可序列化，定位走坐标轴比例尺（随缩放 / 平移 / 联动走），默认不吃命中；越界不画但给结构化诊断
AI Agent DSL	`ice-chart-dsl`：一张表 + `encoding` 直接编译成 `ChartOption`，带结构化诊断（见下节）

0.19.0 → 0.20.0 值得注意的点

option.labels：内置文案可覆盖（i18n 友好）。图表内建 UI 文本（无障碍标题、扇区 / 数值 / 占比、坐标读数、液位等）由一份 ChartLabels 默认表提供，应用层通过 option.labels 整体覆盖即可换语言 / 换措辞，图表包本身不做 i18n 运行时——与引擎「引擎不做 i18n」的契约一致。
类型注册已命名空间化到 ice-chart:*。ICEChart 把内部图元（PlotArea / GridLines / Axis / Legend / Title / Tooltip / Crosshair / Highlight / Brush 等）注册为 ice-chart:PlotArea 这类 canonical typeId，与引擎的 ice-render:*、设计器的 ice-entity-designer:* 互不撞名，序列化 / 反序列化安全。
标注 option.annotation（0.20.0）：目标线 / 阈值线 / 异常点 / 目标区间都是坐标系上的一个图层——{ lines: [{ axis: 'y', value: 150, text: '目标 150' }], points: [...], areas: [...] }。值用数据值（数值轴写数字、类目轴写类目名），所以跟着缩放 / 平移走，不进图例、不占数据下标、不抢命中；越界不画，原因进 chart.annotationDiagnostics()。

快速开始

安装

# 图表库 + 引擎（二者都要装；ice-render 是 peer 依赖，一个页面多张图共用同一引擎实例池）
npm install @damoqiongqiu/ice-chart ice-render

在浏览器里（无构建，UMD 全局 `ICEChart`）

注意引擎要先于图表引入：

<canvas id="chart" width="960" height="420"></canvas>
<script src="./ice-render.umd.js"></script>
<script src="./ice-chart.umd.js"></script>
<script>
  ICEChart.createChart('chart', {
    title: { text: '近 30 天流量' },
    tooltip: { trigger: 'axis' },
    interaction: {
      hover: { enabled: true, dimOthers: true },
      brush: { enabled: true, axes: 'x', mode: 'zoom' },
      zoom: { enabled: true, axes: 'x', wheel: true },
      pan: { enabled: true, axes: 'x' },
      keyboard: true,
    },
    xAxis: { type: 'category' },
    yAxis: { name: '访问量' },
    series: [
      { id: 'pv', type: 'line', name: '访问量', data: [820, 932, 901, 1290] },
      { id: 'uv', type: 'area', name: '独立访客', data: [320, 402, 391, 520] },
    ],
  });
</script>

在打包工程里（ES Module）

import { createChart } from '@damoqiongqiu/ice-chart';

const chart = createChart('canvas-id', {
  title: { text: '近 30 天流量' },
  tooltip: { trigger: 'axis' },
  interaction: { hover: { enabled: true, dimOthers: true } },
  xAxis: { type: 'category' },
  yAxis: { name: '访问量' },
  series: [{ id: 'pv', type: 'line', name: '访问量', data: [820, 932, 901, 1290] }],
});

chart.on('item:click', (params) => {
  console.log(params.seriesName, params.xValue, params.value, params.data);
});

包同时提供 ESM / CJS / UMD 三种产物与完整类型声明（dist/types），Vite / webpack / Rollup 直接 import，Node 侧 require('@damoqiongqiu/ice-chart') 也能拿到 CJS。

AI Agent 接入：JSON-first DSL ⭐

tip

和 ice-render 家族的其它成员一样，ice-chart 也提供一层 JSON-first DSL（ice-chart-dsl）——AI Agent 只需产出「一张表 + 通道绑定（encoding）」，就能编译成 ChartOption，完全不需要手写一长串 series[].data。

最直观的对比：同一份月度销量数据，左边手写 option 要把每一行数据拍进 series[].data，右边 DSL 只声明「x 列绑到「月份」、y 列绑到「销量」、series 列绑到「渠道」」——两者编译出的 ChartOption 逐像素一致（仓库里的 dsl-vs-option.html 带几何自检，任意不一致都会红字报出）。

下面这份「月度销量」就是一份真实可编译、可自检的 DSL 文档（不是截图）：

ice-chart-dsl 文档（AI Agent 可直接产出）
{
  "schemaVersion": 1,
  "kind": "line",
  "title": "月度销量（DSL 编译）",
  "data": [
    ["1月", 120, "线上"], ["1月", 80, "线下"],
    ["2月", 142, "线上"], ["2月", 92, "线下"],
    ["3月", 168, "线上"], ["3月", 78, "线下"],
    ["4月", 154, "线上"], ["4月", 110, "线下"]
  ],
  "encoding": { "x": "月份", "y": "销量", "series": "渠道" },
  "options": {
    "interaction": {
      "hover": { "enabled": true, "dimOthers": true },
      "zoom": { "enabled": true, "axes": "x", "wheel": true },
      "pan": { "enabled": true, "axes": "x" },
      "brush": { "enabled": true, "axes": "x", "mode": "zoom" },
      "keyboard": true
    }
  }
}

DSL 契约（根节点只含这几个字段）：

字段	说明
`schemaVersion`	DSL 版本号（当前 `1`）
`kind`	图表类型：`line` / `bar` / `pie` / `radar` / `scatter` / `sankey` / `graph` / `gauge` / `funnel` 等
`data`	二维数据表（行数组，每行为一条记录）
`encoding`	通道绑定：`x` / `y` / `series` / `color` / `size` 等列名——把「哪列数据」映射到「哪个视觉通道」
`annotation`	标注图层：`{ lines, points, areas }`——目标线 / 阈值线 / 异常点 / 目标区间。值用数据值（数值轴写数字、类目轴写类目名），编译进 `option.annotation`
`options`	透传给 `createChart` 的 `option`：标题、坐标轴、交互、主题等

参考线（目标线 / 阈值线 / 达标区）也是 DSL 的一等字段，agent 不需要伪造系列：

带标注的 DSL 文档
{
  "schemaVersion": 1,
  "kind": "line",
  "title": "月度销量与目标",
  "data": { "columns": ["月份", "销量"], "rows": [["1月", 120], ["2月", 132], ["3月", 101]] },
  "encoding": { "x": "月份", "y": "销量" },
  "annotation": {
    "lines": [{ "axis": "y", "value": 150, "text": "目标 150" }],
    "areas": [{ "axis": "y", "from": 0, "to": 100, "text": "达标区" }]
  }
}

标注的编译期诊断会精确到条目（annotation.lines[0].value）：缺 value 是错误，类目名不在 x 列里（annotation-unknown-category）、数值轴写了非数字（annotation-value-type）是警告。

编译与自检：

import { validateChartDsl, compileChartDsl } from '@damoqiongqiu/ice-chart-dsl';

const diagnostics = validateChartDsl(dsl);     // Agent 产出可即时自检：缺列 / 未知 kind / encoding 错绑
if (diagnostics.length === 0) {
  const option = compileChartDsl(dsl);        // → ChartOption，交给 createChart
  ICEChart.createChart('canvas', option);
}

浏览器：依次加载 ice-render、ice-chart、ice-chart-dsl，全局 ICEChartDSL.validateChartDsl(...) / ICEChartDSL.compileChartDsl(...) 即可。
Node：import { compileChartDsl } from '@damoqiongqiu/ice-chart-dsl'（安装即自动带 @damoqiongqiu/ice-chart）。

info

这套「用户意图 → AI Agent → JSON DSL → 引擎」的接入思路，和 DSL 与 AI Agent 接入里 ice-render 通用 DSL 是同一套哲学——Agent 只产出数据，引擎负责渲染与交互。ER 建模用 ice-entity-designer-dsl，通用图形用 ice-render-dsl，图表用 ice-chart-dsl，三者互不混用。

下面这个例子由打包好的运行时在文档页里直接画出了仓库里的 examples/dsl-vs-option.html：左边手写 option、右边 DSL 编译，两张图逐像素一致（右下角自检面板会实时打印诊断）：

示例画廊（全部可实时把玩，仓库共 29 个）

下面这些不是截图，是文档内实时跑起来的 ice-chart 运行时——覆盖主流图表类型，外加两个「引擎卖点」演示（大数据局部重绘、跨图联动）。拖一拖、框选一下、悬停看十字准星：

ice-chart · 交互式图表库（当前 v0.23.4）

一个完整的实时大屏例子（就是仓库里的 `examples/dashboard-market.html`）

核心能力

快速开始

安装

在浏览器里（无构建，UMD 全局 `ICEChart`）

在打包工程里（ES Module）

AI Agent 接入：JSON-first DSL ⭐

示例画廊（全部可实时把玩，仓库共 29 个）

标注（目标线 / 阈值线 / 达标区）

折线图

堆叠柱状图

饼图 / 玫瑰图

雷达图

漏斗 + 仪表盘

桑基图

K 线（金融）

时序图

大数据（局部重绘）

跨图联动

相关链接

一个完整的实时大屏例子（就是仓库里的 examples/dashboard-market.html）​

核心能力​

快速开始​

安装​

在浏览器里（无构建，UMD 全局 ICEChart）​

在打包工程里（ES Module）​

AI Agent 接入：JSON-first DSL ⭐​

示例画廊（全部可实时把玩，仓库共 29 个）​

标注（目标线 / 阈值线 / 达标区）​

折线图​

堆叠柱状图​

饼图 / 玫瑰图​

雷达图​

漏斗 + 仪表盘​

桑基图​

K 线（金融）​

时序图​

大数据（局部重绘）​

跨图联动​

相关链接​

一个完整的实时大屏例子（就是仓库里的 `examples/dashboard-market.html`）

核心能力

快速开始

安装

在浏览器里（无构建，UMD 全局 `ICEChart`）

在打包工程里（ES Module）

AI Agent 接入：JSON-first DSL ⭐

示例画廊（全部可实时把玩，仓库共 29 个）

标注（目标线 / 阈值线 / 达标区）

折线图

堆叠柱状图

饼图 / 玫瑰图

雷达图

漏斗 + 仪表盘

桑基图

K 线（金融）

时序图

大数据（局部重绘）

跨图联动

相关链接