aerizchart

@aeriz/chartDOCS

用一个选项对象绘制 26 种 Canvas 图表的库。用法只有一种,在 React · Vue · Svelte · jQuery 中名称和选项也完全相同。

v2.1.1 · 单个图表 12–17 KB · 全部 35 KB(gzip)· 零依赖

简介

@aeriz/chart 用一个选项对象绘制 26 种 Canvas 图表。只需传入容器和数据,坐标轴、图例、提示框、动画和主题都由默认值负责。

  • 只有一种做法 数据用 data,修改用 update(),状态用 setState()。26 种图表、5 种环境完全一致。
  • 出错会提示 选项名或数据结构写错时,控制台会给出修改方法,而不是画出一片空白。
  • 按需引入 每种图表是独立模块,打包时只包含用到的图表。零运行时依赖。
  • 随处可用 原生 JS、React、Vue、Svelte 和 jQuery 的名称与用法都相同。
  • 事件好接 点击、悬停、图例、提示框按钮都只是一个函数。详情页、弹窗、下钻几行代码就能完成。事件
  • 快 100 万个点约 50 ms 绘制完成。屏幕外的图表不绘制。

2.1.1 新功能 提示框中的链接和按钮与自定义内容、可接管的图例点击,以及获取指针下的数据项。2.1 的代码可直接运行。

2.1 新功能 参考线与区间、缩放与刷选、联动、百分比堆叠、误差线、多值轴,以及K 线、矩形树图与旭日图、桑基图、关系网络和地图。2.0 的代码可直接运行。

示例

以下示例按真实产品界面制作。它们都在本页实时运行,JS、HTML、CSS 标签页中就是构建该界面的全部代码。每个图表都只是 new SomeChart(element, { data }) 再加几个选项。各类图表的样子见图表类型。

销售仪表盘

@aeriz/chart · JS 38 行

KPI 卡片、组合图、环形图、热力图和漏斗图共 8 个图表。每个图表只需几个选项,月度/季度切换只是一次 update()。

网上商城2026 年 1–12 月
销售额$13.92M▲ 18.4%
订单数312K▲ 11.0%
客单价$44.60▲ 6.7%
转化率3.0%▲ 0.4 pt

销售额与利润率

销售渠道

按星期 · 时段的订单

结账漏斗

业务分析报告 · 复杂图表

@aeriz/chart · JS 97 行

带右轴的四层组合图、堆叠面积图、ARR 桥图、同期群留存、四分位分布、20,000 个点和 8,760 格热力图,共 9 个图表。一个分段按钮就对全部图表调用 update()。

订阅业务报告 2026
加载中…

每周注册数 · 柱 + 面积 + 线 + 点,右轴

注册数(柱)和 8 周均值(面积)使用左轴,转化率(线)使用右侧百分比轴。红点表示明显偏离均值的周。

各渠道获客 · 堆叠面积图

点击图例可去掉某个渠道,其余渠道会重新堆叠。

年度经常性收入(ARR)桥图

从期初 ARR 经过新增、扩展、收缩和流失到期末。

按注册月份的同期群留存

尚未到来的月份保持为空(null)。

各套餐的会话时长

由 8,000 次会话计算出的四分位数和离群值。

竞品对比

六项调查指标,满分 10 分。

20,000 名用户 · 活跃天数与月消费

按套餐着色。悬停可选中单个用户。

各套餐用户数

与散点图使用同一份数据统计。

365 天 × 24 小时流量 · 8,760 格

周末和通勤时段很明显。每个格子都有提示框。

下钻分析 · 一百万个点

@aeriz/chart · JS 43 行

点击左侧的地区柱,onClick 会把其他图表切换到该地区,并重新生成、绘制 1,000,000 条按秒记录的交易。耗时直接显示在顶部。

地区与门店 加载中… 点击左侧的柱,或让图表获得焦点后使用 ↑ ↓ Enter。

各地区销售额

首尔 · 月度销售额(与去年对比)

首尔 · 24 家门店(面积 · 销售额 · 员工)

首尔 · 支付服务器,1,000,000 个按秒采样(11 天 14 小时)

服务器监控

@aeriz/chart · JS 23 行

每 0.1 秒滚动更新的实时折线、3 个仪表盘和各 API 的响应时间。试试点击“模拟故障”。

api-prod · 首尔区域 正常

响应时间(每 0.1 秒)

各 API 的 p95

问卷结果报告

@aeriz/chart · JS 18 行

把同样的图表放在白纸上,它会读取文字颜色和背景,自动变成浅色主题。品牌色只需两行 CSS 变量。

2026 年客户满意度调查 · 1,284 份回答

服务满意度报告

总体满意度为 4.3 分(满分 5 分),比去年提高 0.4 分。各年龄段的得分都有上升,配送提速的影响最大。

各项满意度
按年龄 · 与去年对比
推荐意愿

安装

选择你使用的包管理器。不使用构建工具时,请看 CDN 标签页。

bash
npm install @aeriz/chart

npm 包中只有压缩后的构建产物(dist/)和 TypeScript 类型。

  • import → 按图表拆分的 dist/esm/
  • require → dist/aeriz.min.cjs
  • CDN 脚本 → dist/aeriz.min.js

压缩只缩短局部变量名。选项名、方法、图表名和错误信息都保持原样,可以直接阅读。

提示 在 CDN 地址中写上确切版本号,例如 @2.1.1。地址不会变,因此会被缓存一年。

快速开始

只需要一个有高度的元素和一些数据。没有设置高度时,图表高 320px。

html
<div id="sales" style="height: 260px"></div>
<script type="module">
  import { BarChart } from '@aeriz/chart';

  const chart = new BarChart('#sales', {
    data: { Jan: 64, Feb: 42, Mar: 78, Apr: 55, May: 90, Jun: 71 },
  });

  chart.update({ data: { Jan: 30, Feb: 80 } }); // 以动画过渡到新值
</script>

把鼠标移到柱子上,或聚焦图表后用 ← → 读取数值。

只有一种用法

所有图表都使用相同的四个调用,同一件事没有第二个名字。

目的用法
创建new BarChart(element or selector, options)
修改数据或选项chart.update({ data, … }) — 只传变化的部分,数值会以动画过渡
加载中 · 无数据 · 出错chart.setState('loading' | 'empty' | 'error', text?),用 chart.setState(null) 关闭
立即重绘chart.render() — 重新读取 CSS 变量,即使在屏幕外也立即绘制最终帧
销毁chart.destroy() — 把元素恢复原样

