销售仪表盘
KPI 卡片、组合图、环形图、热力图和漏斗图共 8 个图表。每个图表只需几个选项,月度/季度切换只是一次 update()。
用一个选项对象绘制 26 种 Canvas 图表的库。用法只有一种,在 React · Vue · Svelte · jQuery 中名称和选项也完全相同。
@aeriz/chart 用一个选项对象绘制 26 种 Canvas 图表。只需传入容器和数据,坐标轴、图例、提示框、动画和主题都由默认值负责。
data,修改用 update(),状态用 setState()。26 种图表、5 种环境完全一致。2.1.1 新功能 提示框中的链接和按钮与自定义内容、可接管的图例点击,以及获取指针下的数据项。2.1 的代码可直接运行。
2.1 新功能 参考线与区间、缩放与刷选、联动、百分比堆叠、误差线、多值轴,以及K 线、矩形树图与旭日图、桑基图、关系网络和地图。2.0 的代码可直接运行。
以下示例按真实产品界面制作。它们都在本页实时运行,JS、HTML、CSS 标签页中就是构建该界面的全部代码。每个图表都只是 new SomeChart(element, { data }) 再加几个选项。各类图表的样子见图表类型。
KPI 卡片、组合图、环形图、热力图和漏斗图共 8 个图表。每个图表只需几个选项,月度/季度切换只是一次 update()。
带右轴的四层组合图、堆叠面积图、ARR 桥图、同期群留存、四分位分布、20,000 个点和 8,760 格热力图,共 9 个图表。一个分段按钮就对全部图表调用 update()。
注册数(柱)和 8 周均值(面积)使用左轴,转化率(线)使用右侧百分比轴。红点表示明显偏离均值的周。
点击图例可去掉某个渠道,其余渠道会重新堆叠。
从期初 ARR 经过新增、扩展、收缩和流失到期末。
尚未到来的月份保持为空(null)。
由 8,000 次会话计算出的四分位数和离群值。
六项调查指标,满分 10 分。
按套餐着色。悬停可选中单个用户。
与散点图使用同一份数据统计。
周末和通勤时段很明显。每个格子都有提示框。
点击左侧的地区柱,onClick 会把其他图表切换到该地区,并重新生成、绘制 1,000,000 条按秒记录的交易。耗时直接显示在顶部。
每 0.1 秒滚动更新的实时折线、3 个仪表盘和各 API 的响应时间。试试点击“模拟故障”。
把同样的图表放在白纸上,它会读取文字颜色和背景,自动变成浅色主题。品牌色只需两行 CSS 变量。
总体满意度为 4.3 分(满分 5 分),比去年提高 0.4 分。各年龄段的得分都有上升,配送提速的影响最大。
选择你使用的包管理器。不使用构建工具时,请看 CDN 标签页。
npm install @aeriz/chartpnpm add @aeriz/chartyarn add @aeriz/chart<!-- 全部(全局变量 Aeriz,gzip 后约 38 KB) -->
<script src="https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/aeriz.min.js"></script>
<!-- 单个图表(ES 模块) -->
<script type="module">
import { BarChart } from 'https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/esm/charts/bar.js';
</script>npm 包中只有压缩后的构建产物(dist/)和 TypeScript 类型。
import → 按图表拆分的 dist/esm/require → dist/aeriz.min.cjsdist/aeriz.min.js压缩只缩短局部变量名。选项名、方法、图表名和错误信息都保持原样,可以直接阅读。
提示 在 CDN 地址中写上确切版本号,例如 @2.1.1。地址不会变,因此会被缓存一年。
只需要一个有高度的元素和一些数据。没有设置高度时,图表高 320px。
<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 接受以下三种写法中的任意一种,含义完全相同。
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(误差线)。
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 选项传入 — 地图 |
写错选项或数据结构无法识别时,图表不会默默地显示空白。浏览器控制台会说明哪里错了、怎么改,每条消息只提示一次。
[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 适配器引入也一样。
import { BarChart, PieChart } from '@aeriz/chart'; // 只包含这两个和公共核心不使用打包工具,或想确保只引入一个图表时,从子路径 import。
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
五种环境使用相同的图表名和选项。不用框架时,直接使用类即可。
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(); // 元素离开页面时从 @aeriz/chart/react 引入与图表同名的组件,所有选项都是 props。支持 React 16.8 及以上版本。
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 }}
/>
);
}update()。每次渲染都重新创建的内联对象和函数,只要值相同就不会重绘。[...rows, row])。className、style、id、aria-* 和 data-* 会加到外层 <div> 上。在 StrictMode 下也只创建一个图表。从 @aeriz/chart/vue 引入与图表同名的组件。选项是 props;onClick、onHover、onLegend、onZoom 对应事件 @click、@hover、@legend、@zoom。支持 Vue 3.2 及以上版本。
<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())不会被检测到。
@aeriz/chart/svelte 为每种图表提供一个 action(barChart、lineChart、multiLineChart …),参数就是选项。无需配置编译器,Svelte 3、4、5 用法相同。
<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)。
用 install($, { … }) 注册要用的图表,再按子路径名('bar'、'pie' …)创建。如果先加载了 jQuery,CDN 脚本(aeriz.min.js)会自动注册全部 26 种。
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 });<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@aeriz/chart@2.1.1/dist/aeriz.min.js"></script>
<script>
$('#share').aerizChart('pie', { data: { Chrome: 64, Safari: 19 } });
</script>$('#share').aerizChart('update', { data: { Chrome: 70, Safari: 20 } }); // setState · render · destroy 用法相同
$('#share').aerizChart('instance'); // 图表实例以下图表都在实时运行。点击图例可以隐藏或显示对应系列。
| 类 | 子路径 | data | 说明 |
|---|---|---|---|
BarChart | bar | 每项一个值 | 负值向下,dataLabels |
HBarChart | hbar | 每项一个值 | 横向,标签栏宽度随标签自适应 |
LineChart | line | 每项一个值 | curve、时间轴、对数轴、百万级数据点、缩放、区间 |
AreaChart | area | categories · series | stacked('percent')、缩放 |
StackedBarChart | stacked-bar | categories · series | 负值向下堆叠,stacked: 'percent' |
GroupedBarChart | grouped-bar | categories · series | 系列并排,误差线 |
MultiLineChart | multi-line | categories · series | 跟随指针的共享提示框,缩放,区间 |
ScatterChart | scatter | [{ x, y }] | 按颜色和大小批量绘制,缩放 |
BubbleChart | bubble | [{ x, y, size }] | size 表示面积 |
PieChart | pie | 每项一个值 | 用 innerRadius 做成环形图,可从图例切换扇区 |
RadarChart | radar | categories · series | 每个点都有提示框 |
PolarChart | polar | 每项一个值 | 面积与数值成正比(按半径用 scale: 'linear') |
GaugeChart | gauge | 一个数字 | update({ data }) 从当前显示的值开始变化 |
HeatmapChart | heatmap | { x, y, values } | colors: { low, high } |
BoxplotChart | boxplot | [{ min, q1, median, q3, max }] | 离群点 |
FunnelChart | funnel | 每项一个值 | 相对第一阶段的转化率 |
TreemapChart | treemap | 每项一个值(+ children) | 近似正方形布局,分组带标题 |
SparklineChart | sparkline | 每项一个值 | 无坐标轴的迷你趋势线 |
RealtimeChart | realtime | { series } + push() | 在固定窗口内滚动 |
WaterfallChart | waterfall | [{ label, value, total? }] | 累计值 |
CompositeChart | composite | categories · series(type) | 混合柱、线、面积、点;多个数值轴、堆叠柱、缩放 |
CandlestickChart | candlestick | [{ label, open, high, low, close }] | 贴合价格的坐标轴、缩放、数万根 K 线 |
SunburstChart | sunburst | 每项一个值(+ children) | 每层一个环,中心显示占比 |
SankeyChart | sankey | { links, nodes? } | 粗细与数值成比例的流向带 |
NetworkChart | network | { nodes, links } | 力导向布局,高亮相邻节点 |
MapChart | map | 每项一个值 + geo | 为 GeoJSON 区域着色,scale: 'log' |
绘制每个周期的开盘价、最高价、最低价和收盘价。实体从开盘价画到收盘价(上涨用 colors.up,下跌用 colors.down),影线从最低价画到最高价。数值轴不从 0 开始,而是贴合当前可见的价格。
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 的行会成为分组,分组的值是其子项之和。层级深度不限。
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 });{ JS: 42, TS: 30 })与 2.0 的绘制结果完全相同。Engineering › Backend: $42M),onClick 也会以 hit.path 收到同样的路径。用粗细与数值成比例的带子绘制各阶段之间的流向。节点由连线生成,按从起点出发的最长路径排到右侧相应的列。没有流出的节点排在最后一列。
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() 会直接绘制稳定后的布局。
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 匹配。
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 可以修改提示框中的区域名。properties 包含英文名(name)、韩文名(ko)和人均 GDP(gdp)。不含南极洲。向 RealtimeChart push() 的值会出现在右端,超出 window 的值从左端移出。
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 轴(标签、时间或数值)。
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' }, // 垂直参考线
],
});y)。其他图表会在控制台提示。label 在水平线右端上方(线在顶部时放在下方),在垂直线顶端;color 用于线、区间带和文字(默认为浅色文字)。x 是数值,y 是项目标签。CompositeChart 用 axis 选择线所在的数值轴(更多数值轴)。update({ annotations }) 只重绘这些线,不带动画。设置 zoom: true 后可以缩放和平移 x 轴。支持 LineChart、MultiLineChart、AreaChart、CompositeChart、CandlestickChart 和 ScatterChart。放大时数值轴贴合可见数据(含柱或面积的轴从 0 开始)。
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 组中的图表放大显示。拖动选区边缘可调整大小,拖动内部可移动选区。
new LineChart('#detail', { data, xScale: 'time', sync: 'traffic' });
new LineChart('#overview', { data, xScale: 'time', sync: 'traffic', zoom: 'brush', range: [from, to] });sync 名称相同的图表共享十字准线和缩放范围。它们按相同的 x 值(标签、时间或数值)对齐,所以图表类型和数据长度可以不同。
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 });悬停其中一个图表或拖动放大,另外两个会跟着变化。
range 加入时,会把它交给分组。update({ sync: null }) 退出分组。onZoom 只在用户操作的图表上触发,所以每个分组处理一次即可。stacked: 'percent' 把每个项目的合计按 100% 换算后堆叠占比。数值轴为 0–100%,提示框在原始值旁显示占比。
new StackedBarChart(el, { data, stacked: 'percent' }); // 默认 true(按原值)
new AreaChart(el, { data, stacked: 'percent' }); // true · false · 'percent'
new CompositeChart(el, { data, stacked: true }); // 同一坐标轴上的柱(也支持 'percent')百分比堆叠表示正值的占比,所以负值按 0 处理,控制台会给出提示。StackedBarChart 总是堆叠,因此其 stacked 只接受 true(默认)和 'percent'。
在行中加上 low 和 high,柱会带误差线,线会带区间带。系列数据接收与数值一一对应的 low、high 数组。数值轴会扩展到能显示整个区间,提示框显示为 value (low – high)。
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 在行上接收,GroupedBarChart、MultiLineChart 和 CompositeChart 在系列上接收(Composite 在柱和点上画误差线,在线和面积上画区间带)。其他图表会在控制台说明已忽略它们。
给 CompositeChart 的系列指定 axis 名称,每个名称都有自己的数值轴。'left'(默认)在左侧,其他名称按出现顺序排在右侧,同名系列共用一个轴。stacked 会堆叠同一轴上的柱。
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 作用于左侧轴,其他轴贴合各自的数据。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 中。各框架中的名称都一样。
new BarChart(el, { data: rows, onClick: open, onHover: show, tooltip: { actions } });<BarChart data={rows} onClick={open} onHover={setHovered} tooltip={{ actions }} /><BarChart :data="rows" :tooltip="{ actions }" @click="open" @hover="(hit) => (hovered = hit)" /><div use:barChart={{ data: rows, onClick: open, onHover: (hit) => (hovered = hit), tooltip: { actions } }}></div>$('#sales').aerizChart('bar', { data: rows, onClick: open, onHover: show, tooltip: { actions } });在 React 中,即使每次渲染都传入新的函数或 tooltip 对象,图表也不会重绘。
tooltip.actions 返回的列表显示在提示框下方。带 href 的是链接,只有 onClick 的是按钮。点击时先执行 onClick(hit, chart, event),然后提示框关闭。可以在这个函数里打开弹窗、侧边面板或其他页面。
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。带链接或按钮的提示框会等待鼠标移过来。无需任何设置,没有链接或按钮的提示框仍像以前一样立即跟随鼠标。
tooltip.render(hit, chart) 的返回值就是提示框的内容。每个项目只调用一次,鼠标停在同一项目上时不会再次调用。同时指定 actions 时,链接和按钮会排在你的内容下方。
| 返回值 | 提示框 |
|---|---|
| 字符串或数字 | 该文本(不会被解析为 HTML) |
| DOM 节点 | 原样显示该节点。内含链接或按钮时,会成为等待鼠标的提示框 |
null | 该项目不显示提示框 |
undefined | 默认提示框 |
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}` }],
},
});指向柱子即可看到门店卡片。
<template>,再用 textContent 填入数据,最为方便。返回 HTML 字符串时会按纯文本显示,控制台会提示改为返回节点。--aeriz-tooltip-bg · --aeriz-tooltip-fg)。在 onClick 中调用 update({ data }) 就实现了下钻。新数据以动画方式进入,键盘上按 Enter 效果相同。
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,保存下来,下次就能以相同状态打开图表。
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 即可关闭。
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,指针下的项目也能在你的图例中高亮。
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 调用。鼠标、触屏和键盘(← →)的行为一致。可以用它在侧边面板而不是提示框中显示详情、高亮表格中的同一行,或对齐其他视图。
new CompositeChart('#revenue', {
data: { categories: months, series: [thisYear, lastYear] },
tooltip: false, // 用侧边面板代替提示框
onHover: (hit) => (hit ? showMonth(hit.index) : showYear()),
});在图表上移动鼠标。离开后面板会回到全年合计。
hit 只有 index 和 label。请用 index 从你的数据中读取数值。sync 联动的图表中,只有用户指向的图表会调用 onHover,跟随的十字准线不会调用。无需任何设置,图表会读取元素的文字颜色、字体和背景,并据此生成网格和坐标轴的颜色。因此图表能直接适配浅色和深色页面,系统切换深色模式时也会重新读取主题。只需用 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-radius | 2 · 3 · 3 |
--aeriz-tooltip-bg · --aeriz-tooltip-fg | 深色背景 · 白色文字 |
--aeriz-surface | transparent(画布背景) |
--aeriz-color-1 … 12 | PALETTE 的 8 种颜色 |
format 格式化数值(提示框和数值轴),labelFormat 格式化标签(x 轴标签和提示框标题)。没有按坐标轴区分的格式选项。
{ 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' } // 时间轴标签1.2万,英文 12K)。要固定语言,请传入函数:format: (v) => v.toLocaleString('zh-CN')format,该系列所在的轴也使用相同格式。legend: false 隐藏图例,hidden: [1] 让该项一开始就处于隐藏状态。想在点击时做别的事,请看图例事件。tooltip: false 关闭;自定义内容以及链接和按钮,请看自定义提示框内容和提示框中的链接和按钮。onClick,Esc 关闭。Tab 进入提示框中的链接和按钮。读取的数值会播报给屏幕阅读器。onClick(hit, chart) 只在点击项目时调用。hit 包含 index、label、value、series(系列序号)和 row(你传入的项目本身),层级图还有 path(从顶层开始的名称)。结束缩放或刷选拖动的那次点击不算作项目点击。new BarChart(el, {
data: rows,
title: '月度销售额', // 屏幕阅读器朗读的名称
onClick: (hit) => openDetail(hit.row),
});chart.setState('loading', '加载中…');
chart.setState('error', '网络错误');
chart.setState('empty'); // emptyText(默认 'No data')
chart.setState(null); // 关闭数据为空时会自动显示 emptyText,数据到达后自动消失。动画在图表滚动进入视口时开始,可用 animate: false 关闭;对开启了“减弱动态效果”的用户始终关闭。
所有选项都有默认值,只传你需要的即可。特定图表类型的选项见各图表选项。
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
data | 取决于图表 | — | 见数据格式 |
title | string | 图表类型名 | 屏幕阅读器朗读的名称;Gauge 会显示在数值下方 |
colors | string[] | CSS 变量或 PALETTE | 该图表的颜色(Heatmap 和 Waterfall 为对象) |
format | Intl options | (v) => string | 浏览器语言 | 提示框和数值轴的数字格式 |
labelFormat | (label) => string | — | x 轴标签和提示框标题(带坐标轴的图表) |
min · max | number | 根据数据 | 数值轴范围(带坐标轴的图表、Gauge、Realtime) |
legend | boolean | 多个系列时显示 | false 隐藏 |
hidden | number[] | [] | 要隐藏的图例项位置;点击图例会更新它(带图例的图表)— 图例事件 |
tooltip | boolean | { render?, actions? } | true | false 关闭。render:内容,actions:链接和按钮 — 自定义内容 · 链接和按钮 |
animate | boolean | true | 首次绘制和变化时播放动画 |
emptyText | string | '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? }[] | — | 参考线、目标线和区间带(带数值轴的图表)— 参考线 |
zoom | boolean | 'brush' | false | 缩放和平移,或刷选(Line、MultiLine、Area、Composite、Candlestick、Scatter)— 缩放 |
range | [from, to] | null | 全部 | 要显示的 x 范围(上述图表,无论是否开启 zoom) |
onZoom | (range, chart) => void | — | 用户修改了范围 |
sync | string | — | 与同名图表共享十字准线和范围 — 联动 |
| 方法 | 返回值 | 说明 |
|---|---|---|
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) |
| Bar | dataLabels: true 或 (value, row, index) => string。行的 low · high 绘制误差线 |
| Line | curve: 'smooth' · 'linear' · 'step', xScale: 'category' · 'time', yScale: 'linear' · 'log', fill、points。行的 low · high 绘制区间带 |
| MultiLine | curve, xScale |
| Area | stacked: true · false · 'percent' |
| StackedBar | stacked: true(默认) · 'percent' |
| Bubble | radius: [min, max] px(默认 [4, 32]) |
| Pie | innerRadius:占半径的比例 0–0.9(0.6 = 环形图),center:中心文字或 false |
| Polar | scale: 'sqrt' · 'linear' |
| Radar | max(最外环的值) |
| Gauge | min (0), max (100), unit |
| Heatmap | colors: { low, high } |
| Waterfall | colors: { up, down, total } |
| Funnel · Treemap · Sunburst | labelColor(#fff)。Sunburst:center(中心文字)或 false |
| Sparkline | fill, lastDot, min, max |
| Realtime | window (200), min, max |
| Composite | 每个系列的 type: 'bar' · 'line' · 'area' · 'scatter', axis:数值轴名称(默认 'left'),format,low · high;图表上有 xScale、 stacked: true · 'percent' |
| Candlestick | xScale, colors: { up, down } (#10b981 · #ef4444) |
| Network | radius: [min, max] px(默认 [4, 16]) |
| Map | geo: GeoJSON, projection: 'mercator' · 'equirectangular', scale: 'linear' · 'log', colors: { low, high }, labelFormat:区域名 |
包内附带 TypeScript 类型,编辑器会在你输入时提示每种图表的选项和数据格式。
2.0 中每件事只保留一种做法。使用 1.x 的名称时,控制台会告诉你新名称,打开页面按警告修改即可。如果要继续使用 1.x,请安装 npm install @aeriz/chart@1。
// 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.x | 2.0 |
|---|---|
setData(d) | update({ data: d }) |
setLoading · setEmpty · setError · clearState | setState('loading' | 'empty' | 'error' | null, text?) |
invalidate() | render() |
Gauge setValue(v) · value · label | update({ 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 · waitingText | data: { series } · window · min · max · emptyText |
ariaLabel | title |
palette · color | colors |
colorLow/High · colorUp/Down/Total | colors: { low, high } · colors: { up, down, total } |
yTickFormat · xTickFormat | format · labelFormat |
yLeftTickFormat · yRightTickFormat | 每个系列上的 format |
interpolation ('step-after' …) | curve: 'smooth' · 'linear' · 'step' |
yMin · yMax | min · max (所有带坐标轴的图表) |
minRadius · maxRadius | radius: [min, max] |
centerLabel: false · totalLabel | center: false · center: 'text' |
Pie innerRadius: 80 (px) · 'auto' | innerRadius: 0.6 (仅比例) |
Waterfall isTotal | total |
Scatter r · Bubble z | size |
Composite 的点 values: [{ x, y }] | values: [value | null],与其他系列一致 |
[['Jan', 64], …] 形式的数组对 | { Jan: 64 } 或 [{ label, value }] |
Sparkline | SparklineChart |
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, … }} · onReady | use:barChart={{ … }} · chartOf(node) |
jQuery install($) · .aerizChart(PieChart, …) · 'setData' | install($, { PieChart }) · .aerizChart('pie', …) · 'update' |
getFPS · getActiveCount · scheduler · Engine · drawCartesian · toRows · math | 不再导出(内部使用) |