Kumo Charts

描画ツール

drawingTools は描画ツールバーに置くツールを選び、その順序を決めます。ツールはグループごとにまとめられ(ライン、フィボナッチ・ギャン、パターン、予測・計測、図形・ブラシ、テキスト・注釈)、各グループの位置はリストでの最初のツールの位置で決まり、グループ内のツールはリストの順に並びます。ツールのないグループは表示しません。

チャートの高さが足りず描画ツールバーに収まらないときは、ツールを上下にスクロールでき(ホイール、タッチパッド)、まだツールがある側には小さな矢印が出て、クリックすると少しスクロールします。各グループの右下の小さな三角でそのグループのツール一覧が開きます。見た目はチャートタイプのメニューと同じで、同じ種類のツールがまとまり、種類のあいだに区切り線があります(たとえばライングループはライン、チャネル、ピッチフォークの 3 種類に分かれます)。各行はツールのアイコンと名前で、行末にそのキーボードショートカット、さらにその後ろに星印があります。星印を付けたものは常に表示し、付けていないものはマウスを乗せた行にだけ出ます。キーボードでも操作できます:Enter で開き、上下キーで選び(端まで行くと反対側に戻る)、Enter で選択して小さな三角に戻り、Tab で星印へ移動でき、Esc で閉じて小さな三角に戻ります。

星印を付けたツールは、チャート領域の上にあるお気に入り描画ツールのバーに(描画ツールバーの順で)表示され、1 回クリックするとそのツールを使い、もう 1 回クリックすると手放します。左側のつまみをつかむとチャート領域のどこへでもドラッグでき、つまみをダブルクリックすると元の位置(上部中央)に戻ります。描画ツールバーの下にある星形のボタンはこのバーの表示・非表示を切り替え、新しいツールに星印を付けると自動的に表示されます。星印を付けたツールがないとこのバーは表示されず、星形のボタンを押すとお気に入りへの追加方法を案内します。星印を付けたツール、バーの位置、表示するかどうかはレイアウトに属します。1 つのレイアウトの複数のチャートで共有され、レイアウトの最初のチャートの状態(ChartView)の favoriteDrawingTools、favoriteToolsBar、favoriteToolsShown に保存されるので、どのチャートで星印を付けたり動かしたりしても、レイアウト内のチャートはすべて同じになります。リプレイの操作ウィンドウの位置 replayWindow と、選択した描画のフローティングツールバーの位置 drawingBar も同じです。マルチチャートレイアウトでは、フローティングツールバーはチャート領域全体で 1 つだけで、現在のチャートで選択した描画についていき、別のチャートで描画をクリックすると、ほかのチャートで選択していた描画は選択が外れます。別の場所へドラッグするとそこにとどまり、位置はチャート領域全体に対する比率で保存されます。つまみをダブルクリックすると描画の横に戻ります。メソッドは setFavoriteDrawingTools(types) で、現在のチャートがあるレイアウトに対して働きます。トップバーのお気に入りの時間足、チャートタイプ、インジケーターはワークスペース全体で共有されます。

描画ツールバーは上から下へいくつかの区画に分かれ、区画のあいだに区切り線があります:カーソル。描画ツールの各グループ。マグネットと連続描画。ページ独自のボタン。お気に入り描画ツールの星形のボタン、描画を非表示、描画を削除は描画ツールバーのいちばん下に固定され、上のツールをスクロールしても動きません。ツールのアイコンの描き方は統一されています。ユーザーが点を置く位置に小さな円(アンカー)を描き、線はアンカーのあいだに描きます。外へ延びる線はアイコンの端まで描くので、トレンドライン(2 つのアンカーのあいだ)、レイ(2 つ目のアンカーを通って片側へ延びる)、延長線(両側へ延びる)がひと目で見分けられます。アイコンは描画ツールバーでは 22 ピクセル、メニューでは 20 ピクセルで、すべてのアイコンの線は大きさにかかわらず 1 ピクセル幅です。チャートタイプにもそれぞれアイコンがあり、陰線やエリアのような部分は塗りつぶしか淡い色で埋めています。

drawingTools: ['horizontal-line', 'trend-line', 'rectangle', 'fib-retracement', 'text'];