只有 RealtimeChart 额外提供用于推送数据的 push() 和用于清空的 clear()。

数据结构

数据总是放在唯一的 data 选项中,结构取决于图表要画什么。

每项一个值的图表

Bar、HBar、Line、Sparkline、Pie、Polar、Funnel、Treemap、Sunburst 和 Map 接受以下三种写法中的任意一种,含义完全相同。

js
new BarChart(el, { data: [64, 42, 78] });                  // 数字 → 标签为 1, 2, 3
new BarChart(el, { data: { Jan: 64, Feb: 42 } });          // 对象 → 键即标签
new BarChart(el, { data: [{ label: 'Jan', value: 64 }] }); // 行

// 字段名不同的行:指定读取方式
new BarChart(el, { data: rows, label: (r) => r.month, value: (r) => r.sales });

多系列图表

Area、StackedBar、GroupedBar、MultiLine、Radar 和 Composite 在 data 中放入 categories 和 series。每个系列的值个数要与 categories 相同。误差线和区间需在行或系列中加上 low 与 high(误差线)。

js
new GroupedBarChart(el, {
  data: {
    categories: ['Q1', 'Q2', 'Q3'],
    series: [
      { name: '2025', values: [120, 135, 150] },
      { name: '2026', values: [140, 160, 172] },
    ],
  },
});

其他

图表data
Scatter · Bubble[{ x, y, size?, group?, label? }] — Scatter 的 size 是点的半径(px);Bubble 的 size 是以气泡面积表示的值
Heatmap{ x: [...], y: [...], values: [[...], …] } — values[y][x]
Boxplot[{ label, min, q1, median, q3, max, outliers? }]
Waterfall[{ label, value, total? }] — total: true 的柱子从 0 画到该值(小计、最终结果)
Gauge一个数字(data: 72)
Realtime{ series: [{ name }] } — 数值通过 push() 传入
Candlestick[{ label, open, high, low, close }]
Treemap · Sunburst每项一个值;带 children: [...] 的行会嵌套 — 层级数据
Sankey{ links: [{ source, target, value }], nodes?: [{ id, label?, color? }] }
Network{ nodes: [{ id, label?, group?, size? }], links: [{ source, target, value? }] }
Map每项一个值(标签为区域 id),地图通过 geo 选项传入 — 地图

出错时会告诉你

写错选项或数据结构无法识别时,图表不会默默地显示空白。浏览器控制台会说明哪里错了、怎么改,每条消息只提示一次。

text
[aeriz] BarChart: unknown option "dat" — did you mean "data"?
[aeriz] BarChart: "color" is a 1.x option. In 2.0 use colors.
[aeriz] MultiLineChart: data must be { categories: [...], series: [{ name, values: [...] }] } — got an array.
[aeriz] MultiLineChart: series[1] "Sign-ups" has 5 values but there are 6 categories.
[aeriz] LineChart: rows need a "value" field, or pass value: (row) => row.amount.
[aeriz] PieChart: values can't be negative — "Refunds" is -3. It is drawn as 0.
[aeriz] BarChart: "zoom" is not available on this chart — it works on LineChart, MultiLineChart, AreaChart, CompositeChart, CandlestickChart and ScatterChart.
[aeriz] MapChart: 3 rows match no region (e.g. "Korea"). Keys are feature ids, or properties.name when a feature has no id.

调用已删除的方法会抛出异常,并给出替代写法(chart.setData() was removed. Use chart.update({ data }).)。使用 TypeScript 时,编辑器会提前发现同样的错误。

按需引入

每种图表都是独立模块,包中设置了 "sideEffects": false,因此打包工具(Vite、webpack、Rollup、esbuild)会去掉没用到的图表。照常 import 即可,从 React、Vue、Svelte 适配器引入也一样。

js
import { BarChart, PieChart } from '@aeriz/chart'; // 只包含这两个和公共核心

不使用打包工具,或想确保只引入一个图表时,从子路径 import。

js
import { BarChart } from '@aeriz/chart/bar';
import { SparklineChart } from '@aeriz/chart/sparkline';
引入内容大小(min + gzip)
一个无坐标轴的图表(Gauge、Pie、Funnel …)约 12 KB
一个层级、流向或地图图表(Treemap、Sunburst、Sankey、Network、Map)约 12–13 KB
一个有坐标轴的图表(Bar、Line、Composite …)约 14–17 KB
Bar + Line + Pie约 18 KB
全部 26 种约 35 KB(CDN 的 aeriz.min.js 约 38 KB)
缩放 · 联动(首次使用 zoom 或 sync 时单独加载)约 3 KB
提示框链接、按钮和自定义内容(首次使用 tooltip: { … } 时单独加载)约 2.4 KB
React · Vue · Svelte · jQuery 适配器各 0.3–0.7 KB

使用 esbuild 测得。公共核心(Canvas、主题、提示框、图例、输入、错误提示)由所有图表共享,因此多加几个图表增加的体积很小。

子路径:bar hbar line area stacked-bar grouped-bar multi-line scatter bubble pie radar polar gauge heatmap boxplot funnel treemap sparkline realtime waterfall composite candlestick sunburst sankey network map

原生 JS

五种环境使用相同的图表名和选项。不用框架时,直接使用类即可。

js
import { LineChart } from '@aeriz/chart';

const chart = new LineChart('#trend', { data: [3, 7, 4, 9, 6, 12] });
chart.update({ data: [5, 8, 6, 11] });
chart.destroy(); // 元素离开页面时

React

从 @aeriz/chart/react 引入与图表同名的组件,所有选项都是 props。支持 React 16.8 及以上版本。

jsx
import { useRef } from 'react';
import { BarChart } from '@aeriz/chart/react';

export function Sales({ rows }) {
  const chart = useRef(null); // chart.current = 图表实例
  return (
    <BarChart
      data={rows}
      format={{ style: 'currency', currency: 'USD' }}
      onClick={(hit) => console.log(hit.label, hit.value)}
      ref={chart}
      style={{ height: 320 }}
    />
  );
}
  • 变化的 props 会调用 update()。每次渲染都重新创建的内联对象和函数,只要值相同就不会重绘。
  • 数组按引用比较。要修改数据,请传入新数组([...rows, row])。
  • className、style、id、aria-* 和 data-* 会加到外层 <div> 上。在 StrictMode 下也只创建一个图表。

