KLineChart CSV 可视化 Demo — 项目说明书

1. 项目概览

基于 KLineChart v10 的独立 K 线图表可视化 Demo，支持从本地 CSV 文件加载 OHLCV 历史数据，提供周期切换、指标叠加、深浅主题、缩放拖拽、截图导出等完整交互能力。

技术栈：

技术	版本	用途
KLineChart	10.0.2	核心 K 线渲染引擎
Vite	5.x	本地开发服务器
Canvas 2D	原生	图表绘制

2. 文件结构

debug/
├── index.html            # 页面结构：工具栏 + 图表容器
├── main.js               # 全部业务逻辑（约 600 行）
├── style.css             # 界面样式，含深色主题
├── package.json          # 依赖声明（klinecharts + vite）
├── package-lock.json     # 版本锁定
└── data/
    └── eurgbp_m1.csv     # 示例数据（EUR/GBP 1分钟，2021-2026，约 186 万行）

3. 功能清单

功能	操作方式	说明
CSV 加载	📂 按钮选择 / 拖拽	自动识别 5 种 CSV 格式
周期切换	1m / 5m / 15m / 1h / 1d	实时聚合原始 1m 数据
缩放	+/−/⟲ 按钮、鼠标滚轮、键盘 +/−	barSpace 范围 2–50
翻页	←/→ 键盘、拖拽、滚动条	分页加载（每次 500 根）
指标	工具栏按钮 或 右键菜单	MA / BOLL / MACD / RSI / VOL
深色主题	☾/☀ 按钮 或 D 键	chart.setStyles('dark')
截图	▣ 按钮 或 S 键	getConvertPictureUrl() 下载 PNG
十字光标面板	鼠标移动	顶部实时显示 OHLCV + 涨跌幅
柱体详情	左键点击柱体	弹出详细 OHLCV 浮窗
右键菜单	右键图表	切换指标 / 主题 / 截图
自定义指标	registerIndicator()	扩展任意指标

4. CSV 数据格式

自动识别以下格式（列顺序可自定义，支持带表头/无表头）：

格式 A：Binance 格式（时间戳 + OHLCV）

1630000000000,0.00145000,0.00145000,0.00144000,0.00144000,5259702

格式 B：带表头格式

timestamp,open,high,low,close,volume
1630000000000,0.00145000,0.00145000,0.00144000,0.00144000,5259702

格式 C：点号日期格式（当前示例）

2021.07.06,00:10,0.85627,0.85629,0.85625,0.85628,7000000.0

列顺序：日期, 时间, O, H, L, C, V

格式 D：横杠日期格式

2021-07-06,00:10,0.85627,0.85629,0.85625,0.85628,7000000.0

格式 E：YYYYMMDD 格式

20210706,0.85627,0.85629,0.85625,0.85628,7000000.0

时间戳自动处理： 13 位数字 → 毫秒；10 位数字 → 秒（自动 ×1000）

5. 快速开始

cd debug
npm install
npm run dev

浏览器打开 http://localhost:1789，拖入或点击 📂 选择 CSV 文件即可。

6. 核心代码结构（main.js）

┌─────────────────────────────────────┐
│  loadRawCSV(source)                 │  1. 读取文件（File 或 URL）
│    └─ parseCSV(text)                │     2. 自动识别格式，解析到 TypedArray
├─────────────────────────────────────┤
│  aggregateBars(data, range, span)   │  3. 1m → 5m/15m/1h/1d 聚合
├─────────────────────────────────────┤
│  loadDataLoader()                    │  4. 返回 setDataLoader 参数
│    └─ getBars({type, timestamp…})   │     5. init/forward/backward 分页
├─────────────────────────────────────┤
│  mountChart(source)                  │  6. init → setSymbol → setPeriod
│    ├─ chart.setDataLoader(...)      │     7. setDataLoader → 图表加载数据
│    ├─ chart.createIndicator(...)    │     8. 创建指标
│    └─ subscribeAction(...)          │     9. 绑定 crosshair/click 事件
└─────────────────────────────────────┘

7. 自定义指标开发

7.1 注册指标

在 init() 调用之前注册：

import { registerIndicator, init } from 'klinecharts'

registerIndicator({
  name: 'MYAVG',
  shortName: 'MYAVG',
  series: 'price',
  calcParams: [5, 10, 20],
  precision: 5,
  shouldOhlc: true,
  figures: [
    { key: 'a1', title: 'A5: ', type: 'line' },
    { key: 'a2', title: 'A10: ', type: 'line' },
    { key: 'a3', title: 'A20: ', type: 'line' }
  ],
  regenerateFigures: (params) =>
    params.map((p, i) => ({ key: `a${i+1}`, title: `A${p}: `, type: 'line' })),
  calc: (dataList, indicator) => {
    const sums = indicator.calcParams.map(() => 0)
    return dataList.map((bar, i) => {
      const out = {}
      indicator.calcParams.forEach((p, idx) => {
        sums[idx] += bar.close
        if (i >= p - 1) out[`a${idx+1}`] = sums[idx] / (i + 1)
      })
      return out
    })
  }
})

// 注册后再 init
const chart = init('chart', { /* options */ })
chart.createIndicator({ name: 'MYAVG', paneId: 'new' })

7.2 字段说明

字段	必需	类型	说明
name	是	string	唯一标识，用于 createIndicator({ name }) 匹配
shortName	是	string	工具提示中显示的简称
series	是	'price' | 'volume' | 'normal'	系列类型，决定 Y 轴行为
calcParams	否	number[]	计算参数，可被 overrideIndicator 修改
precision	否	number	结果数值的小数位数
shouldOhlc	否	boolean	计算是否需要 OHLC 字段
figures	是	Figure[]	图形配置，定义画几条线/柱
calc	是	() => D[]	核心计算函数
minValue / maxValue	否	number	固定 Y 轴最小/最大值
styles	否	Partial<IndicatorStyle>	覆盖默认配色

