klinecharts

KLineChart 統合ガイド

KLineChart（npm：klinecharts、現在 v10）をプロジェクトに統合する方法を開発者向けに説明します。

シナリオから選ぶ

ユーザーのニーズ	こちらから始める
初めての統合、簡単なチャート	→ 最小限の例
実際のバックエンド（REST/WebSocket）	→ データの読み込み
React / Vue / その他のフレームワーク	→ フレームワークとの統合
インジケーター／描画ツール	→ インジケーターとオーバーレイ
v9 からのアップグレード	→ v9 → v10 の移行
チャートが空白／データが更新されない	→ トラブルシューティング

バージョンが不明な場合は、package.json の klinecharts を確認してください。v10 では applyNewData / updateData は使用されなくなりました。

最小限の例

import { init, dispose } from 'klinecharts'

const chart = init('chart') // HTMLElement or id; container needs width and height
chart.setSymbol({ ticker: 'BTCUSDT', pricePrecision: 2, volumePrecision: 0 })
chart.setPeriod({ span: 1, type: 'day' })
chart.setDataLoader({
  getBars: ({ callback }) => {
    callback([
      { timestamp: 1517846400000, open: 7424.6, high: 7511.3, low: 6032.3, close: 7310.1, volume: 224461 },
    ])
  }
})
// cleanup: dispose('chart')

必須の順序： init → setSymbol → setPeriod → setDataLoader

データモデル

// KLineData — all price/volume fields must be numbers
{ timestamp: number, open: number, high: number, low: number, close: number, volume?: number, turnover?: number }

// Period
{ span: 5, type: 'minute' }  // 5-minute bars; type: second | minute | hour | day | week | month | year

// SymbolInfo
{ ticker: string, pricePrecision: number, volumePrecision: number }

timestamp はミリ秒単位で指定する必要があります。turnover が必要なのは EMV と AVP のインジケーターのみです。

データの読み込み（setDataLoader）

v10 では従来のデータ API の代わりに setDataLoader を使用します。getBars は async にできますが、必ず callback を呼び出してください。

chart.setDataLoader({
  getBars: ({ type, timestamp, symbol, period, callback }) => {
    // type: 'init' | 'forward' | 'backward'
    // init: first load, timestamp = null
    // forward: scrolled to left edge, timestamp = leftmost bar time
    // backward: scrolled to right edge, timestamp = rightmost bar time
    callback(bars, { forward: true, backward: false })
  },
  subscribeBar: ({ symbol, period, callback }) => {
    // fires after init; call callback with one KLineData per push
    // same timestamp → update last bar; larger timestamp → append
  },
  unsubscribeBar: ({ symbol, period }) => {
    // tear down WebSocket/polling on symbol/period change or dispose
  }
})

ルール：

• 失敗時も含め、必ず getBars から callback を呼び出してください（[] を渡します）
• バーは timestamp の昇順に並べ、重複させないでください
• subscribeBar は配列ではなく、1回に1つのバーを送信します
• more はページネーションを制御します。値は boolean または { forward?, backward? } です

期間またはシンボルを変更すると、chart.setPeriod(...) または chart.setSymbol(...) によって自動的に再読み込みされます。

フレームワークとの統合

コンテナーには明示的な幅と高さが必要です。マウント時に init、アンマウント時に dispose を呼び出し、サイズ変更時には chart.resize() を呼び出してください。

// React pattern
useEffect(() => {
  const chart = init(containerRef.current!)
  chart.setSymbol({ ticker: 'TEST', pricePrecision: 2, volumePrecision: 0 })
  chart.setPeriod({ span: 1, type: 'day' })
  chart.setDataLoader(loader)
  const ro = new ResizeObserver(() => chart.resize())
  ro.observe(containerRef.current!)
  return () => { ro.disconnect(); dispose(containerRef.current!) }
}, [])

CDN：klinecharts.init(...) / klinecharts.dispose(...)

インジケーターとオーバーレイ

chart.createIndicator('MACD')  // separate pane
chart.createIndicator({ name: 'MA', paneId: 'candle_pane' }, true)  // stack on main chart

chart.createOverlay('segment')  // interactive drawing
chart.createOverlay({ name: 'priceLine', points: [{ timestamp, value }] })  // programmatic

メインチャートに重ねて表示できる組み込みインジケーター：BBI、BOLL、EMA、MA、SAR、SMA

実行時の検索：getSupportedIndicators() / getSupportedOverlays()

カスタムタイプ：registerIndicator(...) / registerOverlay(...) — init の前に登録してください。

主なインスタンス API

メソッド	用途
setStyles(partial)	スタイルを更新します（浅いマージ）
setLayoutOptions(partial)	以降に作成されるペインと Y 軸のデフォルトを更新します
getLayoutOptions()	現在のデフォルトのレイアウトオプション全体を取得します
setPaneOptions(opts)	ペインの高さ／状態
overrideYAxis(opts)	Y 軸の位置／目盛り
subscribeAction(type, cb)	クロスヘア、クリックなど
scrollToRealTime()	最新のバーまでスクロールします
getDataList()	現在のバーのデータ
resetData()	データを再読み込みします
getConvertPictureUrl()	画像をエクスポートします

アクションタイプ：onCrosshairChange、onCandleBarClick、onZoom、onScroll、onVisibleRangeChange、onPaneDrag

初期レイアウト

init(container, {
  layout: {
    barSpaceLimit: { min: 2, max: 40 },
    pane: { minHeight: 120 },
    yAxis: { position: 'right' }
  },
  locale: 'zh-CN',
  timezone: 'Asia/Shanghai',
  styles: 'dark'
})

初期化後にレイアウトのデフォルトを変更するには、setLayoutOptions(partial) を使用します。設定は段階的にマージされ、その後に作成されるペインと Y 軸にのみ適用されます。既存のチャート要素には setPaneOptions、overrideYAxis、または overrideXAxis を使用してください。現在のデフォルト全体を読み取るには、getLayoutOptions() を使用します。

v9 → v10 の移行

v9（削除）	v10
applyNewData(data)	type が 'init' の getBars
updateData(bar)	subscribeBar コールバック
applyMoreData(data, more)	'forward' / 'backward' の getBars
setLoadDataCallback	setDataLoader
setPriceVolumePrecision	setSymbol({ pricePrecision, volumePrecision })
setCustomApi	setFormatter
インジケーターの calc が配列を返す	calc が Record<timestamp, value> を返す

トラブルシューティング

1. データがありません — setSymbol/setPeriod/setDataLoader の順に呼び出しましたか？getBars はコールバックを呼び出しましたか？タイムスタンプの単位はミリ秒ですか？
2. ページネーションが機能しません — コールバック内の more.forward / more.backward は正しいですか？
3. リアルタイムで更新されません — subscribeBar はバーを 1 つプッシュしていますか？タイムスタンプは最後のバー以上ですか？
4. シンボルの切り替え後に古いデータが残ります — unsubscribeBar は古いサブスクリプションを閉じていますか？
5. コンテナーが空白です — 幅／高さが 0 になっていませんか？resize は呼び出しましたか？

関連資料

• コピーして使えるプロンプト：prompts.md
• 完全なサンプル：examples.md
• API リファレンス：api-reference.md
• 公式ドキュメント：https://klinecharts.com/guide/data-integration