Vue

从 @aeriz/chart/vue 引入与图表同名的组件。选项是 props;onClick、onHover、onLegend、onZoom 对应事件 @click、@hover、@legend、@zoom。支持 Vue 3.2 及以上版本。

vue
<script setup>
import { ref } from 'vue';
import { LineChart } from '@aeriz/chart/vue';

const rows = ref([3, 7, 4, 9]);
const add = () => (rows.value = [...rows.value, Math.random() * 10]);
const trend = ref(null); // trend.value.chart = 图表实例
</script>

<template>
  <LineChart :data="rows" curve="linear" @click="(hit) => console.log(hit)" ref="trend" style="height: 300px" />
</template>

数据传给图表前会去掉 Vue 的响应式代理,因此大数据量也能保持速度。请用新值替换数据;就地修改(rows.value.push())不会被检测到。

Svelte

@aeriz/chart/svelte 为每种图表提供一个 action(barChart、lineChart、multiLineChart …),参数就是选项。无需配置编译器,Svelte 3、4、5 用法相同。

html
<script>
  import { barChart, chartOf } from '@aeriz/chart/svelte';

  let rows = $state([{ label: 'A', value: 5 }, { label: 'B', value: 9 }]);
</script>

<div use:barChart={{ data: rows, onClick: (hit) => console.log(hit) }} style="height: 300px"></div>

需要图表实例时,使用 chartOf(element)。

jQuery

用 install($, { … }) 注册要用的图表,再按子路径名('bar'、'pie' …)创建。如果先加载了 jQuery,CDN 脚本(aeriz.min.js)会自动注册全部 26 种。

js
import $ from 'jquery';
import { PieChart } from '@aeriz/chart/pie';
import { install } from '@aeriz/chart/jquery';

install($, { PieChart });
$('#share').aerizChart('pie', { data: { Chrome: 64, Safari: 19 }, innerRadius: 0.6 });
js
$('#share').aerizChart('update', { data: { Chrome: 70, Safari: 20 } }); // setState · render · destroy 用法相同
$('#share').aerizChart('instance');                                       // 图表实例

以下图表都在实时运行。点击图例可以隐藏或显示对应系列。

MultiLineChart
StackedBarChart
PieChart · innerRadius
CompositeChart · 右轴
RadarChart
HeatmapChart
TreemapChart · children
WaterfallChart
GaugeChart
CandlestickChart
SunburstChart
SankeyChart
类子路径data说明
BarChartbar每项一个值负值向下,dataLabels
HBarCharthbar每项一个值横向,标签栏宽度随标签自适应
LineChartline每项一个值curve、时间轴、对数轴、百万级数据点、缩放、区间
AreaChartareacategories · seriesstacked('percent')、缩放
StackedBarChartstacked-barcategories · series负值向下堆叠,stacked: 'percent'
GroupedBarChartgrouped-barcategories · series系列并排,误差线
MultiLineChartmulti-linecategories · series跟随指针的共享提示框,缩放,区间
ScatterChartscatter[{ x, y }]按颜色和大小批量绘制,缩放
BubbleChartbubble[{ x, y, size }]size 表示面积
PieChartpie每项一个值用 innerRadius 做成环形图,可从图例切换扇区
RadarChartradarcategories · series每个点都有提示框
PolarChartpolar每项一个值面积与数值成正比(按半径用 scale: 'linear')
GaugeChartgauge一个数字update({ data }) 从当前显示的值开始变化
HeatmapChartheatmap{ x, y, values }colors: { low, high }
BoxplotChartboxplot[{ min, q1, median, q3, max }]离群点
FunnelChartfunnel每项一个值相对第一阶段的转化率
TreemapCharttreemap每项一个值(+ children)近似正方形布局,分组带标题
SparklineChartsparkline每项一个值无坐标轴的迷你趋势线
RealtimeChartrealtime{ series } + push()在固定窗口内滚动
WaterfallChartwaterfall[{ label, value, total? }]累计值
CompositeChartcompositecategories · series(type)混合柱、线、面积、点;多个数值轴、堆叠柱、缩放
CandlestickChartcandlestick[{ label, open, high, low, close }]贴合价格的坐标轴、缩放、数万根 K 线
SunburstChartsunburst每项一个值(+ children)每层一个环,中心显示占比
SankeyChartsankey{ links, nodes? }粗细与数值成比例的流向带
NetworkChartnetwork{ nodes, links }力导向布局,高亮相邻节点
MapChartmap每项一个值 + geo为 GeoJSON 区域着色,scale: 'log'

K 线图

绘制每个周期的开盘价、最高价、最低价和收盘价。实体从开盘价画到收盘价(上涨用 colors.up,下跌用 colors.down),影线从最低价画到最高价。数值轴不从 0 开始,而是贴合当前可见的价格。

js
new CandlestickChart('#stock', {
  data: candles,                   // [{ label, open, high, low, close }]
  zoom: true,
  range: ['7/29', '10/22'],        // 初始显示最近三个月
  annotations: [{ y: 80, label: 'Target $80' }],
  // 在红涨绿跌的市场使用 colors: { up: '#ef4444', down: '#3b82f6' }
});

拖动即可放大;按住 Shift 拖动或横向滚动可平移。双击显示全部。

K 线宽度小于 3px 时只绘制影线,指针按像素列查找最近的 K 线,所以数万根也很流畅。x 轴可以用标签('8/3'),也可以用 xScale: 'time' 加毫秒时间戳。开盘价或收盘价超出最低价到最高价的范围时,控制台会给出提示。

层级 — 矩形树图 · 旭日图

TreemapChart 和 SunburstChart 接收相同的数据。带 children 的行会成为分组,分组的值是其子项之和。层级深度不限。