7.3 Figure 类型

type	说明
line	折线
bar	柱状图（支持 baseValue: 0 画零轴柱）
circle	圆点
text	文字标注

每个 figure 至少需要 key 和 type，key 对应 calc 返回数据中的字段名。

7.4 计算函数约定

calc: (dataList: KLineData[], indicator) => D[]

• dataList 是当前可见窗口内的 K 线数据（每根含 timestamp/open/high/low/close/volume）
• 返回数组长度等于 dataList 长度
• 每项为对象，键名与 figures[].key 对应
• 数据不足时某键可省略（不会画该点），例如 EMA 前 N 个点

8. KLineChart v10 API 速查

8.1 图表生命周期

方法	说明
init(container, options?)	创建图表实例
dispose(container)	销毁，释放资源
setSymbol({ ticker, pricePrecision, volumePrecision })	设置交易品种信息
setPeriod({ span, type })	设置周期，会触发数据重载
setDataLoader(loader)	设置数据加载器
resetData()	强制重新加载数据

调用顺序： init → setSymbol → setPeriod → setDataLoader

8.2 指标

方法	说明
createIndicator(name, isStack?)	添加指标，isStack=true 叠加主图
createIndicator({ name, paneId: 'new' })	新建独立面板
createIndicator({ name, paneId: 'candle_pane' }, true)	叠加主图
removeIndicator({ name })	移除指标
overrideIndicator({ id, calcParams: [...] })	修改指标参数
registerIndicator(template)	注册自定义指标（需 init 前调用）
getSupportedIndicators()	获取内置指标名列表

8.3 样式与布局

方法	说明
setStyles('dark' | 'light' | partial)	切换主题或局部修改样式
setBarSpace(value)	设置柱间距（等同于缩放）
getBarSpace()	获取当前 barSpace {bar, gapBar}
setPaneOptions({ paneId, height })	设置面板高度
scrollToRealTime()	滚动到最新数据
scrollByDistance(dist)	按像素距离滚动

8.4 事件订阅

Action 类型	触发时机	回调参数
onCrosshairChange	鼠标移动	{ x, y, paneId, kLineData, timestamp, dataIndex }
onCandleBarClick	点击柱体	同上
onZoom	滚轮缩放	barSpace
onScroll	拖动翻页	—
onVisibleRangeChange	可见范围变化	起始/结束索引
onPaneDrag	面板高度拖拽	paneId, height

8.5 截图与导出

const url = chart.getConvertPictureUrl(
  false,   // 是否包含叠加层
  'png',   // 'png' | 'jpeg' | 'bmp'
  '#ffffff' // 背景色
)

9. 内置指标一览

指标	叠加/独立	说明
MA	叠加	简单移动平均，参数默认 6/12/20
EMA	独立	指数移动平均
BOLL	叠加	布林带
MACD	独立	异同移动平均
RSI	独立	相对强弱指数
SAR	独立	抛物线转向
BBI	叠加	多空指标
SMA	叠加	简易平均线
VOL	独立	成交量

10. 扩展场景

10.1 接入后端 API

替换 loadRawCSV() 中的 fetch('/data/eurgbp_m1.csv') 为后端接口：

function loadRawCSV(source) {
  return fetch('/api/kline?symbol=BTCUSDT&limit=1000')
    .then(r => r.json())
    .then(rows => {
      // rows 格式: [{t: 1630000000000, o: ..., h: ..., l: ..., c: ..., v: ...}]
      // 转换为内部格式 {ts, o, h, l, c, v, len}
      const count = rows.length
      return {
        ts: new Float64Array(rows.map(r => r.t)),
        o:  new Float64Array(rows.map(r => r.o)),
        h:  new Float64Array(rows.map(r => r.h)),
        l:  new Float64Array(rows.map(r => r.l)),
        c:  new Float64Array(rows.map(r => r.c)),
        v:  new Float64Array(rows.map(r => r.v || 0)),
        len: count
      }
    })
}

getBars 中的 forward/backward 分页自动交给后端处理。

10.2 WebSocket 实时推送

chart.setDataLoader({
  getBars: ({ type, timestamp, period, callback }) => { /* REST 历史 */ },
  subscribeBar: ({ symbol, period, callback }) => {
    ws = new WebSocket(`wss://.../ws?symbol=${symbol}`)
    ws.onmessage = (evt) => {
      const bar = JSON.parse(evt.data)
      // 回调单根 K 线，相同 timestamp 更新最后根
      callback(bar)
    }
  },
  unsubscribeBar: () => { ws.close() }
})

10.3 多图表联动

const chart1 = init('chart1')
const chart2 = init('chart2')

chart1.subscribeAction('onCrosshairChange', (crosshair) => {
  // 通过 executeAction 同步到另一图表
  chart2.executeAction('onCrosshairChange', { x: crosshair.x, y: null })
})

11. 故障排查

现象	可能原因	解决方法
图表空白	调用顺序不对	确认 init → setSymbol → setPeriod → setDataLoader
无数据	getBars 未调用 callback	确保 callback 一定被调用（即使失败）
时间错乱	时间戳单位错误	确认 timestamp 为毫秒
分页失败	more 标记错误	检查 { forward, backward } 返回值
指标不显示	name 不匹配	createIndicator 的 name 必须等于注册时的 name
滚动条消失	data 太少	数据量 < 2 不会显示滚动条
深色/浅色切换失败	样式名拼写错误	使用 'dark' / 'light'