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

定位是让 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 种技术指标、完善的交互操作，支持自定义数据源和主题。适用于前端量化看板或交易界面开发。