js
const budget = [
  { label: 'Engineering', children: [{ label: 'Backend', value: 42 }, { label: 'Apps', value: 30 }, { label: 'Data', value: 18 }] },
  { label: 'Marketing', children: [{ label: 'Ads', value: 25 }, { label: 'Events', value: 9 }, { label: 'Content', value: 7 }] },
  { label: 'Operations', children: [{ label: 'Support', value: 14 }, { label: 'Office', value: 8 }] },
  { label: 'Other', value: 6 },
];
new TreemapChart('#budget-tree', { data: budget, onClick: (hit) => console.log(hit.path) }); // ['Engineering', 'Backend']
new SunburstChart('#budget-sun', { data: budget });
TreemapChart · children
SunburstChart
  • 矩形树图为每个分组加上显示名称和合计的标题,并在其中排列子项。没有子项的扁平数据({ JS: 42, TS: 30 })与 2.0 的绘制结果完全相同。
  • 旭日图把第一层放在最内环,子项位于父项的角度范围内。悬停某一扇区时只有该分支保持高亮,中心显示它占整体的比例。
  • 提示框显示从顶层开始的路径(Engineering › Backend: $42M),onClick 也会以 hit.path 收到同样的路径。

流向 — 桑基图

用粗细与数值成比例的带子绘制各阶段之间的流向。节点由连线生成,按从起点出发的最长路径排到右侧相应的列。没有流出的节点排在最后一列。

js
new SankeyChart('#journey', {
  data: {
    links: [
      { source: 'Search', target: 'Product page', value: 520 },
      { source: 'Ads', target: 'Product page', value: 300 },
      { source: 'Product page', target: 'Cart', value: 410 },
      { source: 'Cart', target: 'Purchase', value: 330 },
      // …
    ],
    nodes: [{ id: 'Purchase', color: '#10b981' }], // 仅在需要修改标签或颜色时
  },
});

回到上游的连线(形成环)无法在桑基图中绘制,因此会被忽略,控制台会指出是哪条连线。悬停带子或节点会高亮其流向,onClick 的 hit.row 是对应的连线行(节点则是节点行)。

关系 — 网络图

用力导向布局放置节点和连线:连线把两端拉近,节点之间互相排斥,大约在第一秒内稳定下来。使用 animate: false 或 render() 会直接绘制稳定后的布局。

js
new NetworkChart('#services', {
  data: {
    nodes: [{ id: 'web', group: 0 }, { id: 'gateway', group: 1, size: 120 }, …], // group:颜色,size:面积
    links: [{ source: 'web', target: 'gateway', value: 80 }, …],               // value:粗细
  },
  radius: [4, 14], // 最小和最大 size 对应的半径(px)
});

悬停某个节点时,除相邻节点外的其他内容会变淡。

节点不超过 40 个时显示全部标签;更多时只显示悬停节点周围的标签。通过 update() 传入新数据时,保留下来的节点位置不变,只有新节点会寻找位置。指向不存在节点的连线会在控制台提示。

地图

按数值为区域着色。包内不含地图数据,请把 GeoJSON 传给 geo。区域按 feature 的 id 匹配,没有 id 时按 properties.name 匹配。

js
const geo = await fetch('/data/world-110m.json').then((r) => r.json());

new MapChart('#world', {
  geo,                                          // FeatureCollection(Polygon · MultiPolygon,经度/纬度)
  data: { KOR: 31846, JPN: 40247, USA: 65298 }, // 区域 id → 数值(也可用行 [{ label, value }])
  scale: 'log',                                 // 数值集中在一端时(人口、GDP 等)
  format: { style: 'currency', currency: 'USD', notation: 'compact' },
});

各国人均 GDP(2019 年,Natural Earth)。提示框中的国名取自 properties.name。

  • 投影方式有 projection: 'mercator'(默认)和 'equirectangular'。地图在每种尺寸下只投影一次,指针命中按真实形状判断,包括孔洞和岛屿。
  • 颜色用 colors: { low, high } 指定,没有数值的区域显示为浅灰色。地图下方有颜色图例(legend: false 可隐藏)。
  • 有行匹配不到任何区域时,控制台会给出数量和示例(检查是否把 "KOR" 写成了 "Korea")。labelFormat: (id) => name 可以修改提示框中的区域名。
  • 本页的世界地图是 world-110m.json(gzip 后 41 KB):将 Natural Earth 1:110m(公有领域)取整到 0.1°。id 为 ISO 3166-1 alpha-3 代码,properties 包含英文名(name)、韩文名(ko)和人均 GDP(gdp)。不含南极洲。

实时数据

向 RealtimeChart push() 的值会出现在右端,超出 window 的值从左端移出。

js
const rt = new RealtimeChart('#cpu', { data: { series: [{ name: 'CPU' }, { name: 'Memory' }] }, window: 120, max: 100 });
setInterval(() => rt.push([cpu(), memory()]), 100);

大数据量

当 LineChart 的点数远多于像素时,每个像素列只保留最小值和最大值。形状不变,提示框显示原始数据点。结果会一直复用到数据变化为止,所以移动鼠标不会重新计算。

点击按钮生成数据并测量绘制时间。

参考线 · 目标线 · 区间

带数值轴的图表会根据 annotations 绘制线和区间带。单个值是虚线,[from, to] 是区间带。y 位于数值轴,x 位于 x 轴(标签、时间或数值)。

js
new LineChart('#latency', {
  data: latency, // 每小时的响应时间
  annotations: [
    { y: 300, label: 'SLO 300 ms', color: '#ef4444' }, // 目标线
    { y: [80, 160], label: 'Normal range' },          // 区间带
    { x: '14:00', label: 'Deploy' },                  // 垂直参考线
  ],
});
  • 支持 Bar、HBar、Line、Area、StackedBar、GroupedBar、MultiLine、Scatter、Bubble、Boxplot、Waterfall、Composite、Candlestick 和 Realtime(仅 y)。其他图表会在控制台提示。
  • 数值轴上的线和区间带始终可见,必要时会扩展坐标轴。label 在水平线右端上方(线在顶部时放在下方),在垂直线顶端;color 用于线、区间带和文字(默认为浅色文字)。
  • HBarChart 的数值轴是水平的,所以 x 是数值,y 是项目标签。CompositeChart 用 axis 选择线所在的数值轴(更多数值轴)。
  • update({ annotations }) 只重绘这些线,不带动画。

缩放 · 平移 · 刷选

设置 zoom: true 后可以缩放和平移 x 轴。支持 LineChart、MultiLineChart、AreaChart、CompositeChart、CandlestickChart 和 ScatterChart。放大时数值轴贴合可见数据(含柱或面积的轴从 0 开始)。

