@363045841yyt/klinechart 0.1.0 → 0.1.2

package/README.md

@@ -1,48 +1,286 @@
-# kmap
-
-This template should help get you started developing with Vue 3 in Vite.
-
-## Recommended IDE Setup
-
-[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
-
-## Recommended Browser Setup
-
-- Chromium-based browsers (Chrome, Edge, Brave, etc.):
-  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
-  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
-- Firefox:
-  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
-  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
-
-## Type Support for `.vue` Imports in TS
-
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
-
-## Customize configuration
-
-See [Vite Configuration Reference](https://vite.dev/config/).
-
-## Project Setup
-
-```sh
-pnpm install
-```
-
-### Compile and Hot-Reload for Development
-
-```sh
-pnpm dev
-```
-
-### Type-Check, Compile and Minify for Production
-
-```sh
-pnpm build
-```
-
-### Run Unit Tests with [Vitest](https://vitest.dev/)
-
-```sh
-pnpm test:unit
-```
+# kmap - 金融图表绘制库
+
+这是一个基于 Vue 3 和 Canvas 的金融图表绘制库，专注于提供高性能的 K 线图展示功能。该库支持横向滚动、移动平均线（MA）显示以及从多种数据源（包括 AKTools）获取金融数据。
+
+## 功能特性
+
+- 📊 **K 线图绘制**：使用 Canvas 实现高性能的 K 线图绘制
+- 📈 **移动平均线**：支持 MA5、MA10、MA20 等多种移动平均线显示
+- ↔️ **横向滚动**：支持大量历史数据的横向滚动浏览
+- 🎨 **深色模式**：自动适配系统深色模式
+- 📱 **响应式设计**：适配不同屏幕尺寸
+- ⚡ **高性能**：使用 requestAnimationFrame 优化渲染性能
+
+## 技术栈
+
+- [Vue 3](https://vuejs.org/) - 渐进式 JavaScript 框架
+- [Vite](https://vite.dev/) - 下一代前端构建工具
+- [TypeScript](https://www.typescriptlang.org/) - JavaScript 类型检查
+- [Canvas API](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API) - 图形绘制
+- [AKTools](https://github.com/akfamily/aktools) - 开源金融数据接口库
+
+## 项目结构
+
+```
+src/
+├── api/                 # API 接口定义
+│   └── data/
+│       └── kLine.ts     # K 线数据接口
+├── components/          # 组件
+│   └── KLineChart.vue   # K 线图主组件
+├── types/               # 类型定义
+│   ├── kLine.ts         # K 线类型定义
+│   └── price.ts         # 价格类型定义
+├── utils/               # 工具函数
+│   ├── draw/            # 绘制工具
+│   │   ├── kLine.ts     # K 线绘制
+│   │   └── MA.ts        # 移动平均线绘制
+│   ├── mock/            # 模拟数据生成
+│   ├── logger.ts        # 日志工具
+│   └── priceToY.ts      # 价格转 Y 坐标
+├── stores/              # 状态管理 (Pinia)
+└── assets/              # 静态资源
+```
+
+## 数据接入
+
+### AKTools 数据接入
+
+AKTools 是一个开源的金融数据接口库，可以免费获取股票、期货、期权等金融产品的历史数据。
+
+#### 安装 AKTools
+
+使用 uv pip 安装:
+
+```bash
+# 安装 uv（如果尚未安装）
+pip install uv
+
+# 使用 uv 安装 AKTools
+uv pip install aktools
+```
+
+或者直接使用 pip 安装:
+
+```bash
+pip install aktools
+```
+
+#### 启动 AKTools 数据服务
+
+方法一：使用 uv 直接运行 AKTools
+
+```bash
+uv run python -m aktools
+```
+
+方法一（推荐）：通过本项目脚本启动（会自动切换到上级目录的 `aktoolshttp/`）
+
+```bash
+pnpm aktools
+```
+
+#### 手机访问本机（开发模式）并调用 AKTools API（推荐）
+
+如果你希望用手机浏览器访问本机正在运行的 `pnpm dev` 页面，同时前端还能调用本机的 AKTools API，推荐使用 **Vite 代理**（避免 CORS，且手机不需要直连 8080）。
+
+本项目已在 `vite.config.ts` 配置：
+
+- dev server 监听 `0.0.0.0`
+- 代理转发：`/api` -> `http://127.0.0.1:8080`
+
+启动步骤：
+
+1. 启动 AKTools（本机 8080）：
+
+   ```bash
+   pnpm aktools
+   ```
+
+2. 启动前端 dev server（允许局域网访问）：
+
+   ```bash
+   pnpm dev:lan
+   ```
+
+3. 查找本机局域网 IP（例如 `192.168.1.23`），手机浏览器访问：
+
+   ```
+   http://192.168.1.23:5173
+   ```
+
+> 说明：前端请求路径保持 `VITE_API_PATH=/api/public/stock_zh_a_hist`，浏览器请求会先到 5173，再由 Vite 代理到本机 8080，因此通常不会遇到跨域问题。
+
+如果你之前在 `.env` 写死了 `VITE_API_BASE_URL=http://127.0.0.1:8080`，手机端会把 `127.0.0.1` 解析成“手机自己”，从而导致 API 连接失败。此时请把 `VITE_API_BASE_URL` 留空（或删除该行），让前端走相对路径并交给 Vite 代理。
+
+方法二：创建自定义后端服务
+除了使用 AKTools 自带的服务外，你也可以根据需要创建自定义的后端服务来处理数据。
+
+#### 配置前端环境变量
+
+在项目根目录创建 `.env` 文件：
+
+```
+VITE_API_BASE_URL=http://127.0.0.1:8080
+VITE_API_PATH=/api/public/stock_zh_a_hist
+```
+
+然后在 [vite.config.ts](file:///d:/Code/kmap/kmap/vite.config.ts) 中确保环境变量被正确加载：
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  define: {
+    'process.env': process.env,
+  },
+})
+```
+
+### 数据格式
+
+K 线数据需要包含以下字段：
+
+```ts
+interface KLineDailyDongCaiResponse {
+  日期: string // 日期
+  股票代码: string // 股票代码
+  开盘: number // 开盘价
+  收盘: number // 收盘价
+  最高: number // 最高价
+  最低: number // 最低价
+  成交量: number // 成交量
+  成交额: number // 成交额
+  振幅: number // 振幅
+  涨跌幅: number // 涨跌幅
+  涨跌额: number // 涨跌额
+  换手率: number // 换手率
+}
+```
+
+## 使用方法
+
+### 1. 安装依赖
+
+```sh
+pnpm install
+```
+
+### 2. 启动开发服务器
+
+```sh
+pnpm dev
+```
+
+### 3. 在组件中使用 K 线图
+
+```vue
+<template>
+  <KLineChart
+    :data="klineData"
+    :kWidth="10"
+    :kGap="2"
+    :yPaddingPx="60"
+    :showMA="{ ma5: true, ma10: true, ma20: true }"
+    :autoScrollToRight="true"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import KLineChart from '@/components/KLineChart.vue'
+import { getKlineDataDongCai } from '@/api/data/kLine'
+import { toKLineData, type KLineData } from '@/types/price'
+
+const klineData = ref<KLineData[]>([])
+
+onMounted(async () => {
+  const raw = await getKlineDataDongCai({
+    symbol: '601360', // 三六零股票代码
+    period: 'daily',
+    start_date: '20250501',
+    end_date: '20251230',
+    adjust: 'qfq', // 前复权
+  })
+  klineData.value = toKLineData(raw) // 转换并排序数据
+})
+</script>
+```
+
+### 组件属性
+
+| 属性              | 类型        | 默认值                                | 说明                           |
+| ----------------- | ----------- | ------------------------------------- | ------------------------------ |
+| data              | KLineData[] | []                                    | K 线数据数组                   |
+| kWidth            | number      | 10                                    | K 线实体宽度                   |
+| kGap              | number      | 2                                     | K 线间距                       |
+| yPaddingPx        | number      | 60                                    | Y 轴上下留白像素               |
+| showMA            | MAFlags     | { ma5: true, ma10: true, ma20: true } | 是否显示移动平均线             |
+| autoScrollToRight | boolean     | true                                  | 数据更新后是否自动滚动到最右侧 |
+
+## 性能优化
+
+- 使用 `requestAnimationFrame` 优化渲染性能
+- 对于滚动等高频事件，使用 passive 模式提升响应性能
+- Canvas 绘制时使用设备像素比（devicePixelRatio）确保在高分屏上清晰显示
+- 通过路径重置（beginPath）避免路径污染
+
+## 环境要求
+
+- Node.js: ^20.19.0 || >=22.12.0
+- pnpm: 包管理器
+- Python: 用于运行 AKTools 服务（可选）
+- uv: Python 包与运行器（用于 `pnpm aktools`，可选但推荐）
+
+## 构建与部署
+
+### 生产环境构建
+
+```sh
+pnpm build
+```
+
+### 预览生产包
+
+```sh
+pnpm preview
+```
+
+## API 接口说明
+
+### getKlineDataDongCai
+
+获取 K 线数据的异步函数。
+
+**参数:**
+
+```ts
+interface KLineDailyDongCaiRequest {
+  symbol: string // 股票代码
+  period: 'daily' | 'weekly' | 'monthly' // 周期
+  start_date: string // 开始日期，格式：YYYYMMDD
+  end_date: string // 结束日期，格式：YYYYMMDD
+  adjust?: 'qfq' | 'hfq' // 复权方式，qfq: 前复权, hfq: 后复权
+  timeout?: number // 超时时间（秒）
+}
+```
+
+**返回值:**
+`Promise<KLineDailyDongCaiResponse[]>` - K 线数据数组
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request 来改进这个项目。
+
+## 许可证
+
+本项目采用 MIT 许可证，详情请见 [LICENSE](./LICENSE) 文件。
+
+## 相关链接
+
+- [Vue.js 官方文档](https://vuejs.org/guide/introduction.html)
+- [Vite 官方文档](https://vite.dev/guide/)
+- [AKTools 官方文档](https://github.com/akfamily/aktools)
+- [Canvas API MDN 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)

package/dist/App.vue.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, HTMLDivElement>;
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
 export default _default;

package/dist/components/KLineChart.vue.d.ts

@@ -11,23 +11,36 @@ type __VLS_Props = {
     yPaddingPx?: number;
     showMA?: MAFlags;
     autoScrollToRight?: boolean;
+    minKWidth?: number;
+    maxKWidth?: number;
+    /** 右侧价格轴宽度 */
+    rightAxisWidth?: number;
+    /** 底部时间轴高度 */
+    bottomAxisHeight?: number;
+    /** Pane 高度比例（主/副），默认 [0.85, 0.15] */
+    paneRatios?: [number, number];
 };
-/**
- * rAF 节流：scroll/resize/data变化都用它触发
- */
 declare function scheduleRender(): void;
 declare function scrollToRight(): void;
 declare const _default: import('vue').DefineComponent<__VLS_Props, {
     scheduleRender: typeof scheduleRender;
     scrollToRight: typeof scrollToRight;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    yPaddingPx: number;
     kWidth: number;
     kGap: number;
-    yPaddingPx: number;
     showMA: MAFlags;
+    rightAxisWidth: number;
+    bottomAxisHeight: number;
+    minKWidth: number;
+    maxKWidth: number;
     autoScrollToRight: boolean;
+    paneRatios: [number, number];
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     containerRef: HTMLDivElement;
-    canvasRef: HTMLCanvasElement;
-}, HTMLDivElement>;
+    canvasLayerRef: HTMLDivElement;
+    plotCanvasRef: HTMLCanvasElement;
+    yAxisCanvasRef: HTMLCanvasElement;
+    xAxisCanvasRef: HTMLCanvasElement;
+}, any>;
 export default _default;

package/dist/components/KLineTooltip.vue.d.ts

@@ -0,0 +1,15 @@
+import { KLineData } from '../types/price';
+type __VLS_Props = {
+    k: KLineData | null;
+    /** 当前k在 data 中的索引 */
+    index: number | null;
+    data: KLineData[];
+    pos: {
+        x: number;
+        y: number;
+    };
+    /** 把 tooltip 根元素回传给父组件（用于测量宽高） */
+    setEl?: (el: HTMLDivElement | null) => void;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/composables/useKLineInteraction.d.ts

@@ -0,0 +1,50 @@
+import { ComputedRef, Ref } from 'vue';
+import { KLineData } from '../types/price';
+import { KLineViewport } from './useKLineRenderer';
+export type TooltipSize = {
+    width: number;
+    height: number;
+};
+export type TooltipPos = {
+    x: number;
+    y: number;
+};
+export declare function useKLineInteraction(args: {
+    containerRef: Ref<HTMLDivElement | null>;
+    tooltipRef: Ref<HTMLDivElement | null>;
+    getData: () => KLineData[];
+    kWidth: Ref<number>;
+    kGap: Ref<number>;
+    minKWidth: number;
+    maxKWidth: number;
+    initialRatio: number;
+    rightAxisWidth: Ref<number>;
+    bottomAxisHeight: Ref<number>;
+    yPaddingPx: Ref<number>;
+    scheduleRender: () => void;
+    getViewport: () => KLineViewport | null;
+    crosshairPos?: Ref<{
+        x: number;
+        y: number;
+    } | null>;
+    crosshairIndex?: Ref<number | null>;
+}): {
+    isDragging: Ref<boolean>;
+    hoveredIndex: Ref<number | null>;
+    hovered: ComputedRef<KLineData | null>;
+    crosshairPos: Ref<{
+        x: number;
+        y: number;
+    } | null>;
+    crosshairIndex: Ref<number | null>;
+    tooltipPos: Ref<TooltipPos>;
+    tooltipSize: Ref<TooltipSize>;
+    clearCrosshair: () => void;
+    clearHover: () => void;
+    onMouseDown: (e: MouseEvent) => void;
+    onMouseMove: (e: MouseEvent) => void;
+    onMouseUp: () => void;
+    onMouseLeave: () => void;
+    onScroll: () => void;
+    onWheel: (e: WheelEvent) => void;
+};

package/dist/composables/useKLineRenderer.d.ts

@@ -0,0 +1,49 @@
+import { Ref } from 'vue';
+import { KLineData } from '../types/price';
+import { PriceRange } from '../utils/kline/viewport';
+export type MAFlags = {
+    ma5?: boolean;
+    ma10?: boolean;
+    ma20?: boolean;
+};
+export type CrosshairPos = {
+    x: number;
+    y: number;
+} | null;
+export type KLineOption = {
+    kWidth: number;
+    kGap: number;
+    yPaddingPx?: number;
+};
+export type KLineViewport = {
+    viewWidth: number;
+    viewHeight: number;
+    plotWidth: number;
+    plotHeight: number;
+    rightAxisWidth: number;
+    bottomAxisHeight: number;
+    scrollLeft: number;
+    start: number;
+    end: number;
+    priceRange: PriceRange;
+    dpr: number;
+};
+export declare function useKLineRenderer(args: {
+    plotCanvasRef: Ref<HTMLCanvasElement | null>;
+    yAxisCanvasRef: Ref<HTMLCanvasElement | null>;
+    xAxisCanvasRef: Ref<HTMLCanvasElement | null>;
+    canvasLayerRef: Ref<HTMLDivElement | null>;
+    containerRef: Ref<HTMLDivElement | null>;
+    getData: () => KLineData[];
+    getOption: () => KLineOption;
+    getShowMA: () => MAFlags;
+    rightAxisWidth: Ref<number>;
+    bottomAxisHeight: Ref<number>;
+    crosshairPos: Ref<CrosshairPos>;
+    crosshairIndex: Ref<number | null>;
+}): {
+    scheduleRender: () => void;
+    render: () => void;
+    getLastViewport: () => KLineViewport | null;
+    destroy: () => void;
+};

package/dist/core/chart.d.ts

@@ -0,0 +1,145 @@
+import { KLineData } from '../types/price';
+import { Pane } from './layout/pane';
+import { InteractionController } from './controller/interaction';
+export type ChartDom = {
+    container: HTMLDivElement;
+    canvasLayer: HTMLDivElement;
+    plotCanvas: HTMLCanvasElement;
+    yAxisCanvas: HTMLCanvasElement;
+    xAxisCanvas: HTMLCanvasElement;
+};
+export type PaneSpec = {
+    id: string;
+    ratio: number;
+};
+export type ChartOptions = {
+    kWidth: number;
+    kGap: number;
+    yPaddingPx: number;
+    rightAxisWidth: number;
+    bottomAxisHeight: number;
+    minKWidth: number;
+    maxKWidth: number;
+    panes: PaneSpec[];
+    /** pane 之间的真实分隔空隙（逻辑像素） */
+    paneGap?: number;
+};
+export type Viewport = {
+    viewWidth: number;
+    viewHeight: number;
+    plotWidth: number;
+    plotHeight: number;
+    scrollLeft: number;
+    dpr: number;
+};
+export declare class Chart {
+    private dom;
+    private opt;
+    private data;
+    private raf;
+    private viewport;
+    private panes;
+    readonly interaction: InteractionController;
+    private onZoomChange?;
+    /**
+     * 注册缩放回调。
+     *
+     * 为什么需要它：
+     * - `zoomAt()` 会更新 core 内部的 `kWidth/kGap`，但项目的横向滚动范围来自 Vue 层 `.scroll-content` 的宽度。
+     * - Vue 需要先用新的 kWidth/kGap 重新计算内容宽度（触发 DOM 更新 scrollWidth），
+     *   再设置正确的 scrollLeft，否则会出现“放大后无法拖到最右侧”的问题。
+     *
+     * @param cb (newKWidth, newKGap, targetScrollLeft) => void
+     */
+    setOnZoomChange(cb: (kWidth: number, kGap: number, targetScrollLeft: number) => void): void;
+    /**
+     * 创建图表实例。
+     *
+     * @param dom 由 Vue 组件传入的 DOM 句柄（container/canvasLayer/三层 canvas）
+     * @param opt 初始配置（kWidth/kGap、轴尺寸、pane 配置等）
+     */
+    constructor(dom: ChartDom, opt: ChartOptions);
+    /** 获取所有 pane（包含布局信息与 renderers 列表） */
+    getPanes(): Pane[];
+    /**
+     * 设置某个 pane 的渲染器链（按顺序执行）。
+     *
+     * @param paneId pane 标识（例如 'main'/'sub'）
+     * @param renderers 渲染器数组；会清空并替换原有列表（保持引用稳定）
+     */
+    setPaneRenderers(paneId: string, renderers: Pane['renderers']): void;
+    /** 获取 ChartDom（供 InteractionController 等使用） */
+    getDom(): ChartDom;
+    /** 获取当前 ChartOptions（注意：返回的是内部当前快照） */
+    getOption(): ChartOptions;
+    /**
+     * 更新配置并触发布局/重绘。
+     * - 更新 panes 时会重建 Pane 实例并重新布局。
+     */
+    updateOptions(partial: Partial<ChartOptions>): void;
+    /**
+     * 更新数据并请求重绘。
+     * @param data K 线数据数组（null/undefined 会被视为 []）
+     */
+    updateData(data: KLineData[]): void;
+    /** 获取当前数据源（给 renderers/interaction 使用） */
+    getData(): KLineData[];
+    /**
+     * 内容总宽度（用于外部 scroll-content 撑开 scrollWidth）
+     * 规则：kGap + n*(kWidth+kGap) + rightAxisWidth
+     */
+    getContentWidth(): number;
+    /**
+     * 容器尺寸变化时调用：
+     * - 重新计算 viewport（DPR/plotWidth/plotHeight）
+     * - 重新计算 pane 布局
+     * - 请求重绘
+     */
+    resize(): void;
+    /**
+     * 请求下一帧重绘（RAF 合并）。
+     * 多次调用只会触发一次 draw，避免频繁重绘。
+     */
+    scheduleDraw(): void;
+    /**
+     * 绘制一帧：
+     * 1) computeViewport（设置 canvas 尺寸）
+     * 2) 计算可视区 range（start/end）
+     * 3) 对每个 pane：更新 priceRange -> 执行 renderers（plotCanvas）-> 画 yAxis（yAxisCanvas）
+     * 4) 画 xAxis（xAxisCanvas）
+     * 5) 画 overlay（十字线、图例、边框等）
+     */
+    draw(): void;
+    /**
+     * 在给定 mouseX（相对 container 左侧）处做缩放。
+     *
+     * 设计目标：缩放后保持 mouseX 指向的“数据索引”尽量稳定（以该点为中心缩放）。
+     *
+     * @param mouseX 鼠标相对 container 的 x（逻辑像素）
+     * @param scrollLeft 当前 container.scrollLeft
+     * @param deltaY WheelEvent.deltaY（>0 缩小，<0 放大）
+     */
+    zoomAt(mouseX: number, scrollLeft: number, deltaY: number): void;
+    /**
+     * 销毁 chart：
+     * - 取消 RAF
+     * - 释放引用，避免内存泄漏
+     */
+    destroy(): void;
+    /** 根据 opt.panes 重建 Pane 实例列表 */
+    private initPanes;
+    /**
+     * 计算每个 pane 的布局（top/height）。
+     * - 按 ratio 分配高度
+     * - 支持 paneGap 形成真实留白
+     */
+    private layoutPanes;
+    /**
+     * 计算并应用 viewport：
+     * - 读取 container 尺寸
+     * - 计算 plot 区域尺寸（扣掉右轴/底轴）
+     * - 处理 DPR 以及最大像素限制（避免超大 canvas）
+     * - 设置 canvasLayer/三个 canvas 的 style 尺寸与实际像素尺寸
+     */
+    private computeViewport;
+}