Kumo Charts

数据

主图的 K 线都通过 chart.data 读写。写进去的是原始数据;读出来的是显示的 K 线,也就是合成周期、K 线变换、回放之后的样子。

K 线的格式

interface BarInput {
  time: number | string | Date; // 毫秒时间戳、ISO 8601 字符串或 Date
  open: number;
  high: number;
  low: number;
  close: number;
  volume?: number; // 默认 0
}

图表会检查每根 K 线:价格必须是有限的数字,high 和 low 要把 open、close 包在中间,成交量不能是负数,时间要从早到晚、不能重复。不对的话抛出 ChartError,信息里写明是第几根、哪里不对,图表保持原样。

传进去的数组图表会复制一份,之后你改它不影响图表,图表也不会改它。

整批设置

chart.data.set(bars);

换品种时再调一次 set() 就行,原来的 K 线全部换掉。视图停在原来的时间、保持原来的缩放:用户原本看着最新的 K 线,新的最新 K 线就出现在原来的位置,离右边缘一样远;原本在往回看历史,图右边缘的时间不变。切换周期和 K 线类型也一样。

如果 K 线是固定周期的,最好同时告诉图表周期:

chart.data.set(bars, { interval: '1m' });

给了周期,图表才能在浏览器里合成更大的周期、把逐笔成交合进 K 线。见周期和交易日历。

实时更新

chart.data.update(bar);
chart.data.update([bar1, bar2]); // 一次推好几根

时间和最后一根相同就替换它,比它晚就接在后面,比它早就报错(历史 K 线用 set() 或 prepend())。

用户正看着最新的 K 线时,新 K 线进来图表会跟着往前走;用户往回翻看历史时,图表不动。

逐笔成交

拿到的是逐笔成交,就直接交给图表,它会合进当前这根 K 线,到了下一根的时间自己开新的一根:

chart.data.addTrades({ time: 1767225600123, price: 87601.5, size: 0.02 });
chart.data.addTrades(trades); // 一次给一批,按时间排好

size 是成交数量,加到 K 线的成交量上,默认 0。side 是主动成交的一方:buy 主动买入(吃掉卖单),sell 主动卖出,不知道就不写;按成交生成 K 线的变换会拿到它(见自己写一种 K 线变换)。这需要 set() 时给了 interval。迟到的成交会被跳过:比最后一根 K 线还早、或者比已经给过的最新一笔还早,比如断线重连后补发的。设了交易时段的话,时段外的成交也会被跳过。addTrades() 返回实际用上的笔数。

按成交笔数、成交量生成的 K 线(见图表类型)要用到成交本身,图表会保留最近的一部分,数量由 performance.maxTrades 决定,默认 10 万笔。

加载更多历史

用户往左拖到快没有 K 线时,图表发出 loadMore 事件:

chart.on('loadMore', async ({ before }) => {
  const older = await fetchBars({ endTime: before - 1 });
  chart.data.prepend(older);
});

before 是现在第一根 K 线的时间。prepend() 把更早的 K 线加到前面,和已有的重叠的部分会被忽略,返回实际加了几根。加完第一根变了,用户再往左拖就会再发一次;什么也没加,就要等用户拖开再拖回来才会再发。

还剩多少根时发出,由 timeScale.loadMoreThreshold 决定,默认 20 根。bars 是视图还想要多少根(按显示的 K 线算):离这个数还差的,加上左边空着的地方。卡吉图、砖形图这类由很多根合成一根的,每根要的原始 K 线也成倍增加,按这个数一次取够,不要一页一页地取。

清空

chart.data.clear();

K 线全部移除,正在进行的回放也会结束。周期设置保留。

读取

chart.data.length; // 显示的 K 线有几根
chart.data.at(0); // 第一根,没有就是 null
chart.data.last(); // 最后一根
chart.data.indexOf(time); // 某个时间的那一根在第几个,没有就是 -1
chart.data.toArray(); // 全部复制成数组

读出来的 K 线 time 一律是毫秒时间戳。

要遍历很多根的话,用 chart.data.bars,它按列直接读,不复制:

const { bars } = chart.data;
let highest = -Infinity;

for (let i = 0; i < bars.length; i += 1) {
  highest = Math.max(highest, bars.high(i));
}

chart.data.source 是同样的视图,读的是原始周期的 K 线(回放时只到当前那一根)。

K 线变了

显示的 K 线有任何变化(设置、更新、加载历史、切换周期、回放)都会发出 barsChange:

chart.on('barsChange', ({ change }) => {
  if (change.kind === 'tail') {
    // 只有第 change.from 根之后变了,或者接上了新的
  } else {
    // 'reset':哪一根都可能变了
  }
});

自己根据 K 线算东西的时候,可以靠它只重算变了的那部分。

叠加其它数据

主图以外的数据,比如对比的另一个品种、自己算好的一条线,用 chart.series 叠加上去,见窗格。

↑↓ 选择 · Enter 打开 · Esc 关闭