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 必须以毫秒为单位。只有 EMV 和 AVP 指标需要 turnover。

数据加载（setDataLoader）

v10 使用 setDataLoader，而不是旧版数据 API。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，即使失败也不例外（传入 []）
• K 线按 timestamp 升序排列，且不得重复
• subscribeBar 每次推送一根 K 线，而不是数组
• 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()	滚动到最新 K 线
getDataList()	当前 K 线数据
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)	getBars，类型为 'init'
updateData(bar)	subscribeBar 回调
applyMoreData(data, more)	getBars，类型为 'forward' / 'backward'
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 是否推送了一根 K 线？时间戳是否 ≥ 最新一根 K 线的时间戳？
4. 切换交易品种后数据过期——unsubscribeBar 是否关闭了旧订阅？
5. 容器空白——宽度/高度是否为 0？是否调用了 resize？

延伸阅读

• 可直接复制的提示词：prompts.md
• 完整示例：examples.md
• API 参考：api-reference.md
• 官方文档：https://klinecharts.com/guide/data-integration