kline-charts-react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kline-charts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# KLine Charts
+
+<p align="center">
+  <strong>📈 专业级股票 K 线图表 React 组件</strong>
+</p>
+
+<p align="center">
+  基于 ECharts，内置 stock-sdk 数据源，开箱即用
+</p>
+
+<p align="center">
+  <a href="#安装">安装</a> •
+  <a href="#快速开始">快速开始</a> •
+  <a href="#功能特性">功能特性</a> •
+  <a href="#api-文档">API 文档</a> •
+  <a href="#主题定制">主题定制</a>
+</p>
+
+---
+
+## 功能特性
+
+- 🚀 **零配置数据** - 内置 stock-sdk，传入股票代码自动获取数据
+- 🔌 **可插拔数据源** - 支持自定义 DataProvider（解决跨域/接入自有行情源/SSR）
+- 🌍 **多市场支持** - A 股、港股、美股
+- 📊 **丰富周期** - 分时、五日、日 K、周 K、月 K、分钟级 K 线
+- 📈 **技术指标** - MA/MACD/BOLL/KDJ/RSI/WR/BIAS/CCI/ATR/OBV/ROC/DMI/SAR/KC
+- 🎯 **交互完善** - 缩放、平移、十字准线、Tooltip、撤销/重做
+- 🖥️ **全屏模式** - 一键全屏展示
+- 🔄 **自动刷新** - 分时模式支持自动刷新数据
+- 🎨 **高度可定制** - 主题、颜色、指标参数均可配置
+- 📱 **响应式设计** - 自适应容器尺寸
+- 📦 **轻量体积** - Tree-shaking 友好，按需引入 ECharts 组件
+
+## 安装
+
+```bash
+npm install kline-charts-react
+
+# 或使用 yarn
+yarn add kline-charts-react
+
+# 或使用 pnpm
+pnpm add kline-charts-react
+```
+
+### Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+## 快速开始
+
+```tsx
+import { KLineChart } from 'kline-charts-react';
+import 'kline-charts-react/style.css';
+
+function App() {
+  return (
+    <KLineChart
+      symbol="sh600519"  // 贵州茅台
+      height={600}
+    />
+  );
+}
+```
+
+## 基础用法
+
+### 切换股票
+
+```tsx
+<KLineChart
+  symbol="sz000001"  // 平安银行
+  market="A"         // A 股（默认）
+/>
+```
+
+### 指定周期
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  period="weekly"  // 周 K 线
+/>
+```
+
+可选周期：`timeline` | `timeline5` | `1` | `5` | `15` | `30` | `60` | `daily` | `weekly` | `monthly`
+
+### 配置技术指标
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  indicators={['ma', 'volume', 'macd', 'kdj']}
+  indicatorOptions={{
+    ma: { periods: [5, 10, 20, 60] },
+    macd: { short: 12, long: 26, signal: 9 },
+  }}
+/>
+```
+
+### 深色主题
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  theme="dark"
+/>
+```
+
+### 自动刷新（分时模式）
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  period="timeline"
+  autoRefresh={{ intervalMs: 5000, onlyTradingTime: true }}
+/>
+```
+
+### 自定义数据源
+
+解决跨域问题或接入自有行情源：
+
+```tsx
+import { KLineChart, type KLineDataProvider } from 'kline-charts-react';
+
+const customProvider: KLineDataProvider = {
+  getKline: async (params, signal) => {
+    const res = await fetch(`/api/kline?symbol=${params.symbol}`, { 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={customProvider}
+/>
+```
+
+### 使用 Ref 控制图表
+
+```tsx
+import { useRef } from 'react';
+import { KLineChart, type KLineChartRef } from 'kline-charts-react';
+
+function App() {
+  const chartRef = useRef<KLineChartRef>(null);
+
+  const handleRefresh = () => {
+    chartRef.current?.refresh();
+  };
+
+  const handleExport = () => {
+    const dataUrl = chartRef.current?.exportImage('png');
+    // 下载图片...
+  };
+
+  return (
+    <>
+      <button onClick={handleRefresh}>刷新</button>
+      <button onClick={handleExport}>导出图片</button>
+      <KLineChart ref={chartRef} symbol="sh600519" />
+    </>
+  );
+}
+```
+
+## API 文档
+
+### KLineChartProps
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `symbol` | `string` | **必填** | 股票代码，如 `sh600519`、`sz000001` |
+| `market` | `'A' \| 'HK' \| 'US'` | `'A'` | 市场类型 |
+| `period` | `PeriodType` | `'daily'` | K 线周期 |
+| `adjust` | `'' \| 'qfq' \| 'hfq'` | `'qfq'` | 复权类型（前复权） |
+| `height` | `number \| string` | `500` | 图表高度 |
+| `width` | `number \| string` | `'100%'` | 图表宽度 |
+| `theme` | `'light' \| 'dark' \| ThemeConfig` | `'light'` | 主题配置 |
+| `indicators` | `IndicatorType[]` | `['ma', 'volume', 'macd']` | 启用的技术指标 |
+| `indicatorOptions` | `IndicatorOptions` | - | 指标参数配置 |
+| `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
+| `showPeriodSelector` | `boolean` | `true` | 是否显示周期切换 |
+| `showIndicatorSelector` | `boolean` | `true` | 是否显示指标切换 |
+| `maxSubPanes` | `number` | `3` | 最多显示几个副图，0 表示不显示副图 |
+| `visibleCount` | `number` | `60` | 初始可见 K 线数量 |
+| `dataProvider` | `KLineDataProvider` | - | 自定义数据源 |
+| `sdkOptions` | `SDKOptions` | - | stock-sdk 配置 |
+| `requestOptions` | `RequestOptions` | - | 请求控制配置 |
+| `autoRefresh` | `boolean \| AutoRefreshOptions` | - | 自动刷新配置 |
+| `echartsOption` | `EChartsOption` | - | 自定义 ECharts 配置 |
+| `onDataLoad` | `(data: KlineData[]) => void` | - | 数据加载回调 |
+| `onPeriodChange` | `(period: PeriodType) => void` | - | 周期切换回调 |
+| `onError` | `(error: Error) => void` | - | 错误回调 |
+
+### KLineChartRef
+
+| 方法 | 说明 |
+|------|------|
+| `refresh()` | 刷新数据 |
+| `setPeriod(period)` | 切换周期 |
+| `setIndicators(indicators)` | 切换指标 |
+| `zoomTo(start, end)` | 缩放到指定范围 |
+| `resetZoom()` | 重置缩放 |
+| `getEchartsInstance()` | 获取 ECharts 实例 |
+| `exportImage(type?)` | 导出图片（png/jpeg） |
+| `getData()` | 获取当前数据 |
+
+### PeriodType
+
+```ts
+type PeriodType =
+  | 'timeline'   // 分时
+  | 'timeline5'  // 五日分时
+  | '1'          // 1分钟
+  | '5'          // 5分钟
+  | '15'         // 15分钟
+  | '30'         // 30分钟
+  | '60'         // 60分钟
+  | 'daily'      // 日K
+  | 'weekly'     // 周K
+  | 'monthly';   // 月K
+```
+
+### IndicatorType
+
+```ts
+type IndicatorType =
+  // 主图指标
+  | 'ma'      // 移动平均线
+  | 'boll'    // 布林带
+  | 'sar'     // 抛物线转向（SAR）
+  | 'kc'      // 肯特纳通道（KC）
+  // 副图指标
+  | 'volume'  // 成交量
+  | 'macd'    // MACD
+  | 'kdj'     // KDJ
+  | 'rsi'     // RSI
+  | 'wr'      // WR（威廉指标）
+  | 'bias'    // BIAS（乖离率）
+  | 'cci'     // CCI（顺势指标）
+  | 'atr'     // ATR（平均真实波幅）
+  | 'obv'     // OBV（能量潮）
+  | 'roc'     // ROC（变动率）
+  | 'dmi';    // DMI（趋向指标）
+```
+
+**主图指标说明**：
+- **MA** - 移动平均线，显示不同周期的均线
+- **BOLL** - 布林带，由上轨、中轨、下轨组成的通道
+- **SAR** - 抛物线转向，以点状显示趋势反转信号
+- **KC** - 肯特纳通道，基于 EMA 和 ATR 的通道指标
+
+**副图指标说明**：
+- **OBV** - 能量潮，通过成交量变化预测价格趋势
+- **ROC** - 变动率，衡量价格变化的速度
+- **DMI** - 趋向指标，包含 +DI、-DI、ADX、ADXR 四条线
+
+## 主题定制
+
+### 内置主题
+
+```tsx
+// 浅色主题（默认）
+<KLineChart theme="light" />
+
+// 深色主题
+<KLineChart theme="dark" />
+```
+
+### 自定义主题
+
+```tsx
+<KLineChart
+  theme={{
+    backgroundColor: '#1a1a2e',
+    textColor: '#eaeaea',
+    upColor: '#26a69a',
+    downColor: '#ef5350',
+    gridLineColor: '#2a2a4a',
+    // ... 更多配置
+  }}
+/>
+```
+
+## 处理跨域
+
+由于 stock-sdk 默认请求腾讯财经接口，浏览器环境可能遇到跨域问题。推荐解决方案：
+
+### 方案 1：配置代理（开发环境）
+
+```ts
+// vite.config.ts
+export default {
+  server: {
+    proxy: {
+      '/qt': {
+        target: 'https://qt.gtimg.cn',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/qt/, ''),
+      },
+    },
+  },
+};
+```
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  sdkOptions={{ baseUrl: '/qt' }}
+/>
+```
+
+### 方案 2：自定义 DataProvider
+
+使用自己的后端接口代理数据：
+
+```tsx
+<KLineChart
+  symbol="sh600519"
+  dataProvider={myDataProvider}
+/>
+```
+
+## 目录结构
+
+```
+kline-charts-react/
+├── src/
+│   ├── components/       # 子组件
+│   │   ├── Loading/
+│   │   ├── PeriodSelector/
+│   │   ├── IndicatorSelector/
+│   │   ├── Toolbar/
+│   │   └── MADisplay/
+│   ├── hooks/            # React Hooks
+│   │   ├── useKlineData.ts
+│   │   ├── useEcharts.ts
+│   │   └── useZoomHistory.ts
+│   ├── utils/            # 工具函数
+│   │   ├── indicators.ts
+│   │   ├── optionBuilder.ts
+│   │   └── timelineBuilder.ts
+│   ├── types/            # 类型定义
+│   ├── KLineChart.tsx    # 主组件
+│   └── index.ts          # 入口
+├── playground/           # 调试环境
+└── dist/                 # 构建产物
+```
+
+## 开发
+
+```bash
+# 安装依赖
+yarn install
+
+# 启动开发调试（直连本地源码，支持热更新）
+yarn dev
+
+# 构建组件库
+yarn build
+
+# 构建 playground 生产版本（使用 npm 包）
+yarn build:playground
+
+# 代码检查
+yarn lint
+```
+
+**开发模式说明**：
+- `yarn dev` 会启动 playground，直接引用 `src/` 下的源码，修改源码后自动热更新
+- 生产构建时，playground 会使用 npm 上发布的 `kline-charts-react` 包
+
+## 已知限制
+
+- **导出图片**：`exportImage()` 方法导出的图片仅包含 ECharts 图表内容，不包含左上角的指标数值文字（这部分是用 React 渲染在图表外部的）
+
+## License
+
+MIT © 2025

