React K 线图组件与股票数据 SDK 实现方案

示例代码：

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.linkdiary.cn

如果自有行情接口，组件也留了口子，支持自定义数据源替换。

渲染层选择 ECharts

图表渲染用的 ECharts。选它的原因比较朴素：成熟、稳定、社区大、文档全。K 线图（Candlestick）、折线图、柱状图、散点图这几种类型 ECharts 都有原生支持。

体积方面做了按需注册，只引入了实际用到的 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 推送