kline-component

高性能 React K 线（蜡烛图）组件，基于 Canvas 渲染，适用于加密货币/股票/期货等金融行情展示。

零外部图表库依赖，纯 Canvas 2D 实现，支持 7 种技术指标、暗色/亮色双主题、滚轮缩放、拖拽平移、十字光标等交互。

特性

• Canvas 高性能渲染 — 分区布局：主图（K线 + 叠加指标）、成交量、副图指标
• 7 种技术指标 — MA、EMA、BOLL（叠加主图），MACD、RSI、KDJ（独立副图），VOL（均量线）
• 双主题 — 暗色/亮色一键切换，专业交易平台风格
• 丰富交互 — 滚轮缩放、拖拽平移、十字光标、悬停详情面板
• 零依赖 — 除 React 外无任何外部图表库
• TypeScript — 完整类型定义
• Tree-shakeable — ESM 输出，支持按需引入

安装

npm install kline-component

快速开始

import { KLineChart, darkTheme, generateMockKLineData } from 'kline-component';

function App() {
  const data = generateMockKLineData(500);

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <KLineChart
        data={data}
        theme={darkTheme}
        indicators={['MA', 'VOL', 'MACD']}
      />
    </div>
  );
}

Props

| 属性 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | data | KLineData[] | 是 | — | K 线数据数组 | | theme | KLineTheme | 是 | — | 主题对象，使用 darkTheme 或 lightTheme | | indicators | string[] | 否 | ['MA', 'VOL', 'MACD'] | 要显示的指标名称数组 | | className | string | 否 | — | 容器 CSS 类名 | | style | React.CSSProperties | 否 | — | 容器内联样式 |

注意：容器需要有明确的宽高（width + height），组件会自动填满父容器。

数据格式

KLineData 接口定义：

interface KLineData {
  timestamp: number;   // 毫秒级时间戳
  open: number;        // 开盘价
  high: number;        // 最高价
  low: number;         // 最低价
  close: number;       // 收盘价
  volume?: number;     // 成交量（可选）
  turnover?: number;   // 成交额（可选）
}

数据需按 timestamp 升序排列。

Mock 数据

包内提供模拟数据生成器，方便开发调试：

import { generateMockKLineData } from 'kline-component';

// 生成 500 根 BTC/USDT 15 分钟 K 线
const data = generateMockKLineData(500);

指标

内置 7 种技术指标，通过 indicators 属性控制显示：

| 名称 | 类型 | 参数 | 说明 | | --- | --- | --- | --- | | MA | 叠加主图 | [5, 10, 30, 60] | 简单移动平均线 | | EMA | 叠加主图 | [6, 12, 20] | 指数移动平均线 | | BOLL | 叠加主图 | [20, 2] | 布林带 | | MACD | 独立副图 | [12, 26, 9] | 异同移动平均线 | | RSI | 独立副图 | [6, 12, 24] | 相对强弱指数 | | KDJ | 独立副图 | [9, 3, 3] | 随机指标 | | VOL | 成交量区 | [5, 10, 20] | 成交量 + 均量线 |

// 只显示 MA + BOLL
<KLineChart data={data} theme={darkTheme} indicators={['MA', 'BOLL', 'VOL']} />

主题

内置暗色和亮色两套主题：

import { darkTheme, lightTheme } from 'kline-component';

// 暗色主题（推荐，交易平台标配）
<KLineChart data={data} theme={darkTheme} indicators={['MA', 'VOL', 'MACD']} />

// 亮色主题
<KLineChart data={data} theme={lightTheme} indicators={['MA', 'VOL', 'MACD']} />

也支持自定义主题，通过实现 KLineTheme 接口：

import type { KLineTheme } from 'kline-component';

const customTheme: KLineTheme = {
  background: '#0d1117',
  textColor: '#8b949e',
  textFont: '12px -apple-system, sans-serif',
  gridColor: 'rgba(255,255,255,0.04)',
  crosshairColor: 'rgba(255,255,255,0.3)',
  crosshairTextColor: '#e0e0e0',
  crosshairTextBg: 'rgba(30,30,50,0.9)',
  upColor: '#26a69a',
  downColor: '#ef5350',
  upWickColor: '#26a69a',
  downWickColor: '#ef5350',
  maColors: ['#f5c842', '#e86f52', '#636efa', '#00d4aa'],
  bollColors: ['#636efa', '#f5c842', '#636efa'],
  macdDifColor: '#f5c842',
  macdDeaColor: '#e86f52',
  macdBarUpColor: '#26a69a',
  macdBarDownColor: '#ef5350',
  rsiColors: ['#f5c842', '#e86f52', '#636efa'],
  kdjColors: ['#f5c842', '#e86f52', '#636efa'],
  volMaColors: ['#f5c842', '#e86f52', '#636efa'],
};

交互

组件内置以下交互能力，无需额外配置：

• 滚轮缩放 — 鼠标滚轮缩放 K 线，以光标位置为中心
• 拖拽平移 — 鼠标左键按住拖拽查看历史数据
• 十字光标 — 鼠标悬停显示十字准线和价格标签
• 详情面板 — 悬停时在光标附近弹出 OHLCV + 指标值详情

本地开发

# 克隆项目
git clone <repo-url>
cd kline-component

# 安装依赖
npm install

# 构建库
npm run build

# 运行示例
npm run dev

技术栈

• React 18+
• TypeScript
• Canvas 2D
• Vite

License

MIT