自定义模块
自己写的指标、画线、图形,最简单的做法是直接交给对应的模块(indicators([...allIndicators, MY_INDICATOR]))。当你想把几样东西打包在一起,比如一组自己的指标加一个插件,再给图表加一套自己的接口,就做成一个模块,和图表库的模块一样在建图时传进去。
写一个模块
createModule({ name, install }):install 在图表建好、图表库的模块都装好之后运行,拿到图表本身,返回的对象会成为图表上的新接口。
import { createChart, createModule, withAlpha } from '@kumo-charts/core';
/** 主图上一段高亮的价格区间,可以随时改 */
export function band() {
return createModule({
name: 'band',
install: (chart) => {
let range: { from: number; to: number } | null = null;
let repaint = () => {};
chart.plugins.add({
name: 'band',
attach: (host) => {
repaint = host.repaint;
},
paint: ({ ctx, layer, pane, theme }) => {
if (layer !== 'below' || pane.id !== 'main' || !range) return;
const top = pane.valueToY(Math.max(range.from, range.to));
const bottom = pane.valueToY(Math.min(range.from, range.to));
ctx.fillStyle = withAlpha(theme.accent, 0.12);
ctx.fillRect(0, top, pane.width, bottom - top);
}
});
return {
band: {
set(from: number, to: number) {
range = { from, to };
repaint();
},
clear() {
range = null;
repaint();
}
}
};
}
});
}
const chart = createChart(container, { modules: [band()] });
chart.band.set(62_000, 64_000); // 有类型返回 { band: ... },图表上就多了 chart.band,TypeScript 也知道它。新接口的名字不能和图表已有的重复(比如 data、indicators),重复了建图会报错。不需要新接口时,install 什么都不返回就行。
带上自己的类型
模块里注册指标、画线这些类型,需要图表有对应的模块。install 拿到的 chart 只有核心的类型,用到某个模块的接口时,把它标成带这个模块的图表:
import { createModule, type Chart } from '@kumo-charts/core';
import { indicators, allIndicators, type IndicatorsModule } from '@kumo-charts/core/indicators';
import { drawings, allDrawings, type DrawingsModule } from '@kumo-charts/core/drawings';
export const myToolkit = createModule({
name: 'my-toolkit',
install: (chart) => {
if (!chart.modules().includes('indicators') || !chart.modules().includes('drawings')) {
throw new Error('my-toolkit needs the indicators and drawings modules.');
}
const typed = chart as Chart<[IndicatorsModule, DrawingsModule]>;
typed.indicators.register(DEVIATION);
typed.drawings.register(priceZone);
}
});
createChart(container, {
modules: [indicators(allIndicators), drawings(allDrawings), myToolkit]
});install 在图表使用选项之前运行,所以建图时的选项里就能用模块注册的类型,比如主图直接用自定义的图形:
createChart(container, {
modules: [myToolkit],
mainSeries: { type: 'dots' } // 'dots' 由 myToolkit 注册
});选项、事件和布局
模块还可以像图表库的模块一样:在图表的选项里加一段自己的选项,发自己的事件,在 saveState() 存的布局里存一份自己的东西。要用这些,先用一个类型写清模块加了什么,作为 createModule 的类型参数:
import { createChart, createModule } from '@kumo-charts/core';
interface Range {
from: number;
to: number;
}
interface BandTypes {
/** 图表上的新接口 */
api: { band: { set(range: Range | null): void } };
/** 选项里的一段:options.band */
options: { band: { opacity: number } };
/** 模块的事件 */
events: { bandChange: { range: Range | null } };
/** 布局里存的一份:saveState().band */
state: { band?: Range };
}
export const band = createModule<BandTypes>({
name: 'band',
options: {
key: 'band',
defaults: () => ({ opacity: 0.12 }),
validate: (section, label) => {
if (section.opacity < 0 || section.opacity > 1) {
throw new Error(`${label}.opacity must be between 0 and 1.`);
}
}
},
install: (chart, context) => {
let range: Range | null = null;
const set = (next: Range | null) => {
range = next;
context.emit('bandChange', { range });
};
context.keepState({
key: 'band',
save: () => range ?? { from: Number.NaN, to: Number.NaN },
read: (saved, label) => {
const value = saved as Partial<Range> | null;
if (typeof value?.from !== 'number' || typeof value.to !== 'number') {
throw new Error(`${label} must have from and to.`);
}
return { from: value.from, to: value.to };
},
load: (state) => {
range = state && Number.isFinite(state.from) ? state : null;
}
});
chart.plugins.add({
name: 'band',
paint: ({ ctx, layer, pane }) => {
if (layer !== 'below' || pane.id !== 'main' || !range) return;
const top = pane.valueToY(Math.max(range.from, range.to));
const bottom = pane.valueToY(Math.min(range.from, range.to));
ctx.fillStyle = `rgba(41, 98, 255, ${context.options().opacity})`;
ctx.fillRect(0, top, pane.width, bottom - top);
}
});
return { band: { set } };
}
});
const chart = createChart(container, { modules: [band], band: { opacity: 0.2 } });
chart.on('bandChange', ({ range }) => console.log(range));
chart.band.set({ from: 62_000, to: 64_000 });
chart.applyOptions({ band: { opacity: 0.3 } });选项
options 里的 key 是这段选项在图表选项里的名字。建图时、applyOptions() 时传的这段都合并在 defaults() 上,再交给 validate() 检查;validate() 抛错的话,这次设置什么都不改。模块里用 context.options() 读这段现在的值,chart.options() 里也有它。没有声明 options 的模块调用 context.options() 会报错。
事件
context.emit(名字, 事件) 发出模块的事件,图表的 chart.on() 就能监听,和图表库的事件一样有类型。在一次 API 调用里发出的事件,也和图表的事件一样,等调用做完才派发。
跟着选项变
图表每次设置选项(applyOptions(),以及 loadState() 换了主图的类型时)都会发出 optionsChange,带着设置后的 options 和设置前的 previous。模块比较自己关心的那几项就知道有没有变,比如主图的类型换掉了:
chart.on('optionsChange', ({ options, previous }) => {
if (options.mainSeries.type !== previous.mainSeries.type) {
// 主图换了类型
}
});存进布局
context.keepState() 让 saveState() 存下 save() 的结果,放在 key 下面。loadState() 时先用 read() 检查这一份(抛错就整次读取失败,图表什么都不改),等所有部分都检查通过,再调用 load()。读的布局里没有这一份时(比如是装这个模块之前存的),load() 收到 null。key 不能和图表自己存的(view、panes 等)或别的模块存的重复。
运行顺序
- 图表库的模块先装,然后按
modules里的顺序运行各个自定义模块的install。 install里抛出的错误会让createChart()失败,已经建了一半的图表会被清理掉。- 模块名字在一个图表里不能重复;
chart.modules()列出全部模块的名字。
打包发布
模块就是一个普通的函数,可以放进自己的 npm 包。把 @kumo-charts/core 写成 peerDependencies,用的人装一份图表库,你的模块和他们的图表共用它。