ツール(全 52 種類、描画ツールバーの順):

  • ライン:trend-line(トレンドライン)、ray(レイ)、extended-line(延長線)、trend-angle(トレンド角度)、info-line(情報ライン)、horizontal-line(水平線)、horizontal-ray(水平レイ)、vertical-line(垂直線)、cross-line(十字線)、parallel-channel(平行チャネル)、regression-trend(回帰トレンド)、pitchfork(ピッチフォーク)、schiff-pitchfork(シフ・ピッチフォーク)、modified-schiff-pitchfork(修正シフ・ピッチフォーク)
  • フィボナッチ・ギャン:fib-retracement(フィボナッチ・リトレースメント)、fib-extension(フィボナッチ・エクステンション)、fib-channel(フィボナッチ・チャネル)、fib-time-zone(フィボナッチ・タイムゾーン)、fib-speed-fan(フィボナッチ・ファン)、gann-box(ギャン・ボックス)、gann-fan(ギャン・ファン)、cyclic-lines(サイクルライン)
  • パターン:xabcd-pattern(XABCDパターン)、abcd-pattern(ABCDパターン)、head-and-shoulders(ヘッド・アンド・ショルダー)、elliott-impulse(エリオット推進波 12345)、elliott-correction(エリオット修正波 ABC)、elliott-triangle(エリオット・トライアングル ABCDE)、elliott-double-combo(エリオット・ダブルコンビネーション WXY)、elliott-triple-combo(エリオット・トリプルコンビネーション WXYXZ)
  • 予測・計測:long-position(ロングポジション)、short-position(ショートポジション)、anchored-vwap(アンカーVWAP)、fixed-range-volume-profile(価格帯別出来高(固定範囲))、price-range(価格範囲)、date-range(日付範囲)、date-price-range(日付と価格の範囲)
  • 図形・ブラシ:brush(ブラシ。押したままドラッグして手描き)、highlighter(蛍光ペン。押したままドラッグし、太く半透明)、arrow(矢印)、rectangle(長方形)、rotated-rectangle(回転長方形。2 点を結ぶ中心線に沿って、両側に同じ幅。両端の中点と 4 つの角のどれもドラッグできる)、path(パス)、circle(正円)、ellipse(楕円。斜めにも描ける)、triangle(三角形)
  • テキスト・注釈:text(テキスト)、callout(吹き出し)、price-label(価格ラベル)、flag-mark(旗マーク)、arrow-mark-up(上矢印)、arrow-mark-down(下矢印)

指定しなければすべてのツールが入り、ページ独自のツール(customDrawings)はそれぞれ after で指定したツールの後ろに、after のないものはそのグループの最後に置かれます。リストを指定したときは、ページ独自のツールもリストに(その type を)書いたときだけ現れます。リストにない組み込みのツールは隠れるので、たとえばページが独自のツールでフィボナッチ・リトレースメントを置き換えるなら、リストから fib-retracement を外して独自のものを入れます。drawingToolTypes(customDrawings) はリストを指定しないときのすべてのツールを(描画ツールバーの順で)返すので、そこから不要なものを除くのがいちばん手軽です。DRAWING_GROUP_IDS は各グループの名前で、lines、fibonacci、patterns、measure、shapes、annotation です。隠したツールですでにチャートに描かれている描画はそのまま表示され、選択も変更もできます。描画ツールバーにそのツールがないので、新しく描けないだけです。

const tools = drawingToolTypes([RULER]).filter((type) => type !== 'fib-retracement');
chart.applyOptions({ drawingTools: tools }); // 独自の定規でフィボナッチ・リトレースメントを置き換える
chart.applyOptions({ drawingTools: null }); // すべてに戻す

描画をまるごと外すには features: { drawings: false } を使います。

目盛り:レベルをどちらの端から数えるか

