Kumo Charts

カスタム描画ツール

独自の描画ツールも、組み込みのものと同じように扱えます。ユーザーが描き、ドラッグし、選択し、元に戻すことができ、レイアウトに保存でき、アラートで監視することもできます。

描画のタイプは、チャートに 3 つのことを伝えます。アンカーがいくつあるか、どう描くか(paint)、ポインターがどこにあればそれに当たったとみなすか(hitTest)です。ここでは「価格ゾーン」を作ります。2 つのアンカーで上下 2 本の価格ラインを決め、1 つ目のアンカーからチャートの右端まで伸ばします。

コードを表示コードを隠す
import { createChart, withAlpha } from '@kumo-charts/core';
import {
  drawings,
  type Anchors,
  type DrawingTypeDefinition,
  type Positions
} from '@kumo-charts/core/drawings';
import { loadBars } from '@docs/data';

const priceZone: DrawingTypeDefinition<Anchors<2>> = {
  type: 'price-zone',
  points: 2,
  // 設定画面で変更できるスタイル
  fields: ['color', 'fillColor', 'lineWidth', 'lineStyle'],
  defaultStyle: (theme) => ({ color: theme.accent, fillColor: withAlpha(theme.accent, 0.12) }),

  paint: ({ ctx, geometry, selected }) => {
    const { box } = zone(geometry.points);
    const { style, width } = geometry;
    ctx.fillStyle = style.fillColor;
    ctx.fillRect(box.left, box.top, width - box.left, box.bottom - box.top);
    ctx.strokeStyle = style.color;
    ctx.lineWidth = selected ? style.lineWidth + 1 : style.lineWidth;
    ctx.beginPath();
    ctx.moveTo(box.left, box.top);
    ctx.lineTo(width, box.top);
    ctx.moveTo(box.left, box.bottom);
    ctx.lineTo(width, box.bottom);
    ctx.stroke();
  },

  hitTest: (geometry, point, tolerance) => {
    const { box } = zone(geometry.points);
    if (point.x < box.left - tolerance) return null;
    const edge = Math.min(Math.abs(point.y - box.top), Math.abs(point.y - box.bottom));
    if (edge <= tolerance) return { part: 'line', distance: edge };
    return null;
  }
};

/** 2 つのアンカーで囲まれた範囲(ピクセル座標) */
function zone([a, b]: Positions<Anchors<2>>) {
  return {
    box: { left: Math.min(a.x, b.x), top: Math.min(a.y, b.y), bottom: Math.max(a.y, b.y) }
  };
}

const chart = createChart(document.getElementById('chart')!, {
  modules: [drawings([priceZone])]
});

chart.data.set(await loadBars(), { interval: '1m' });
chart.data.setTimeframe('1h');
chart.drawings.startTool('price-zone'); // チャートを 2 回クリックしてみる

座標

paint と hitTest が受け取る geometry には、次のものが入っています。

  • points:アンカーのピクセル座標。ペインのプロット領域の左上を基準とし、置かれた順に並ぶ。
  • anchors:アンカーの時間と価格。
  • width、height:プロット領域のサイズ。
  • style:この描画の最終的なスタイル(デフォルト値に描画自身のスタイルを重ねたもの)。
  • valueToY、yToValue、timeToX:価格・時間とピクセルの間の換算。追加のラインを描くときに使う。
  • bars:表示されている足。たとえばアンカー以降の最高値を探すときに使う。
  • formatValue:価格を軸と同じ書式で表示する。ラベルを描くときに使う。
  • theme、textFont、measureText:テキストを描くときに使う。

DrawingTypeDefinition<Anchors<2>> のようにアンカーの数で型を書くと、points と anchors はちょうど 2 つの組になり、あるかどうかを確かめずに取り出せます。チャートは points と同じ数のアンカーを渡します。

paint の ctx はすでにプロット領域にクリップされ、座標も平行移動済みなので、そのまま CSS ピクセルで描けば大丈夫です。高解像度ディスプレイのスケーリングはチャートが処理します。hovered と selected は、ポインターがその上にあるか、選択されているかを表すので、目立つように描き分けるのに使えます。 破線は描画の線種どおりに描きます。dashPattern(style.lineStyle, style.lineWidth)(@kumo-charts/core/drawings から読み込み)で、組み込みの描画と同じ破線になります。

当たり判定

hitTest は当たらなければ null を返し、当たったときは part と距離を返します。line は線上、body は文字やラベルの枠、塗りつぶして描いたマークといった描画の中身です。塗りつぶしの部分では当たりを返さないでください。塗りつぶしは描画の背景で、そこをクリックすると下にあるものに当たり、ドラッグするとチャートがスクロールします。描画は、チャート組み込みの描画と同じく線をクリックして選びます。描画どうし、あるいは注文ラインやアラートのラインと重なっているときは、線上に当たったものが中身に当たったものより優先されます。同じく線上(または中身)に当たったものの中では近いものが、同じ距離なら上にある(後から描いた)ものが優先されます。tolerance はチャートの interaction.hitTolerance で、デフォルトは 6 ピクセルです。

