KlineChart_dev/README.md

# 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. 快速开始

```bash
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()` 调用之前注册：

```js
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 计算函数约定

```js
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 截图与导出

```js
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')` 为后端接口：

```js
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 实时推送

```js
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 多图表联动

```js
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'` |