사용자 정의 시리즈
차트는 두 단계로 봉을 표시합니다. 먼저 어떤 봉을 표시할지 정하고(봉 변환, 예: 렌코는 봉을 벽돌로 바꿈), 그다음 어떻게 그릴지 정합니다(시리즈 유형, 예: 캔들, 라인). 두 단계 모두 직접 작성할 수 있습니다.
그리는 방식 직접 작성하기
아래 시리즈 유형은 봉마다 종가 위치에 점을 하나 찍습니다.
코드 보기코드 숨기기
import { createChart, type SeriesTypeDefinition } from '@kumo-charts/core';
import { loadBars } from '@docs/data';
interface DotsStyle {
color: string;
radius: number;
}
const dots: SeriesTypeDefinition<DotsStyle> = {
type: 'dots',
input: 'value', // 봉마다 값 하나, 'ohlc'이면 시가·고가·저가·종가를 받음
defaultStyle: (_theme, color) => ({ color, radius: 2 }),
paint: ({ ctx, points, style }) => {
ctx.fillStyle = style.color;
for (let i = 0; i < points.count; i += 1) {
const y = points.value(i);
if (Number.isNaN(y)) continue; // 값이 없는 곳
ctx.beginPath();
ctx.arc(points.x(i), y, style.radius, 0, Math.PI * 2);
ctx.fill();
}
}
};
const chart = createChart(document.getElementById('chart')!);
chart.series.register(dots);
chart.data.set(await loadBars(), { interval: '1m' });
chart.data.setTimeframe('1h');
chart.series.add({
type: 'dots',
data: chart.data.toArray().map((bar) => ({ time: bar.time, value: bar.close }))
});paint는 화면에 보이는 점만 받으며, 좌표는 이미 변환되어 있습니다.
points.x(i): i번째 점의 가로 좌표(봉의 중심).input: 'value'일 때points.value(i)는 세로 좌표입니다.input: 'ohlc'일 때는points.open(i),high(i),low(i),close(i)를 쓰고,points.isUp(i)는 상승 여부입니다.points.color(i): 메인 시리즈의barColor가 이 봉에 지정한 색상, 없으면null.barSpacing: 봉 하나가 차지하는 너비. 막대나 캔들의 너비를 정할 때 씁니다.valueToY: 기준선처럼 추가 요소를 그릴 때 씁니다.
ctx는 이미 플롯 영역으로 잘려 있고 좌표도 옮겨져 있으므로 CSS 픽셀 단위로 그립니다.
defaultStyle(theme, color)는 완전한 기본 스타일을 반환합니다. color는 차트가 이 시리즈에 배정한 색상이며(겹쳐 놓은 시리즈에는 테마의 palette에서 차례로 배정), 사용자가 준 스타일이 그 위에 병합됩니다. 가격 축이 데이터 외에 다른 값(예: 막대의 시작점)도 담아야 한다면 extraExtents(style)에서 그 값들을 반환합니다.
메인 시리즈에 쓰기
등록한 시리즈 유형은 메인 시리즈에도 쓸 수 있습니다.
chart.applyOptions({ mainSeries: { type: 'dots' } });TypeScript에서는 메인 시리즈의 유형이 차트가 아는 이름이어야 하므로, 선언 병합으로 알려 줍니다.
declare module '@kumo-charts/core' {
interface SeriesStyleMap {
dots: DotsStyle;
}
}이렇게 하면 mainSeries.type: 'dots'와 mainSeries.styles.dots 모두 타입 검사를 받습니다.
봉 변환 직접 작성하기
봉 변환은 현재 주기의 봉을 받아 하나씩 새 봉을 만듭니다. 아래 변환은 N개 봉마다 하나로 합칩니다.
import type { Bar, BarTransformDefinition, BarTransformStream } from '@kumo-charts/core';
class MergeStream implements BarTransformStream {
constructor(
private readonly size: number,
private forming: Bar | null = null,
private count = 0
) {}
next(bar: Bar): readonly Bar[] {
const f = this.forming;
this.forming = f
? {
time: f.time,
open: f.open,
high: Math.max(f.high, bar.high),
low: Math.min(f.low, bar.low),
close: bar.close,
volume: f.volume + bar.volume
}
: { ...bar };
this.count += 1;
if (this.count < this.size) return []; // 아직 다 모이지 않아 완성된 봉이 없음
const done = this.forming;
this.forming = null;
this.count = 0;
return [done];
}
current(): Bar | null {
return this.forming; // 아직 형성 중인 봉, 맨 끝에 그림
}
clone(): BarTransformStream {
return new MergeStream(this.size, this.forming, this.count);
}
}
export const mergeBars: BarTransformDefinition<{ size?: number }> = {
type: 'merge',
name: 'Merge',
keepsTime: false,
create: ({ size = 3 }) => {
if (!Number.isInteger(size) || size < 1)
throw new Error('merge: size must be a positive integer');
return new MergeStream(size);
}
};
chart.transforms.register(mergeBars);
chart.transforms.set({ type: 'merge', params: { size: 5 } });몇 가지 규칙이 있습니다.
next(bar, side)는 이 입력으로 완성된 봉(0개, 1개 또는 여러 개)을 시간 순서대로 반환합니다. 체결로 만들 때side는 그 체결의 시장가 쪽(buy,sell, 모르면null)이며, 봉으로 만들 때는null입니다. 쓰지 않는다면 이 인자는 생략해도 됩니다.current()는 아직 완성되지 않고 형성 중인 봉을 반환하며, 없으면null입니다.clone()은 모든 상태를 복사해야 합니다. 최신 봉이 실시간으로 업데이트되면 차트는 업데이트 이전의 복사본에서 다시 계산합니다.keepsTime: 입력 봉 하나가 정확히 시간이 같은 출력 봉 하나가 될 때(하이킨 아시처럼)true로 지정하면, 차트는 카운트다운처럼 주기에 의존하는 기능을 유지합니다. 그렇지 않으면false입니다.create(params, input, from)의input은 곧 입력될 모든 봉으로, 자동 크기를 계산할 때 쓸 수 있습니다(예: 평균 실제 범위로 벽돌 높이 결정).from은 그것이 무엇인지 알려 주며,'bars'는 현재 주기의 봉,'trades'는 체결 하나하나입니다. 매개변수가 잘못되었으면 오류를 던지세요.transforms.set()이 그 오류를 호출한 쪽에 전달합니다.
자동으로 계산한 매개변수를 보고하면 chart.transforms.get().resolved로 읽을 수 있어 화면에 표시할 수 있습니다. 아직 정해지지 않았으면 null을 반환합니다. 계산기에 메서드를 하나 추가합니다.
class MergeStream implements BarTransformStream {
// ……위의 메서드들
resolved(): Readonly<Record<string, unknown>> {
return { size: this.size };
}
}둘을 함께 쓰기
카기처럼 만들어진 봉을 전용 방식으로 그려야 할 때는 변환과 시리즈 유형을 각각 등록한 뒤 함께 켭니다.
chart.batch(() => {
chart.transforms.set({ type: 'merge', params: { size: 5 } });
chart.applyOptions({ mainSeries: { type: 'dots' } });
});시리즈 유형의 paint에서 transform은 변환이 보고한 매개변수(resolved)이며, 박스 크기 같은 것을 그릴 때 쓸 수 있습니다.
차트를 만들 때부터 이 유형들을 포함하거나, 다른 프로젝트에서 쓰도록 패키지로 묶으려면 사용자 정의 모듈을 참고하세요.