React K 线图组件 kline-charts-react 功能与使用

一个基于 Props 即可绘制专业 K 线图的组件，数据获取和指标计算全自动。

背景与动机

需求是在 React 项目中集成股票 K 线图，要求支持周期切换、指标查看及缩放拖拽。现有方案如 TradingView 的 Lightweight Charts 免费版功能受限且非 React 组件，npm 上搜索 "react kline" 的结果多为年久失修或 Demo 级别产品。因此决定自行开发通用组件并开源。

项目概览

项目名为 kline-charts-react，采用 MIT 协议开源。

K 线图示例

快速开始

import { KLineChart } from 'kline-charts-react';
import 'kline-charts-react/style.css';

function App() {
  return <KLineChart symbol="sh600519" height={600} />;
}

传入股票代码，组件会自动拉取数据、计算技术指标并渲染完整的 K 线图。

核心功能

对标主流金融交互，主要功能包括：

周期全覆盖：支持分时、五日分时、日 K、周 K、月 K，以及 1/5/15/30/60 分钟线。
15 种技术指标：MA、BOLL、MACD、KDJ、RSI、WR、BIAS、CCI、ATR、OBV、ROC、DMI、SAR、KC，全部前端实时计算。Tooltip 中展示所选指标值。
丰富的交互：鼠标滚轮缩放、拖拽平移、十字准线、数据 Tooltip、缩放历史撤销/重做、全屏模式、导出图片。
主题切换：内置明暗两套主题，支持自定义颜色对象。
复权处理：前复权、后复权、不复权，默认前复权。

数据层设计

前端领域获取股票行情一直存在空白。为此开发了面向前端的股票数据 SDK：stock-sdk。

定位是让 JavaScript/TypeScript 开发者用最简单的方式获取股票行情和 K 线数据。

关键特性：

纯 TS 实现，零外部依赖，压缩后体积不到 20KB
浏览器和 Node.js 通吃，ESM/CJS 双格式
支持 A 股、港股、美股和公募基金，实时行情、历史 K 线都有
内置常用技术指标，MA、MACD、BOLL、KDJ、RSI 等开箱可用
TypeScript 类型齐全，IDE 智能提示

使用示例

import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK();

// 批量获取实时行情
const quotes = await sdk.getSimpleQuotes(['sh600519', 'sz000858']);
quotes.forEach(q => {
  console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
});

// 获取前复权日 K 线
const kline = await sdk.getKline('sh600519', { period: 'daily', adjust: 'qfq' });

kline-charts-react 的数据层由 stock-sdk 驱动。你传入股票代码，stock-sdk 自动去拉行情数据，组件拿到数据后计算指标、构建图表配置、渲染到页面上。全程浏览器端完成，不需要自己搭后端。

如果你有自己的行情接口，组件也支持自定义数据源替换。

渲染引擎选择

图表渲染选用 ECharts。原因包括成熟、稳定、社区大、文档全。K 线图（Candlestick）、折线图、柱状图、散点图等类型 ECharts 均有原生支持，配合 dataZoom、tooltip、axisPointer 等交互组件可大幅减少开发工作。

体积方面，组件内部做了按需注册，只引入实际用到的 chart 和 component。echarts 作为 peerDependency 处理，不会打进组件包里。组件自身构建产物约 77KB（gzip 约 19KB）。

关键设计

1. 简单场景简单用

默认配置下只需传 symbol，开箱即用：

<KLineChart symbol="sh600519" />

需要精细控制时，通过 props 配置：

<KLineChart 
  symbol="sh600519" 
  period="weekly" 
  adjust="qfq" 
  theme="dark" 
  indicators={['ma', 'volume', 'kdj', 'rsi']} 
  indicatorOptions={{ ma: { periods: [5, 10, 20, 60] } }} 
  maxSubPanes={3} 
  height={700} 
/>

2. 数据源替换

内置数据源不满足需求时，传一个 dataProvider 即可替换数据获取逻辑：

const myProvider = {
  getKline: async (params, signal) => {
    const res = await fetch(`/api/kline?symbol=${params.symbol}&period=${params.period}`, { signal });
    return res.json();
  },
  getTimeline: async (params, signal) => {
    const res = await fetch(`/api/timeline?symbol=${params.symbol}`, { signal });
    return res.json();
  },
};

<KLineChart symbol="sh600519" dataProvider={myProvider} />

K 线数据格式为标准 OHLCV（date, open, close, high, low, volume, amount），分时数据为 time, price, volume, amount, avgPrice。只要按此格式返回即可，指标计算交给组件。

3. Ref 方法

组件对外暴露了 ref，方便在组件外部做程序化控制：

const chartRef = useRef<KLineChartRef>(null);
chartRef.current?.refresh(); // 刷新
chartRef.current?.exportImage('png'); // 导出图片
chartRef.current?.setPeriod('weekly'); // 切换周期
chartRef.current?.getEchartsInstance(); // 获取 ECharts 实例

4. 分时自动轮询

看分时时需要持续刷新数据。组件内置定时轮询，可设定仅在开盘时间段内刷新：

<KLineChart 
  symbol="sh600519" 
  period="timeline" 
  autoRefresh={{ intervalMs: 5000, onlyTradingTime: true }} 
/>

安装方式

yarn add kline-charts-react
# 还需要安装 peer dependencies
yarn add react react-dom echarts

echarts 是 peerDependency 而不是 dependency，如果项目中已安装 echarts，不会出现两份 echarts 的情况。

已知限制

移动端触控：桌面端交互已打磨，但移动端的捏合缩放、双指操作尚未专门处理。
导出图片不完整：左上角的指标数值是 React DOM 渲染的，不在 ECharts Canvas 里，导出图片不会包含这部分。
没有 WebSocket：实时数据目前只能通过轮询，后续考虑接入 WebSocket 推送。

结语

这是一个为 React 项目设计的 K 线图组件，传入股票代码即可渲染，内置 stock-sdk 数据源、15 种技术指标、完善的交互操作，支持自定义数据源和主题。适用于前端量化看板或交易界面开发。

React K 线图组件 kline-charts-react 功能与使用