package/dist/KLineChart.d.ts

@@ -0,0 +1,5 @@
+import { KLineChartProps, KLineChartRef } from './types';
+/**
+ * K 线图表组件
+ */
+export declare const KLineChart: import('react').ForwardRefExoticComponent<KLineChartProps & import('react').RefAttributes<KLineChartRef>>;

package/dist/components/IndicatorDisplay/IndicatorDisplay.d.ts

@@ -0,0 +1,12 @@
+import { KlineWithIndicators, IndicatorType } from '../../types';
+interface IndicatorDisplayProps {
+    data: KlineWithIndicators[];
+    indicators: IndicatorType[];
+    hoverIndex?: number | null;
+}
+/**
+ * 主图指标数值显示组件
+ * 支持 MA、BOLL、SAR、KC 指标
+ */
+export declare function IndicatorDisplay({ data, indicators, hoverIndex }: IndicatorDisplayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/IndicatorDisplay/index.d.ts

@@ -0,0 +1 @@
+export { IndicatorDisplay } from './IndicatorDisplay';

package/dist/components/IndicatorSelector/IndicatorSelector.d.ts

@@ -0,0 +1,12 @@
+import { IndicatorType } from '../../types';
+interface IndicatorSelectorProps {
+    value: IndicatorType[];
+    onChange: (indicators: IndicatorType[]) => void;
+    maxSubPanes?: number;
+    maxMainIndicators?: number;
+}
+/**
+ * 指标选择器组件
+ */
+export declare function IndicatorSelector({ value, onChange, maxSubPanes, maxMainIndicators, }: IndicatorSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/IndicatorSelector/index.d.ts

@@ -0,0 +1 @@
+export { IndicatorSelector } from './IndicatorSelector';

package/dist/components/Loading/Loading.d.ts

@@ -0,0 +1,8 @@
+interface LoadingProps {
+    text?: string;
+}
+/**
+ * 加载状态组件
+ */
+export declare function Loading({ text }: LoadingProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Loading/index.d.ts

@@ -0,0 +1 @@
+export { Loading } from './Loading';

package/dist/components/MADisplay/MADisplay.d.ts

@@ -0,0 +1,10 @@
+import { KlineWithIndicators } from '../../types';
+interface MADisplayProps {
+    data: KlineWithIndicators[];
+    hoverIndex?: number | null;
+}
+/**
+ * MA 数值显示组件
+ */
+export declare function MADisplay({ data, hoverIndex }: MADisplayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/MADisplay/index.d.ts

@@ -0,0 +1 @@
+export { MADisplay } from './MADisplay';

package/dist/components/PeriodSelector/PeriodSelector.d.ts

@@ -0,0 +1,10 @@
+import { PeriodType } from '../../types';
+interface PeriodSelectorProps {
+    value: PeriodType;
+    onChange: (period: PeriodType) => void;
+}
+/**
+ * 周期选择器组件
+ */
+export declare function PeriodSelector({ value, onChange }: PeriodSelectorProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/PeriodSelector/index.d.ts

@@ -0,0 +1 @@
+export { PeriodSelector } from './PeriodSelector';

package/dist/components/SubPaneTitle/SubPaneTitle.d.ts

@@ -0,0 +1,13 @@
+import { KlineWithIndicators, PaneConfig } from '../../types';
+interface SubPaneTitleProps {
+    panes: PaneConfig[];
+    data: KlineWithIndicators[];
+    hoverIndex?: number | null;
+    containerHeight: number;
+}
+/**
+ * 副图标题组件
+ * 显示在每个副图的左上角
+ */
+export declare function SubPaneTitle({ panes, data, hoverIndex, containerHeight }: SubPaneTitleProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/SubPaneTitle/index.d.ts

@@ -0,0 +1 @@
+export { SubPaneTitle } from './SubPaneTitle';

package/dist/components/Toolbar/Toolbar.d.ts

@@ -0,0 +1,20 @@
+import { AdjustType } from '../../types';
+interface ToolbarProps {
+    adjust: AdjustType;
+    onAdjustChange: (adjust: AdjustType) => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    onUndo: () => void;
+    onRedo: () => void;
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onPanLeft: () => void;
+    onPanRight: () => void;
+    onReset: () => void;
+    onFullscreen?: () => void;
+}
+/**
+ * 工具栏组件
+ */
+export declare function Toolbar({ adjust, onAdjustChange, canUndo, canRedo, onUndo, onRedo, onZoomIn, onZoomOut, onPanLeft, onPanRight, onReset, onFullscreen, }: ToolbarProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Toolbar/index.d.ts

@@ -0,0 +1 @@
+export { Toolbar } from './Toolbar';

package/dist/components/index.d.ts

@@ -0,0 +1,7 @@
+export { Loading } from './Loading';
+export { PeriodSelector } from './PeriodSelector';
+export { IndicatorSelector } from './IndicatorSelector';
+export { Toolbar } from './Toolbar';
+export { MADisplay } from './MADisplay';
+export { IndicatorDisplay } from './IndicatorDisplay';
+export { SubPaneTitle } from './SubPaneTitle';

package/dist/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { useKlineData } from './useKlineData';
+export { useEcharts } from './useEcharts';
+export { useZoomHistory } from './useZoomHistory';

package/dist/hooks/useEcharts.d.ts

@@ -0,0 +1,26 @@
+import { EChartsOption } from 'echarts';
+import * as echarts from 'echarts/core';
+export type EChartsInstance = echarts.ECharts;
+interface SetOptionOpts {
+    notMerge?: boolean;
+    lazyUpdate?: boolean;
+    replaceMerge?: string[];
+}
+interface UseEchartsResult {
+    chartRef: React.RefObject<HTMLDivElement | null>;
+    chartInstance: EChartsInstance | null;
+    setOption: (option: EChartsOption, opts?: boolean | SetOptionOpts, lazyUpdate?: boolean) => void;
+    resize: () => void;
+    dispose: () => void;
+    getDataURL: (opts?: {
+        type?: 'png' | 'jpeg';
+        pixelRatio?: number;
+        backgroundColor?: string;
+    }) => string;
+    bindEvent: (eventName: string, handler: (params: unknown) => void) => () => void;
+}
+/**
+ * ECharts 实例管理 Hook
+ */
+export declare function useEcharts(): UseEchartsResult;
+export {};

package/dist/hooks/useKlineData.d.ts

@@ -0,0 +1,24 @@
+import { KlineWithIndicators, TimelineData, PeriodType, MarketType, AdjustType, KLineDataProvider, SDKOptions, RequestOptions, IndicatorOptions } from '../types';
+interface UseKlineDataParams {
+    symbol: string;
+    market: MarketType;
+    period: PeriodType;
+    adjust: AdjustType;
+    dataProvider?: KLineDataProvider;
+    sdkOptions?: SDKOptions;
+    requestOptions?: RequestOptions;
+    indicatorOptions?: IndicatorOptions;
+    indicators?: string[];
+}
+interface UseKlineDataResult {
+    data: KlineWithIndicators[];
+    timelineData: TimelineData[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/**
+ * K 线数据获取 Hook
+ */
+export declare function useKlineData(params: UseKlineDataParams): UseKlineDataResult;
+export {};

package/dist/hooks/useZoomHistory.d.ts

@@ -0,0 +1,18 @@
+interface ZoomState {
+    start: number;
+    end: number;
+}
+interface UseZoomHistoryResult {
+    canUndo: boolean;
+    canRedo: boolean;
+    currentState: ZoomState;
+    pushState: (state: ZoomState) => void;
+    undo: () => ZoomState | null;
+    redo: () => ZoomState | null;
+    reset: (state?: ZoomState) => void;
+}
+/**
+ * 缩放历史管理 Hook（支持撤销/重做）
+ */
+export declare function useZoomHistory(initialState?: ZoomState): UseZoomHistoryResult;
+export {};