kline-charts-react 0.0.1 → 0.0.3

package/README.md

@@ -47,7 +47,7 @@ pnpm add kline-charts-react
 ### Peer Dependencies
 
 ```bash
-npm install react react-dom
+npm install react react-dom echarts
 ```
 
 ## 快速开始
@@ -82,12 +82,41 @@ function App() {
 ```tsx
 <KLineChart
   symbol="sh600519"
-  period="weekly"  // 周 K 线
+  defaultPeriod="weekly"  // 非受控模式下默认显示周 K
 />
 ```
 
 可选周期：`timeline` | `timeline5` | `1` | `5` | `15` | `30` | `60` | `daily` | `weekly` | `monthly`
 
+### 受控 / 非受控
+
+`period`、`adjust`、`indicators` 支持受控模式；`defaultPeriod`、`defaultAdjust`、`defaultIndicators` 用于非受控默认值。
+
+```tsx
+// 非受控
+<KLineChart
+  symbol="sh600519"
+  defaultPeriod="daily"
+  defaultAdjust="qfq"
+  defaultIndicators={['ma', 'volume', 'macd']}
+/>
+```
+
+```tsx
+// 受控
+function App() {
+  const [period, setPeriod] = useState<PeriodType>('daily');
+
+  return (
+    <KLineChart
+      symbol="sh600519"
+      period={period}
+      onPeriodChange={setPeriod}
+    />
+  );
+}
+```
+
 ### 配置技术指标
 
 ```tsx
@@ -128,13 +157,16 @@ function App() {
 import { KLineChart, type KLineDataProvider } from 'kline-charts-react';
 
 const customProvider: KLineDataProvider = {
+  // K 线数据（必须实现）
   getKline: async (params, signal) => {
-    const res = await fetch(`/api/kline?symbol=${params.symbol}`, { signal });
-    return res.json();
+    // params: { symbol, market, period, adjust }
+    const res = await fetch(`/api/kline?symbol=${params.symbol}&period=${params.period}`, { signal });
+    return res.json(); // 返回 KlineData[]
   },
+  // 分时数据（可选，仅分时模式使用）
   getTimeline: async (params, signal) => {
     const res = await fetch(`/api/timeline?symbol=${params.symbol}`, { signal });
-    return res.json();
+    return res.json(); // 返回 TimelineData[]
   },
 };
 
@@ -144,6 +176,42 @@ const customProvider: KLineDataProvider = {
 />
 ```
 
+#### KlineData 数据结构
+
+`getKline` 需要返回 `KlineData[]`，每条数据的字段如下：
+
+```ts
+interface KlineData {
+  date: string;              // 日期/时间，如 "2024-01-15" 或 "2024-01-15 09:35"
+  open: number | null;       // 开盘价
+  close: number | null;      // 收盘价
+  high: number | null;       // 最高价
+  low: number | null;        // 最低价
+  volume: number | null;     // 成交量
+  amount: number | null;     // 成交额
+  changePercent?: number;    // 涨跌幅（可选）
+  change?: number;           // 涨跌额（可选）
+  amplitude?: number;        // 振幅（可选）
+  turnoverRate?: number;     // 换手率（可选）
+}
+```
+
+#### TimelineData 数据结构
+
+`getTimeline` 需要返回 `TimelineData[]`，用于分时图展示：
+
+```ts
+interface TimelineData {
+  time: string;       // 时间，如 "09:30"
+  price: number;      // 当前价格
+  volume: number;     // 累计成交量
+  amount: number;     // 累计成交额
+  avgPrice: number;   // 均价
+}
+```
+
+> 技术指标（MA、MACD、KDJ 等）会由组件自动根据 K 线数据计算，无需在数据源中提供。
+
 ### 使用 Ref 控制图表
 
 ```tsx
@@ -172,6 +240,14 @@ function App() {
 }
 ```
 
+### `unstable` 二级导出
+
+主入口只保留稳定导出。如果你明确需要内部 hooks / 子组件，请从 `kline-charts-react/unstable` 引入：
+
+```tsx
+import { useKlineData, Toolbar } from 'kline-charts-react/unstable';
+```
+
 ## API 文档
 
 ### KLineChartProps
@@ -180,12 +256,15 @@ function App() {
 |------|------|--------|------|
 | `symbol` | `string` | **必填** | 股票代码，如 `sh600519`、`sz000001` |
 | `market` | `'A' \| 'HK' \| 'US'` | `'A'` | 市场类型 |
-| `period` | `PeriodType` | `'daily'` | K 线周期 |
-| `adjust` | `'' \| 'qfq' \| 'hfq'` | `'qfq'` | 复权类型（前复权） |
+| `period` | `PeriodType` | - | 当前 K 线周期（受控） |
+| `defaultPeriod` | `PeriodType` | `'daily'` | 非受控模式下默认周期 |
+| `adjust` | `'' \| 'qfq' \| 'hfq'` | - | 当前复权类型（受控） |
+| `defaultAdjust` | `'' \| 'qfq' \| 'hfq'` | `'qfq'` | 非受控模式下默认复权 |
 | `height` | `number \| string` | `500` | 图表高度 |
 | `width` | `number \| string` | `'100%'` | 图表宽度 |
 | `theme` | `'light' \| 'dark' \| ThemeConfig` | `'light'` | 主题配置 |
-| `indicators` | `IndicatorType[]` | `['ma', 'volume', 'macd']` | 启用的技术指标 |
+| `indicators` | `IndicatorType[]` | - | 当前启用的技术指标（受控） |
+| `defaultIndicators` | `IndicatorType[]` | `['ma', 'volume', 'macd']` | 非受控模式下默认指标 |
 | `indicatorOptions` | `IndicatorOptions` | - | 指标参数配置 |
 | `showToolbar` | `boolean` | `true` | 是否显示工具栏 |
 | `showPeriodSelector` | `boolean` | `true` | 是否显示周期切换 |
@@ -197,8 +276,13 @@ function App() {
 | `requestOptions` | `RequestOptions` | - | 请求控制配置 |
 | `autoRefresh` | `boolean \| AutoRefreshOptions` | - | 自动刷新配置 |
 | `echartsOption` | `EChartsOption` | - | 自定义 ECharts 配置 |
+| `echartsOptionMerge` | `EChartsOptionMergeOptions` | - | ECharts Option 合并策略 |
+| `panes` | `PaneConfig[]` | - | 自定义面板布局，支持单副图多指标 |
 | `onDataLoad` | `(data: KlineData[]) => void` | - | 数据加载回调 |
 | `onPeriodChange` | `(period: PeriodType) => void` | - | 周期切换回调 |
+| `onAdjustChange` | `(adjust: AdjustType) => void` | - | 复权切换回调 |
+| `onIndicatorsChange` | `(indicators: IndicatorType[]) => void` | - | 指标切换回调 |
+| `onVisibleRangeChange` | `({ start, end }) => void` | - | 当前 dataZoom 可见范围变化 |
 | `onError` | `(error: Error) => void` | - | 错误回调 |
 
 ### KLineChartRef
@@ -207,9 +291,11 @@ function App() {
 |------|------|
 | `refresh()` | 刷新数据 |
 | `setPeriod(period)` | 切换周期 |
+| `setAdjust(adjust)` | 切换复权 |
 | `setIndicators(indicators)` | 切换指标 |
 | `zoomTo(start, end)` | 缩放到指定范围 |
 | `resetZoom()` | 重置缩放 |
+| `getVisibleRange()` | 获取当前可见范围 `{ start, end }` |
 | `getEchartsInstance()` | 获取 ECharts 实例 |
 | `exportImage(type?)` | 导出图片（png/jpeg） |
 | `getData()` | 获取当前数据 |
@@ -335,25 +421,28 @@ export default {
 ```
 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/                 # 构建产物
+│   ├── components/           # 子组件
+│   │   ├── Loading/          # 加载状态
+│   │   ├── PeriodSelector/   # 周期切换
+│   │   ├── IndicatorSelector/# 指标选择器
+│   │   ├── Toolbar/          # 工具栏
+│   │   ├── IndicatorDisplay/ # 主图指标数值
+│   │   └── SubPaneTitle/     # 副图标题
+│   ├── hooks/                # React Hooks
+│   │   ├── useKlineData.ts   # 数据获取 & 指标计算
+│   │   ├── useEcharts.ts     # ECharts 实例管理
+│   │   └── useZoomHistory.ts # 缩放历史
+│   ├── utils/                # 工具函数
+│   │   ├── indicators.ts     # 技术指标计算
+│   │   ├── optionBuilder.ts  # K 线 ECharts 配置
+│   │   ├── timelineBuilder.ts# 分时图 ECharts 配置
+│   │   ├── formatters.ts     # 数据格式化
+│   │   └── cache.ts          # 数据缓存
+│   ├── types/                # 类型定义
+│   ├── KLineChart.tsx        # 主组件
+│   └── index.ts              # 入口
+├── playground/               # 调试环境
+└── dist/                     # 构建产物
 ```
 
 ## 开发
@@ -368,16 +457,26 @@ yarn dev
 # 构建组件库
 yarn build
 
-# 构建 playground 生产版本（使用 npm 包）
+# 构建 playground 生产版本
 yarn build:playground
 
 # 代码检查
 yarn lint
+
+# 类型检查
+yarn typecheck
+
+# 单元测试
+yarn test:run
+
+# 打包校验
+yarn pack:check
 ```
 
 **开发模式说明**：
 - `yarn dev` 会启动 playground，直接引用 `src/` 下的源码，修改源码后自动热更新
-- 生产构建时，playground 会使用 npm 上发布的 `kline-charts-react` 包
+- `playground/` 通过本地 `file:..` 依赖引用当前仓库，避免和 npm 上的历史版本漂移
+- CI 会执行 `lint`、`typecheck`、`test:run`、`build`、`build:playground` 和 `pack:check`
 
 ## 已知限制