js
const chart = new LineChart('#visits', {
  data: visits,                           // [{ label: 时间(ms), value }]
  xScale: 'time',
  zoom: true,
  range: [from, to],                      // 初始范围(省略时显示全部)
  onZoom: (range) => console.log(range), // 用户每次修改时为 [from, to] 或 null
});

chart.update({ range: null }); // 通过代码显示全部

在图表上拖动试试。

鼠标 · 触控板触屏键盘(图表获得焦点时)
放大拖动选择范围 · Ctrl/⌘ + 滚轮 · 双指捏合双指张开+
缩小Ctrl/⌘ + 滚轮 · 双指捏合双指捏合-
平移Shift + 拖动 · 横向滚动放大后单指拖动Shift + ← →
重置双击 · 右上角按钮右上角按钮0

普通的滚轮滚动页面,在未放大的图表上单指拖动会显示提示框,所以不会妨碍页面滚动。range 使用 x 轴单位:标签轴为 ['Mar', 'May'],时间轴为毫秒,数值轴(Scatter)为数字。没有 zoom 时,range 只是显示该范围。

默认保持轻量 拖动、捏合和同步的代码(约 3 KB)单独加载,只在首次创建带 zoom 或 sync 的图表时载入。不缩放的图表永远不会加载它。

刷选

设置 zoom: 'brush' 的图表始终显示全部,在它上面拖出的范围会由同一 sync 组中的图表放大显示。拖动选区边缘可调整大小,拖动内部可移动选区。

js
new LineChart('#detail', { data, xScale: 'time', sync: 'traffic' });
new LineChart('#overview', { data, xScale: 'time', sync: 'traffic', zoom: 'brush', range: [from, to] });

图表联动

sync 名称相同的图表共享十字准线和缩放范围。它们按相同的 x 值(标签、时间或数值)对齐,所以图表类型和数据长度可以不同。

js
new MultiLineChart('#requests', { data: requests, sync: 'ops', zoom: true });
new AreaChart('#errors', { data: errors, sync: 'ops', zoom: true, stacked: true });
new CompositeChart('#cost', { data: cost, sync: 'ops', zoom: true });

悬停其中一个图表或拖动放大,另外两个会跟着变化。

  • 只有指针下方的图表显示提示框。其他图表在同一位置显示十字准线(MultiLine · Composite),或显示虚线并高亮最近的项目(其余图表)。
  • 后加入分组的图表从分组当前范围开始;带着自己的 range 加入时,会把它交给分组。update({ sync: null }) 退出分组。
  • onZoom 只在用户操作的图表上触发,所以每个分组处理一次即可。

堆叠 · 百分比堆叠

stacked: 'percent' 把每个项目的合计按 100% 换算后堆叠占比。数值轴为 0–100%,提示框在原始值旁显示占比。

js
new StackedBarChart(el, { data, stacked: 'percent' }); // 默认 true(按原值)
new AreaChart(el, { data, stacked: 'percent' });       // true · false · 'percent'
new CompositeChart(el, { data, stacked: true });       // 同一坐标轴上的柱(也支持 'percent')
StackedBarChart · stacked: 'percent'
AreaChart · stacked: 'percent'

百分比堆叠表示正值的占比,所以负值按 0 处理,控制台会给出提示。StackedBarChart 总是堆叠,因此其 stacked 只接受 true(默认)和 'percent'。

误差线 · 置信区间

在行中加上 low 和 high,柱会带误差线,线会带区间带。系列数据接收与数值一一对应的 low、high 数组。数值轴会扩展到能显示整个区间,提示框显示为 value (low – high)。

js
new BarChart(el, { data: [{ label: 'A', value: 0.031, low: 0.027, high: 0.035 }, …] });
new LineChart(el, { data: forecast }); // [{ label, value, low, high }] → 线 + 区间带

new GroupedBarChart(el, {
  data: { categories, series: [{ name: '2026', values, low: [...], high: [...] }] },
});
BarChart · 误差线
LineChart · 预测区间

BarChart 和 LineChart 在行上接收,GroupedBarChart、MultiLineChart 和 CompositeChart 在系列上接收(Composite 在柱和点上画误差线,在线和面积上画区间带)。其他图表会在控制台说明已忽略它们。

更多数值轴 · 堆叠组合

给 CompositeChart 的系列指定 axis 名称,每个名称都有自己的数值轴。'left'(默认)在左侧,其他名称按出现顺序排在右侧,同名系列共用一个轴。stacked 会堆叠同一轴上的柱。

js
new CompositeChart('#business', {
  stacked: true,
  data: {
    categories: ['Jan', 'Feb', 'Mar', …],
    series: [
      { type: 'bar', name: 'Online', values: online },  // 左侧轴
      { type: 'bar', name: 'Store', values: store },    // 同一轴,所以堆叠在上方
      { type: 'line', name: 'Margin', values: margin, axis: 'margin', format: { style: 'percent' } },
      { type: 'line', name: 'Visitors', values: visitors, axis: 'visitors' },
    ],
  },
});
  • 有多个轴时,只包含一个系列的轴会用该系列的颜色显示刻度标签,便于分辨它属于哪条线。
  • 轴上的数字使用其系列的 format。min 和 max 作用于左侧轴,其他轴贴合各自的数据。
  • 2.0 的 axis: 'right' 照常可用,'right' 只是一个普通名称。

事件一览

图表的所有事件都是作为选项传入的函数。没有事件名字符串,也没有 addEventListener,26 种图表的名称和参数完全一致。随时可以用 update({ onClick }) 替换函数,不会重播动画。

选项触发时机用途
onClick(hit, chart)点击某个项目,或在获得焦点的图表上按 Enter打开详情页、弹窗,下钻
onHover(hit, chart)指针下的项目变化时;离开时 hit 为 null侧边面板、高亮表格中的同一行
onLegend(index, visible, chart, event)点击图例项、在切换之前调用 event.preventDefault(),改为执行其他操作
onZoom(range, chart)用户修改范围时把范围保存到 URL、对齐其他视图 — 缩放
tooltip.actions(hit, chart)生成提示框时(每个项目一次)提示框下方的链接和按钮
tooltip.render(hit, chart)生成提示框时(每个项目一次)自定义提示框内容