フィボナッチ・リトレースメント、エクステンション、チャネル、ファン、ギャン・ボックスのようなレベルのあるツールは、アンカーごとに値を持ち、レベルはこの 2 つの値で数えます。値はスタイルの levelRange(時間方向のレベルは timeLevelRange)に保存され、デフォルトは { start: 1, end: 0 } です。最初のアンカーが 1、2 つ目が 0 で、レベル 0.618 は 2 つ目のアンカーから全長の 0.618 倍の位置です。設定ウィンドウの「目盛り」では、デフォルト、反転({ start: 0, end: 1 })、倍数(R)({ start: 0, end: -1 }:最初のアンカーが 0 で、2 つ目のアンカー側がマイナス、反対側が 1、2、3……。たとえばエントリー価格からストップ価格へドラッグすれば、1 がちょうど 1R)、カスタム(2 つのアンカーにそれぞれ値を書く)を選べます。レベルの文字(levelLabel)には接頭辞と接尾辞を付けられ、たとえば接尾辞に R と書くと 2R と表示します。

ページは drawingStyles でツールにスタイルを与え、そのツールのデフォルトにできます。ユーザーが新しく描くときにそれを使い、ユーザーが自分で変えたスタイルはその上にかぶさり、設定ウィンドウの「スタイルをリセット」でそれに戻ります。スタイルの書き間違い(存在しないフィールド、範囲外の線の太さなど)はエラーになり、チャートライブラリの checkDrawingStyle() と同じように検査します。表示したあとでも applyOptions で変えられます:

chart.applyOptions({
  drawingStyles: {
    'fib-retracement': {
      levelRange: { start: 0, end: -1 },
      levelLabel: { level: true, format: 'ratio', prefix: '', suffix: 'R', price: true }
    }
  }
});

これらのツールの描き方、デフォルトのレベルとラベル:フィボナッチ・リトレースメントは 24 レベルあり、デフォルトで 0、0.236、0.382、0.5、0.618、0.786、1、1.618、2.618、3.618、4.236 を表示し、残りの 13 レベル(1.272、1.414、2、2.272……4.764)は設定ウィンドウでオンにします。フィボナッチ・タイムゾーンは 0、1、2、3、5、8、13……単位のところに縦線を引きます。フィボナッチ・ファンとギャン・ボックスの価格レベルと時間レベルはデフォルトで 0、0.25、0.382、0.5、0.618、0.75、1 です。回帰トレンドは 2 つのアンカーのあいだの各足の終値で線形回帰を行い、上下に標準偏差 2 倍のラインを 1 本ずつ引き、ピアソンの相関係数を表示します。アンカーVWAP はアンカーの足から計算し(デフォルトは (高値 + 安値 + 終値) / 3)、標準偏差 1 倍のバンドを伴います。エリオット波動はディグリーごとにラベルを付け、デフォルトはインターミディエイトの (1)……(5)、(A)(B)(C) です。ヘッド・アンド・ショルダーの「左肩・頭・右肩」は画面の言語で表示します。エリオット・トライアングルは A から E、コンビネーションは W、X、Y(トリプルはさらに X、Z)とラベルを付けます。情報ラインは線分の中央の横の枠に、値動きと率、足の本数と期間、角度を書きます。シフ・ピッチフォークの中央線は柄の半分の高さから始まり(修正版は時間でも半分を取る)、急すぎるトレンドに向きます。ギャン・ファンは最初のアンカーから 8×1 から 1×8 の角度でレイを引き、1×1 は 2 つ目のアンカーを通ります。どのラインにもアラートを設定できます。サイクルラインは 2 つのアンカーの間隔で右へずっと縦線を引きます。ABCDパターンは BC と CD のリトレースメント比率を表示します。上矢印と下矢印は上昇と下落の色を使い、一言テキストを添えられます。回帰トレンドとアンカーVWAP は足から計算するので、意味があるのはアンカーの時間だけで、ハンドルはライン上にあり、左右にしかドラッグできません。