ハンドル(ドラッグして形を変える小さな点)はチャートが処理します。デフォルトではアンカーごとに 1 つあり、ドラッグするとそのアンカーが動きます。別のハンドルが必要なときは handles() と moveHandle() を書きます。moveHandle() の 4 番目の引数 space は、時間と価格を描くときの位置(足の番号、軸の目盛り上の値)に変換します。この空間で計算すれば、対数軸でも、足の間に欠けがあっても、ハンドルがちょうどポインターの下に来ます。unitHeight は目盛りの 1 単位が画面上で足何本分の幅の高さかを表し、これを使うと角度や長さが画面に見えるとおりになります。5 番目の引数はその描画のスタイルです。ハンドルの id がアンカーの番号('0'、'1'…)なら moveHandle() は省略でき、ドラッグするとそのアンカーが動きます。id がアンカーの番号ではないのに moveHandle() がないと、ハンドルが表示された時点でエラーになります。

その他のオプション

オプション 働き
points: 0 アンカー数が決まっていない。ダブルクリックか Enter で終了する。パスなど
freehand 押したままドラッグして描く。ブラシなど(points: 0 と組み合わせる)
place、complete() ユーザーが置くのは最初のいくつかのアンカーだけで、残りはあなたが計算する。目標価格から対称に損切り価格を出すなど。complete() は points 個のアンカーを返すこと。そうでないとそのクリックでは置けず、エラーになる
mainPane メインペインのローソク足から計算する(geometry.bars を読むなど)。メインペインにだけ置ける
paintBelow() ローソク足の下に描く部分。ポジションの損益エリアなど
editableText 置いた直後とダブルクリックしたときに、テキスト編集ボックスを開く
axisMarks() 選択中に軸上で強調表示する価格と時間。2 番目の引数はスタイル
bounds() 描画が占める範囲(アンカーの外に伸びる線やラベルを含む)。chart.drawings.bounds() はこれを返す。何も描かないときは null で、ユーザーもそこには置けない。省略するとハンドルを囲む範囲
levels() アラートが監視できるライン

bounds() を書いた描画は、その範囲が画面の外に完全に出ているときは描かれず、ポインターが近くにないときは当たり判定もされません。そのため bounds() には描くものと当たるものをすべて含めてください。書かない描画はいつも描かれ、判定されます。

アラートで監視できるようにする

levels: ([a, b]) => {
  const top = Math.max(a.price, b.price);
  const bottom = Math.min(a.price, b.price);
  const time = Math.min(a.time, b.time);
  return [
    // 2 点の時間が同じなら水平線になる。extend: 'end' で右端まで伸ばす
    { key: 'top', from: { time, price: top }, to: { time, price: top }, extend: 'end' },
    { key: 'bottom', from: { time, price: bottom }, to: { time, price: bottom }, extend: 'end' }
  ];
};

これで「価格がこのゾーンに入った」というアラートを設定できます。

chart.alerts.add({
  id: 'zone',
  trigger: 'enter-channel',
  value: [
    { kind: 'drawing', id: zoneId, level: 'top' },
    { kind: 'drawing', id: zoneId, level: 'bottom' }
  ]
});

使う

import { drawings, allDrawings } from '@kumo-charts/core/drawings';

createChart(container, { modules: [drawings([...allDrawings, priceZone])] });

// または作成したあとで
chart.drawings.register(priceZone);

新しいバージョンの定義に差し替える(ページがこの描画の描き方を更新したなど)には replace() を使います。チャート上のこの種類の描画は残り、新しい定義で描き直されます。このツールを使用中なら取り消されます。アンカー数が変わる場合は、先にチャート上のこの種類の描画を削除してから差し替えます。不要になったら unregister() で外します(チャート上にこの種類の描画があるとエラーになります)。

描画以外のデータ(ページが描画ごとに計算した値など)を読んで描く場合、データが変わったら refresh() を呼んで描き直します。チャートはデータの変化を自分では検知できません。

chart.drawings.replace({ ...priceZone, fields: ['color', 'fill', 'fillColor'] });
chart.drawings.refresh();

スタイルをチャートが受け付けるか先に確かめるには(ユーザーが入力したもの、別の場所に保存したものなど)、checkDrawingStyle() を使います。受け付けられない場合は、どこが違うかを示すエラーになります。

import { checkDrawingStyle } from '@kumo-charts/core/drawings';

checkDrawingStyle({ lineWidth: 2, levelRange: { start: 0, end: -1 } });

↑↓ で選択 · Enter で開く · Esc で閉じる