hit 在各处的结构都相同:index(在数据中的位置)、label、value、series(系列序号)、row(你传入的项目本身),层级图还有 path(从顶层开始的名称)。你在行上保存的其他值(例如 id)都在 hit.row 中。各框架中的名称都一样。

js
new BarChart(el, { data: rows, onClick: open, onHover: show, tooltip: { actions } });

在 React 中,即使每次渲染都传入新的函数或 tooltip 对象,图表也不会重绘。

提示框中的链接和按钮

tooltip.actions 返回的列表显示在提示框下方。带 href 的是链接,只有 onClick 的是按钮。点击时先执行 onClick(hit, chart, event),然后提示框关闭。可以在这个函数里打开弹窗、侧边面板或其他页面。

js
new HeatmapChart('#orders', {
  data: { x: hours, y: days, values },             // 按星期 × 小时统计的订单
  tooltip: {
    actions: (hit) => [
      { label: '订单列表', href: `/orders?day=${hit.row.y}&hour=${hit.row.x}` },
      { label: '8 周趋势', onClick: (hit) => openTrend(hit) }, // 模态框、面板……都可以
    ],
  },
});

先指向一个单元格,再把鼠标移到提示框里的按钮上。途中经过其他单元格时提示框不会移动。

  • 使用路由的应用 保留 href(用于在新标签页打开和复制地址),在 onClick 中先调用 event.preventDefault(),再调用 router.push(href)。
  • 新标签页 target: '_blank',会自动加上 rel="noopener"。
  • 拦截的地址 javascript: 地址会被拦截,控制台会提示改用 onClick。

等待鼠标的提示框

带链接或按钮的提示框会等待鼠标移过来。无需任何设置,没有链接或按钮的提示框仍像以前一样立即跟随鼠标。

  • 移动途中 — 鼠标移向提示框时,经过的项目会被跳过。途中停留 0.3 秒,则切换为鼠标下方的项目。
  • 离开 — 离开图表或提示框 0.3 秒后才关闭,短暂移出没有关系。
  • 键盘 — 用 ← → 选择项目会打开提示框,Tab 进入其中的链接和按钮。Esc 关闭提示框并回到图表。
  • 触屏 — 轻触打开提示框,其中的按钮可以立即点按。点按其他位置即关闭。
  • 屏幕阅读器 — 带链接或按钮的提示框会成为可朗读、可操作的区域;没有的则像以前一样由图表朗读。

自定义提示框内容

tooltip.render(hit, chart) 的返回值就是提示框的内容。每个项目只调用一次,鼠标停在同一项目上时不会再次调用。同时指定 actions 时,链接和按钮会排在你的内容下方。

返回值提示框
字符串或数字该文本(不会被解析为 HTML)
DOM 节点原样显示该节点。内含链接或按钮时,会成为等待鼠标的提示框
null该项目不显示提示框
undefined默认提示框
js
const card = document.querySelector('#store-card');       // 一个 <template>

new BarChart('#stores', {
  data: stores,                                            // [{ label, value, target, manager }]
  tooltip: {
    render: (hit) => {
      const el = card.content.firstElementChild.cloneNode(true);
      el.querySelector('.name').textContent = hit.label;    // 数据通过 textContent 写入
      el.querySelector('.meter i').style.width = `${(hit.value / hit.row.target) * 100}%`;
      return el;
    },
    actions: (hit) => [{ label: '门店页面', href: `/stores/${hit.row.id}` }],
  },
});

指向柱子即可看到门店卡片。

  • 字符串 始终按纯文本显示,数据中混有标签也是安全的。
  • HTML 请返回 DOM 节点。复制一个 <template>,再用 textContent 填入数据,最为方便。返回 HTML 字符串时会按纯文本显示,控制台会提示改为返回节点。
  • 颜色 背景色和文字颜色跟随主题(--aeriz-tooltip-bg · --aeriz-tooltip-fg)。

点击下钻

在 onClick 中调用 update({ data }) 就实现了下钻。新数据以动画方式进入,键盘上按 Enter 效果相同。

js
const chart = new BarChart('#sales', {
  data: regions,                         // [{ label: 'West', value: 412, children: [...] }, ...]
  onClick: (hit) => {
    if (hit.row.children) chart.update({ data: hit.row.children });
  },
});

点击柱子可依次进入地区 → 城市 → 门店;点击上方路径可返回。

图例事件

点击图例时,会在状态改变之前调用 onLegend(index, visible, chart, event)。

  • visible — 按默认行为该项将要变成的状态。最后一个可见项不能隐藏,因此为 true。
  • event.preventDefault() — 阻止默认的显示/隐藏切换。
  • event.target — 被点击的图例按钮。

哪些项被隐藏由 hidden 选项(要隐藏的图例项位置)决定。可以一开始就设置,也可以用 update({ hidden }) 修改;点击图例也会更新 chart.options.hidden,保存下来,下次就能以相同状态打开图表。

js
new MultiLineChart('#traffic', {
  data: { categories, series },
  hidden: [3],                                    // 初始隐藏第四个系列
  onLegend: (i, visible, chart, event) => {
    event.preventDefault();                       // 代替隐藏/显示:只显示这一项,再点一次显示全部
    const others = series.map((_, j) => j).filter((j) => j !== i);
    const alone = String(chart.options.hidden) === String(others);
    chart.update({ hidden: alone ? [] : others });
  },
});

要在图例项处打开菜单,可以使用 event.target 的位置。下面的演示中,点击图例会打开菜单,由菜单修改 hidden。菜单使用浏览器的 popover,点击外部或按 Esc 即可关闭。

js
onLegend: (i, visible, chart, event) => {
  event.preventDefault();
  const r = event.target.getBoundingClientRect();  // 图例按钮
  menu.style.left = `${r.left}px`;
  menu.style.top = `${r.bottom + 4}px`;
  menu.showPopover();                             // <div popover> … </div>
},

点击图例会打开菜单,而不是隐藏/显示。使用键盘时,按 Tab 移到图例再按 Enter。

自定义图例

用 legend: false 关闭内置图例,自己做想要的图例并连接到 update({ hidden }):带数值和占比的列表、复选框、表格行都可以。再加上 onHover,指针下的项目也能在你的图例中高亮。

js
const chart = new PieChart('#share', {
  data: browsers, colors, innerRadius: 0.6, legend: false,
  onHover: (hit) => highlight(hit?.index),        // 指针离开时 hit 为 null
});