描画の設定ウィンドウは、ツールごとに設定できる項目を表示します。トレンドラインには延長、矢印、テキスト、長方形には塗りつぶし、延長、枠内のテキスト、チャネルには塗りつぶしと延長、フィボナッチには各レベル、ギャン・ボックスとフィボナッチ・ファンには価格レベルと時間レベル、ギャン・ファンには各角度(価格/時間で、2 は 2×1)、蛍光ペンには 6〜20 ピクセルの線の太さ、回帰トレンドには計算に使う価格と偏差(デフォルトは標準偏差の +2、0、−2 倍)、アンカーVWAP には計算に使う価格とバンド、フィボナッチ・タイムゾーンには倍数としての各レベル(レベルを追加するとフィボナッチ数列の続きになる)、エリオット波動にはディグリー、価格ラベルとパターンにはラベルの色と文字サイズ、正円と楕円には枠内のテキスト、テキストと吹き出しには背景があります。水平線は価格の座標だけ、垂直線は時間の座標だけ、回帰トレンドとアンカーVWAP は時間の座標だけを持ちます。ユーザーがツールバーや設定ウィンドウでスタイルを変えると、そのツールでそれ以降に描く描画はそのスタイルを使い、状態の drawingStyles に保存されます。設定ウィンドウの「スタイルをリセット」は、その描画とそのツールの両方をデフォルトに戻します。

2 つのバーを変える:フローティングバーと描画ツールバー

描画を選択したときに浮かぶバー(色や線の太さの変更、ロック、削除)に何をどの順で置くかは drawingBarItems で決めます。リストには 3 種類のものを書けます:

  • 組み込みの項目(DRAWING_BAR_PARTS):color、lineWidth、lineStyle、separator(区切り線。何度でも書ける)、text(テキストを書く)、settings、duplicate、lock、remove。
  • スタイルの切り替え { field }:描画のスタイルにある切り替えをボタンにします。1 回押すとオン、もう 1 回押すとオフで、変更は設定ウィンドウで変えたのと同じです(元に戻せて、そのツールのデフォルトにもなります)。使える切り替えは DRAWING_BAR_SWITCHES にあり、fill、bold、italic、extendLeft、extendRight、startArrow、endArrow です。さらに label(ツールチップの文言)と icon を渡してデフォルトのものと替えられます。
  • ページ独自のボタン { id, label, icon, types? }:クリックするとその描画を添えて drawingBarClick イベントが発火します。types を書くと、その種類の描画にだけ出ます。

各項目はその描画で使えるときだけ現れます。トレンドラインには extendRight がありますが長方形にはないので、長方形のフローティングバーにはこのボタンが出ません。両端や連続する区切り線は自動的に取り除かれます。drawingBarItems を渡さなければ、組み込みの項目がすべて入ります。

const chart = createProChart(container, {
  datafeed,
  symbol: 'BTCUSDT',
  drawingBarItems: [
    'color',
    'lineWidth',
    'lineStyle',
    'separator',
    { field: 'extendRight' }, // 「右に延長」をフローティングバーに置く
    { field: 'extendLeft' },
    'separator',
    { id: 'share', label: { en: 'Share', zh: '分享' }, icon: 'M12 5v10M8 9l4-4 4 4M5 19h14' },
    'settings',
    'lock',
    'remove'
  ]
});

chart.on('drawingBarClick', ({ id, symbol, drawing }) => {
  if (id === 'share') {
    share(symbol, drawing); // drawing はその描画:id、type、points、style……
  }
});

左側の描画ツールバーにあるツール以外のボタンのうちどれを残すかは drawingToolbarControls(DRAWING_TOOLBAR_CONTROLS)で決めます:cursor(クロスヘア)、magnet(マグネット)、continuous(連続描画)、favorites(お気に入りツールのバー)、hide(描画を非表示)、clear(すべて削除)。並べたものだけが表示され、位置は変わりません。ツール自体は drawingTools が管理し、ページ独自のボタンは「独自のボタン」を参照してください。

chart.applyOptions({ drawingToolbarControls: ['cursor', 'magnet', 'hide'] }); // 連続描画、お気に入り、すべて削除は要らない
chart.applyOptions({ drawingBarItems: null, drawingToolbarControls: null }); // デフォルトに戻す

自前の描画ツールバー:chart.drawingTools

上の 2 つのオプションで足りないときは、組み込みのバーをオフにして、chart.drawingTools で自分で作れます。組み込みの 2 つのバーが読むもの、行うことはすべてここにあり、どのフレームワークで書いても構いません。

const chart = createProChart(container, {
  datafeed,
  symbol: 'BTCUSDT',
  features: { drawingToolbar: false, drawingBar: false } // 組み込みの描画ツールバーとフローティングバーをオフにする。描画機能はそのまま
});

