Kumo Charts

データ

メインペインのローソク足は、すべて chart.data で読み書きします。書き込むのは元データで、読み出すのは表示されるローソク足、つまり時間足の合成、ローソク足の変換、リプレイを経たあとの足です。

ローソク足の形式

interface BarInput {
  time: number | string | Date; // ミリ秒のタイムスタンプ、ISO 8601 文字列、または Date
  open: number;
  high: number;
  low: number;
  close: number;
  volume?: number; // デフォルトは 0
}

チャートは足を 1 本ずつチェックします。価格は有限の数値であること、high と low が open と close を挟んでいること、出来高が負でないこと、時間が古い順に並び重複しないこと。条件を満たさない足があると ChartError を投げ、何本目のどこがおかしいかをメッセージで示します。チャートはそのままです。

渡した配列はチャートがコピーします。あとで配列を変更してもチャートには影響せず、チャートが配列を書き換えることもありません。

まとめて設定する

chart.data.set(bars);

銘柄を切り替えるときも、もう一度 set() を呼ぶだけです。元のローソク足はすべて置き換わります。表示は同じ時間、同じズームのままです。最新の足を見ていたなら新しい最新の足を同じ位置(右端から同じ距離)に、過去を見ていたならチャート右端の時間をそのまま表示します。時間足やチャートタイプの切り替えでも同じです。

ローソク足が決まった時間足なら、時間足も一緒にチャートに伝えておくのがおすすめです。

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

時間足を指定しておくと、チャートはより長い時間足をブラウザ上で合成したり、約定(ティック)をローソク足に反映したりできます。時間足と取引カレンダーを参照してください。

リアルタイム更新

chart.data.update(bar);
chart.data.update([bar1, bar2]); // 複数本をまとめて送る

時間が最後の足と同じならその足を置き換え、それより新しければ後ろに追加し、古ければエラーになります(過去のローソク足には set() か prepend() を使います)。

ユーザーが最新の足を見ているときは、新しい足が来るとチャートも一緒に進みます。ユーザーが過去にさかのぼって見ているときは、チャートは動きません。

約定(ティック)

受け取るのが約定(ティック)なら、そのままチャートに渡します。チャートが現在の足に反映し、次の足の時間になると自動で新しい足を始めます。

chart.data.addTrades({ time: 1767225600123, price: 87601.5, size: 0.02 });
chart.data.addTrades(trades); // まとめて渡す。時間順に並べておく

size は約定数量で、足の出来高に加算されます。デフォルトは 0 です。これには set() で interval を指定しておく必要があります。遅れて届いた約定はスキップされます。最後の足より前のもの、またはすでに渡した最新の約定より前のもので、たとえば再接続のあとに届いたものです。取引セッションを設定している場合、セッション外の約定もスキップされます。addTrades() は実際に使われた約定の件数を返します。side は成行で約定した側です。buy は成行買い(売り注文を取った)、sell は成行売りで、分からなければ省略します。約定から足を作る変換はこれを受け取ります(ローソク足の変換を自分で書くを参照)。

約定数や出来高ごとに作る足(チャートタイプを参照)は約定そのものを使うので、チャートは直近の約定を一定数保持します。保持する数は performance.maxTrades で決まり、デフォルトは 10 万件です。

過去のデータを読み込む

ユーザーが左へドラッグしてローソク足が残り少なくなると、チャートは loadMore イベントを発行します。

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

before は現在の最初の足の時間です。prepend() は古いローソク足を先頭に追加します。既存の足と重なる部分は無視され、実際に追加した本数が返ります。追加して最初の足が変われば、ユーザーがさらに左へドラッグしたときにもう一度発行されます。何も追加されなかった場合は、ユーザーがいったん離れてからまたドラッグして戻ってくるまで発行されません。

残り何本で発行するかは timeScale.loadMoreThreshold で決まり、デフォルトは 20 本です。bars は表示中の足であと何本ほしいかを表します。しきい値に足りない分と、左に空いている分の合計です。カギ足や練行足のように多くの足から 1 本を作る場合は、その分だけ元の足が多く必要なので、ページごとではなく一度に取得してください。

クリア

chart.data.clear();

ローソク足をすべて削除し、進行中のリプレイも終了します。時間足の設定は残ります。

読み取り

chart.data.length; // 表示されるローソク足の本数
chart.data.at(0); // 最初の足。なければ null
chart.data.last(); // 最後の足
chart.data.indexOf(time); // その時間の足が何番目か。なければ -1
chart.data.toArray(); // すべてを配列にコピー

読み出したローソク足の 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 は同じ形のビューで、元の時間足のローソク足を読みます(リプレイ中は現在の足まで)。

ローソク足が変わったとき

表示されるローソク足に何か変化があると(設定、更新、過去データの読み込み、時間足の切り替え、リプレイ)、barsChange が発行されます。

chart.on('barsChange', ({ change }) => {
  if (change.kind === 'tail') {
    // change.from 本目より後ろだけが変わったか、新しい足が追加された
  } else {
    // 'reset':どの足も変わった可能性がある
  }
});

ローソク足をもとに自分で何かを計算するときは、これを使って変わった部分だけを計算し直せます。

ほかのデータを重ねる

メインのローソク足以外のデータ、たとえば比較用の別の銘柄や、自分で計算したラインは、chart.series で重ねて表示します。ペインを参照してください。

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