list.onclick = (e) => {
  const i = +e.target.closest('button').dataset.i;
  const hidden = chart.options.hidden ?? [];
  chart.update({ hidden: hidden.includes(i) ? hidden.filter((j) => j !== i) : [...hidden, i] });
};

    点击右侧列表可隐藏或显示。指向某个扇区,对应的行会高亮。

    跟随指针所在的项目

    指针下的项目每变化一次,onHover(hit, chart) 就调用一次;指针离开图表时以 null 调用。鼠标、触屏和键盘(← →)的行为一致。可以用它在侧边面板而不是提示框中显示详情、高亮表格中的同一行,或对齐其他视图。

    js
    new CompositeChart('#revenue', {
      data: { categories: months, series: [thisYear, lastYear] },
      tooltip: false,                                 // 用侧边面板代替提示框
      onHover: (hit) => (hit ? showMonth(hit.index) : showYear()),
    });

    在图表上移动鼠标。离开后面板会回到全年合计。

    • 十字准线类图表(MultiLine、Composite、Realtime)指向 x 轴上的一个位置,所以 hit 只有 index 和 label。请用 index 从你的数据中读取数值。
    • 在通过 sync 联动的图表中,只有用户指向的图表会调用 onHover,跟随的十字准线不会调用。

    主题

    无需任何设置,图表会读取元素的文字颜色、字体和背景,并据此生成网格和坐标轴的颜色。因此图表能直接适配浅色和深色页面,系统切换深色模式时也会重新读取主题。只需用 CSS 变量覆盖你想改的部分。

    css
    .dashboard {
      --aeriz-color-1: #64c8ff;   /* 调色板:--aeriz-color-1 … 12 */
      --aeriz-color-2: #10b981;
      --aeriz-text: #e7eef5;       /* 默认:元素的 color */
      --aeriz-grid: rgba(100, 200, 255, 0.08);
      --aeriz-font: 'Inter', sans-serif; /* 默认:元素的 font-family */
      --aeriz-font-size: 12px;
      --aeriz-line-width: 2;
      --aeriz-bar-radius: 4;
      --aeriz-tooltip-bg: rgba(0, 0, 0, 0.9);
    }

    如果用脚本修改了变量,请调用 chart.render()。只给一个图表换色时使用 colors: ['#f00', '#0f0'] 选项;只给一根柱子上色时,在该行上设置 color。

    变量默认值
    --aeriz-text元素的文字颜色
    --aeriz-muted · --aeriz-grid · --aeriz-axis文字颜色的 62% · 9% · 30%
    --aeriz-bg最近的不透明背景
    --aeriz-font · --aeriz-font-size元素的字体 · 11
    --aeriz-accent#64c8ff(加载动画)
    --aeriz-line-width · --aeriz-point-radius · --aeriz-bar-radius2 · 3 · 3
    --aeriz-tooltip-bg · --aeriz-tooltip-fg深色背景 · 白色文字
    --aeriz-surfacetransparent(画布背景)
    --aeriz-color-1 … 12PALETTE 的 8 种颜色

    数字与标签格式

    format 格式化数值(提示框和数值轴),labelFormat 格式化标签(x 轴标签和提示框标题)。没有按坐标轴区分的格式选项。

    js
    { format: { style: 'currency', currency: 'USD' } }      // $1,234.00
    { format: { style: 'percent' } }                         // 0.25 → 25%
    { format: (v) => v.toFixed(1) + '°C' }                   // 函数
    { labelFormat: (t) => new Date(t).getHours() + 'h' }     // 时间轴标签
    • 默认 提示框使用千位分隔符,坐标轴从 10,000 起使用缩写。
    • 语言 数字格式跟随用户浏览器的语言(中文 1.2万,英文 12K)。要固定语言,请传入函数:format: (v) => v.toLocaleString('zh-CN')
    • CompositeChart 每个系列都可以设置 format,该系列所在的轴也使用相同格式。

    图例 · 提示框 · 键盘

    • 图例 — 有多个系列的图表(以及饼图)会自动添加。点击某项会隐藏或显示该系列并重新调整坐标轴。最后一个可见项无法隐藏。用 legend: false 隐藏图例,hidden: [1] 让该项一开始就处于隐藏状态。想在点击时做别的事,请看图例事件。
    • 提示框 — 支持鼠标、触屏和触控笔。轻触后提示框保持打开,直到点按其他位置。提示框不会超出图表范围。用 tooltip: false 关闭;自定义内容以及链接和按钮,请看自定义提示框内容和提示框中的链接和按钮。
    • 键盘 — 让图表获得焦点后,用 ← → ↑ ↓ 移动,Home · End 跳到两端,Enter 触发 onClick,Esc 关闭。Tab 进入提示框中的链接和按钮。读取的数值会播报给屏幕阅读器。
    • 点击 — onClick(hit, chart) 只在点击项目时调用。hit 包含 index、label、value、series(系列序号)和 row(你传入的项目本身),层级图还有 path(从顶层开始的名称)。结束缩放或刷选拖动的那次点击不算作项目点击。
    js
    new BarChart(el, {
      data: rows,
      title: '月度销售额',                 // 屏幕阅读器朗读的名称
      onClick: (hit) => openDetail(hit.row),
    });

    状态 · 动画

    js
    chart.setState('loading', '加载中…');
    chart.setState('error', '网络错误');
    chart.setState('empty');   // emptyText(默认 'No data')
    chart.setState(null);      // 关闭

    数据为空时会自动显示 emptyText,数据到达后自动消失。动画在图表滚动进入视口时开始,可用 animate: false 关闭;对开启了“减弱动态效果”的用户始终关闭。

    通用选项

    所有选项都有默认值,只传你需要的即可。特定图表类型的选项见各图表选项。

    选项类型默认值说明
    data取决于图表—见数据格式
    titlestring图表类型名屏幕阅读器朗读的名称;Gauge 会显示在数值下方
    colorsstring[]CSS 变量或 PALETTE该图表的颜色(Heatmap 和 Waterfall 为对象)
    formatIntl options | (v) => string浏览器语言提示框和数值轴的数字格式
    labelFormat(label) => string—x 轴标签和提示框标题(带坐标轴的图表)
    min · maxnumber根据数据数值轴范围(带坐标轴的图表、Gauge、Realtime)
    legendboolean多个系列时显示false 隐藏
    hiddennumber[][]要隐藏的图例项位置;点击图例会更新它(带图例的图表)— 图例事件
    tooltipboolean | { render?, actions? }truefalse 关闭。render:内容,actions:链接和按钮 — 自定义内容 · 链接和按钮
    animatebooleantrue首次绘制和变化时播放动画
    emptyTextstring'No data'无数据时显示的文字
    onClick(hit, chart) => void—点击了项目或按下 Enter
    onHover(hit | null, chart) => void—指针下的项目变化;离开时为 null — 侧边面板
    onLegend(index, visible, chart, event) => void—点击了图例项(切换之前);event.preventDefault() 保持原样
    annotations{ x | y, label?, color?, axis? }[]—参考线、目标线和区间带(带数值轴的图表)— 参考线
    zoomboolean | 'brush'false缩放和平移,或刷选(Line、MultiLine、Area、Composite、Candlestick、Scatter)— 缩放
    range[from, to] | null全部要显示的 x 范围(上述图表,无论是否开启 zoom)
    onZoom(range, chart) => void—用户修改了范围
    syncstring—与同名图表共享十字准线和范围 — 联动

    方法

    方法返回值说明
    update(options)this合并选项(包括数据)并以动画重绘
    setState(state, text?)this显示 'loading' · 'empty' · 'error';null 关闭
    render()this重新读取 CSS 变量并立即绘制最终帧(屏幕外、打印、导出)
    destroy()—移除监听器和观察器,并还原元素
    push(v | v[]) · clear()this仅 RealtimeChart:添加一个样本(多个系列时为数组)· 全部清除

    此外,包只导出 Chart(继承它来编写自己的图表)和默认颜色 PALETTE,没有其他导出。

    各图表选项

    图表选项
    每项一个值的图表label、value:读取行的函数 ((row) => row.sales)
    BardataLabels: true 或 (value, row, index) => string。行的 low · high 绘制误差线
    Linecurve: 'smooth' · 'linear' · 'step', xScale: 'category' · 'time', yScale: 'linear' · 'log', fill、points。行的 low · high 绘制区间带
    MultiLinecurve, xScale
    Areastacked: true · false · 'percent'
    StackedBarstacked: true(默认) · 'percent'
    Bubbleradius: [min, max] px(默认 [4, 32])
    PieinnerRadius:占半径的比例 0–0.9(0.6 = 环形图),center:中心文字或 false
    Polarscale: 'sqrt' · 'linear'
    Radarmax(最外环的值)
    Gaugemin (0), max (100), unit
    Heatmapcolors: { low, high }
    Waterfallcolors: { up, down, total }
    Funnel · Treemap · SunburstlabelColor(#fff)。Sunburst:center(中心文字)或 false
    Sparklinefill, lastDot, min, max
    Realtimewindow (200), min, max
    Composite每个系列的 type: 'bar' · 'line' · 'area' · 'scatter', axis:数值轴名称(默认 'left'),format,low · high;图表上有 xScale、 stacked: true · 'percent'
    CandlestickxScale, colors: { up, down } (#10b981 · #ef4444)
    Networkradius: [min, max] px(默认 [4, 16])
    Mapgeo: GeoJSON, projection: 'mercator' · 'equirectangular', scale: 'linear' · 'log', colors: { low, high }, labelFormat:区域名

    包内附带 TypeScript 类型,编辑器会在你输入时提示每种图表的选项和数据格式。

    从 1.x 升级到 2.0

    2.0 中每件事只保留一种做法。使用 1.x 的名称时,控制台会告诉你新名称,打开页面按警告修改即可。如果要继续使用 1.x,请安装 npm install @aeriz/chart@1。

    js
    // 1.x
    new MultiLineChart(el, { categories, series, interpolation: 'linear', yTickFormat: (v) => v + '%' });
    chart.setData(rows);
    chart.setLoading('…');
    gauge.setValue(80);
    
    // 2.0
    new MultiLineChart(el, { data: { categories, series }, curve: 'linear', format: (v) => v + '%' });
    chart.update({ data: rows });
    chart.setState('loading', '…');
    gauge.update({ data: 80 });
    1.x2.0
    setData(d)update({ data: d })
    setLoading · setEmpty · setError · clearStatesetState('loading' | 'empty' | 'error' | null, text?)
    invalidate()render()
    Gauge setValue(v) · value · labelupdate({ data: v }) · data · title
    categories · series · layers · axes (options)data: { categories, series }
    Heatmap xLabels · yLabels · data: [{ x, y, value }]data: { x, y, values: [[…]] }
    Realtime series · windowSize · yMin · yMax · waitingTextdata: { series } · window · min · max · emptyText
    ariaLabeltitle
    palette · colorcolors
    colorLow/High · colorUp/Down/Totalcolors: { low, high } · colors: { up, down, total }
    yTickFormat · xTickFormatformat · labelFormat
    yLeftTickFormat · yRightTickFormat每个系列上的 format
    interpolation ('step-after' …)curve: 'smooth' · 'linear' · 'step'
    yMin · yMaxmin · max (所有带坐标轴的图表)
    minRadius · maxRadiusradius: [min, max]
    centerLabel: false · totalLabelcenter: false · center: 'text'
    Pie innerRadius: 80 (px) · 'auto'innerRadius: 0.6 (仅比例)
    Waterfall isTotaltotal
    Scatter r · Bubble zsize
    Composite 的点 values: [{ x, y }]values: [value | null],与其他系列一致
    [['Jan', 64], …] 形式的数组对{ Jan: 64 } 或 [{ label, value }]
    SparklineSparklineChart
    onClick(hit, point, chart) (也会以 null 调用)onClick(hit, chart)(仅在项目上); hit.data → hit.row
    React · Vue <AerizChart type={BarChart} options={…} /><BarChart data={…} {…options} /> (来自 /react · /vue)
    Svelte use:aeriz={{ type: BarChart, … }} · onReadyuse:barChart={{ … }} · chartOf(node)
    jQuery install($) · .aerizChart(PieChart, …) · 'setData'install($, { PieChart }) · .aerizChart('pie', …) · 'update'
    getFPS · getActiveCount · scheduler · Engine · drawCartesian · toRows · math不再导出(内部使用)