2 つの切り替えは片方だけオフにもできます。どちらもオフにしなくても chart.drawingTools は使え、たとえばページの別の場所によく使うツールのボタンをいくつか置けます。

メソッド 説明
list() 現在提供しているツール。描画ツールバーのグループと順序で:[{ id, name, tools: [{ type, name, icon, keys }] }]。名前は現在の言語で、icon は 24×24 のグリッド上の SVG パス、keys はそのキーボードショートカットです
getState() { active, magnet, continuous, hidden, favorites, favoritesShown }:使用中のツール(なければ null)、マグネット(off、weak、strong)、連続描画、描画を隠しているかどうか、ユーザーがお気に入りにしたツール、お気に入り描画ツールのバーを開いているかどうか
start(type)、cancel() ツールを持つ(次にユーザーがチャートをクリックするとそのツールで描く)、手放す
setMagnet(mode) マグネット
setContinuous(on) 連続描画:1 本描き終えたら続けて次を描く
setHidden(hidden) すべての描画を隠す・表示する
setFavoritesShown(shown) お気に入り描画ツールのバーを開く・閉じる。描画ツールバーの下の星形のボタンと同じで、開いていてもお気に入りのツールがあるときだけ表示します
clear() 現在のチャートのすべての描画を削除します。1 ステップで元に戻せます
undo()、redo() 現在のチャートの描画に対する直前の変更を元に戻す・やり直す
getSelected() 現在のチャートで選択している描画:{ chart, symbol, drawing, style, fields, editableText, bounds }。なければ null
select(id, target?) 描画を選択します。クリックするのと同じです。null で選択を外します
duplicate(id, target?) 描画を複製し、複製したものを選択して、その id を返します
openSettings(id, target?) その描画の設定ウィンドウを開きます

描画の変更には「メソッドで描画する」の updateDrawing()、removeDrawing() を使います。getSelected() が返す style はその描画が実際に使っているスタイル(自分で変えたものがそのツールのデフォルトの上にかぶさったもの)、fields はその種類の描画が持つスタイル項目(lineWidth のない描画では線の太さを表示すべきではありません)、editableText はテキストを書けるかどうか、bounds はウィンドウ内での位置(getBoundingClientRect() と同じ座標)で、表示範囲にないときは null です。

お気に入り描画ツールのバーは drawingToolbar と一緒にはオフになりません。ユーザーがツールをお気に入りにしていれば、これまで通りチャート上に浮かびます。ページ独自の描画ツールバーからは setFavoritesShown() で開閉するか、オフにして getState().favorites をもとにお気に入りのツールを自分で表示します。

状態が変わると 3 つのイベントが発火します:drawingToolChange(内容は getState() と同じ)、drawingSelectionChange({ selected }。選択が替わったとき、選択を外したとき、選択中の描画が変わったときに発火)、drawingBoundsChange({ chart, id, bounds }。選択中の描画がウィンドウ内で動いたとき。チャートのスクロール、拡大縮小、描画のドラッグで起きます。ページがリッスンしているときだけ毎フレーム測ります)。

// 自前の描画ツールバー:ツールを並べ、クリックで持ち、使用中のものを強調する。
const groups = await chart.drawingTools.list();
toolbar.render(groups, (type) => chart.drawingTools.start(type));
chart.on('drawingToolChange', ({ active, magnet }) => {
  toolbar.highlight(active);
  toolbar.showMagnet(magnet);
});

// 自前のフローティングバー:選択中の描画についていき、その描画にあるスタイル項目のボタンを出す。
chart.on('drawingSelectionChange', ({ selected }) => {
  if (!selected) {
    bar.hide();
    return;
  }

  bar.show({
    color: selected.fields.includes('color') ? selected.style.color : null,
    extendRight: selected.fields.includes('extendRight') ? selected.style.extendRight : null,
    onColor: (color) => chart.updateDrawing(selected.drawing.id, { style: { color } }),
    onRemove: () => chart.removeDrawing(selected.drawing.id)
  });
});
chart.on('drawingBoundsChange', ({ bounds }) => {
  bar.moveTo(bounds); // bounds が null のとき、描画は表示範囲にない
});

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