@363045841yyt/klinechart 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +126 -259
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.js +151 -32
  4. package/dist/klinechart.css +1 -1
  5. package/dist/src/components/LeftToolbar.vue.d.ts +4 -0
  6. package/dist/src/core/controller/interaction.d.ts +9 -0
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,259 +1,126 @@
1
- # kmap - 金融图表绘制库
2
-
3
- [English](README_EN.md) | 简体中文
4
-
5
- 这是一个基于 Canvas 的金融图表绘制库，提供 Vue 组件封装。专注于高性能 K 线图渲染，支持**语义化 JSON 配置**，便于 AI Agent 直接控制图表渲染。特性包括横向滚动、多种技术指标（MA/BOLL/MACD/RSI 等）、自定义标记标注、多数据源支持（BaoStock、东方财富）。
6
-
7
- [NPM](https://www.npmjs.com/package/@363045841yyt/klinechart) | [GitHub](https://github.com/363045841/KLineChartQuant)
8
-
9
- ## 功能特性
10
-
11
- - **基于 Canvas**：使用 Canvas 实现高性能的 K 线图绘制
12
- - **响应式设计**：适配不同屏幕尺寸，支持所有设备像素比（DPR），不同 DPR 下绘制清晰
13
- - **ResizeObserver 驱动的高清渲染**：单一链路自动维护 Canvas 尺寸与 DPR，浏览器缩放、跨屏拖动、容器 resize 时持续清晰绘制
14
- - **影线处理**：统一 DPR 坐标计算，底层保证影线在不同 DPR 屏幕下绝对居中并绘制清晰
15
- - **像素对齐**：统一坐标源，在物理坐标层面实现像素对齐，消除亚像素渲染，确保线条锐利清晰
16
- - **框架无关**：核心逻辑完全独立，不依赖特定框架
17
- - **插件化架构**：渲染器插件支持动态注册、配置和生命周期管理
18
- - **量价关系标注**：自动识别并标注量价齐升、量价背离、量增价跌、量缩价跌四种形态
19
- - **绘图工具**（v0.5 预览）：支持基础线条绘制，包括趋势线（线段、射线、延长线）、水平线/垂直线/十字线、信息线、平行通道和线性回归通道。v0.5 版本将完善绘图交互与编辑能力
20
-
21
- ![pasted-image-1778063749574.webp](https://files.seeusercontent.com/2026/05/06/2Udv/pasted-image-1778063749574.webp)
22
- ![pasted-image-1778063691961.webp](https://files.seeusercontent.com/2026/05/06/q1Cq/pasted-image-1778063691961.webp)
23
- ![pasted-image-1778063638151.webp](https://files.seeusercontent.com/2026/05/06/uv3R/pasted-image-1778063638151.webp)
24
- ![pasted-image-1778256491407.webp](https://files.seeusercontent.com/2026/05/08/1Nkp/pasted-image-1778256491407.webp)
25
-
26
- ### Agent 语义化控制
27
-
28
- - **JSON 配置驱动**：通过 `semanticConfig` prop 接收 JSON 配置，AI Agent 可直接控制图表渲染
29
- - **自定义标记**：支持 6 种预设形状（arrow_up、arrow_down、flag、circle、rectangle、diamond），标记大小随 K 线缩放自适应
30
- - **完整指标支持**：主图 MA/BOLL，副图 MACD/RSI/CCI/STOCH 等
31
- - **安全校验**：JSON Schema 校验、原型污染防护、颜色 XSS 防护、输入边界检查
32
- - **日期友好格式**：使用 `YYYY-MM-DD` 自然日期格式，便于 Agent 输出
33
-
34
- ## 技术栈
35
-
36
- - [Vue 3](https://vuejs.org/) - 渐进式 JavaScript 框架
37
- - [Rolldown Vite](https://cn.vite.dev/guide/rolldown) - 下一代前端构建工具，极速构建
38
- - [TypeScript](https://www.typescriptlang.org/)
39
- - [Canvas API](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)
40
- - [Vitest](https://vitest.dev/) - 单元测试框架
41
-
42
- ## 项目结构
43
-
44
- ```
45
- src/
46
- ├── api/ # API 接口定义
47
- │ └── data/ # 数据源接口
48
- ├── components/ # Vue 组件
49
- │ ├── KLineChart.vue # K 线图主组件
50
- │ ├── IndicatorSelector.vue # 指标选择器
51
- │ ├── IndicatorParams.vue # 指标参数编辑
52
- │ └── LeftToolbar.vue # 左侧绘图工具栏
53
- ├── core/ # 核心渲染引擎
54
- │ ├── chart.ts # 图表控制器
55
- │ ├── drawing/ # 绘图系统
56
- │ │ ├── index.ts # DrawingStore、定义注册、图元渲染器
57
- │ │ └── plugin.ts # 绘图渲染器插件
58
- │ ├── renderers/ # 渲染器插件
59
- │ │ ├── candle.ts # K 线渲染器
60
- │ │ ├── ma.ts # MA 均线渲染器
61
- │ │ ├── boll.ts # BOLL 布林带渲染器
62
- │ │ ├── macd.ts # MACD 指标渲染器
63
- │ │ ├── volume.ts # 成交量渲染器
64
- │ │ └── ... # 其他渲染器
65
- │ ├── theme/ # 主题配置
66
- │ ├── marker/ # 标记点系统
67
- │ └── utils/ # 核心工具
68
- ├── semantic/ # 语义化配置模块（Agent 控制）
69
- │ ├── types.ts # 类型定义
70
- │ ├── schema.json # JSON Schema
71
- │ ├── validator.ts # 校验器
72
- │ ├── controller.ts # 控制器
73
- │ └── drawShape.ts # 形状绘制
74
- ├── plugin/ # 插件系统
75
- │ ├── types.ts # 类型定义
76
- │ ├── PluginHost.ts # 插件宿主
77
- │ ├── EventBus.ts # 事件总线
78
- │ ├── HookSystem.ts # 钩子系统
79
- │ └── rendererPluginManager.ts # 渲染器管理
80
- ├── types/ # 类型定义
81
- └── utils/ # 工具函数
82
- ```
83
-
84
- ## 数据源
85
-
86
- - [BaoStock](http://baostock.com/) - 开源金融数据接口，每日支持十万次 API 调用
87
- - [AKTools](https://github.com/akfamily/aktools) - 开源金融数据接口库（可能存在反爬限制）
88
-
89
- ## 使用 NPM 安装组件库
90
-
91
- ```bash
92
- npm i @363045841yyt/klinechart
93
- ```
94
-
95
- ## 快速开始
96
-
97
- ```bash
98
- # 安装依赖
99
- pnpm install
100
-
101
- # 启动开发服务器
102
- pnpm dev
103
- ```
104
-
105
- ## 使用示例
106
-
107
- ```vue
108
- <template>
109
- <KLineChart :semanticConfig="config" />
110
- </template>
111
-
112
- <script setup lang="ts">
113
- import { ref } from 'vue'
114
- import KLineChart from '@/components/KLineChart.vue'
115
- import type { SemanticChartConfig } from '@/semantic'
116
-
117
- const config = ref<SemanticChartConfig>({
118
- version: '1.0.0',
119
- data: {
120
- source: 'baostock',
121
- symbol: '601360',
122
- exchange: 'SH',
123
- startDate: '2024-01-01',
124
- endDate: '2024-12-31',
125
- period: 'daily',
126
- adjust: 'qfq',
127
- },
128
- indicators: {
129
- main: [{ type: 'MA', enabled: true, params: { periods: [5, 10, 20] } }],
130
- sub: [{ type: 'MACD', enabled: true }],
131
- },
132
- chart: {
133
- kWidth: 10,
134
- kGap: 2,
135
- autoScrollToRight: true,
136
- },
137
- })
138
- </script>
139
- ```
140
-
141
- ### 语义化 JSON 控制（Agent 模式）
142
-
143
- 通过 `semanticConfig` prop，AI Agent 可以用 JSON 配置完整控制图表渲染：
144
-
145
- ```vue
146
- <template>
147
- <KLineChart :semanticConfig="config" />
148
- </template>
149
-
150
- <script setup lang="ts">
151
- import { ref } from 'vue'
152
- import type { SemanticChartConfig } from '@363045841yyt/klinechart'
153
-
154
- const config = ref<SemanticChartConfig>({
155
- version: '1.0.0',
156
- data: {
157
- source: 'baostock',
158
- symbol: '600519',
159
- exchange: 'SH',
160
- startDate: '2025-01-01',
161
- endDate: '2025-04-18',
162
- period: 'daily',
163
- adjust: 'qfq',
164
- },
165
- indicators: {
166
- main: [{ type: 'MA', enabled: true, params: { periods: [5, 10, 20] } }],
167
- sub: [{ type: 'MACD', enabled: true }],
168
- },
169
- markers: {
170
- customMarkers: [
171
- {
172
- id: 'buy_001',
173
- date: '2025-02-15',
174
- shape: 'arrow_up',
175
- label: { text: '买入' },
176
- style: { fillColor: '#52c41a' },
177
- },
178
- ],
179
- },
180
- })
181
- </script>
182
- ```
183
-
184
- 详细配置说明请参阅 [语义化配置文档](./docs/semantic-config.md)。
185
-
186
- ## 数据源配置
187
-
188
- ### BaoStock（推荐）
189
-
190
- 免费开源的 Python 证券数据接口，每日支持十万次 API 调用。
191
-
192
- ```bash
193
- # 方式一：手动安装并启动
194
- uv pip install baostock
195
- git clone https://github.com/363045841/stockbao.git
196
- cd stockbao
197
- uv run python ./server.py
198
-
199
- # 方式二：使用项目内置脚本（需将 stockbao 克隆到父目录）
200
- pnpm stockbao
201
- ```
202
-
203
- ### AKTools
204
-
205
- 基于 Python 的开源财经数据接口，数据来源于东方财富等公开渠道。
206
-
207
- ```bash
208
- uv pip install aktools
209
- uv run python -m aktools # 启动服务
210
- ```
211
-
212
- > ⚠️ 注意：AKTools 采取直连 API，频繁请求可能触发反爬机制
213
-
214
- ### 组件属性
215
-
216
- | 属性 | 类型 | 默认值 | 说明 |
217
- |------|------|--------|------|
218
- | semanticConfig | SemanticChartConfig | - | **必需**。语义化配置（唯一控制源） |
219
- | yPaddingPx | number | 0 | Y 轴上下留白像素 |
220
- | minKWidth | number | 2 | K 线最小宽度 |
221
- | maxKWidth | number | 50 | K 线最大宽度 |
222
- | rightAxisWidth | number | 0 | 右侧价格轴宽度 |
223
- | bottomAxisHeight | number | 24 | 底部时间轴高度 |
224
- | priceLabelWidth | number | 60 | 价格标签额外宽度（用于显示涨跌幅） |
225
- | zoomLevels | number | 20 | 缩放级别数量 |
226
- | initialZoomLevel | number | 3 | 初始缩放级别（1 ~ zoomLevels） |
227
-
228
- ## 环境要求
229
-
230
- - Node.js: ^20.19.0 || >=22.12.0
231
- - pnpm: 包管理器
232
- - Python: 用于运行数据源服务（可选）
233
- - uv: Python 包管理器
234
-
235
- ## 构建与部署
236
-
237
- ```bash
238
- pnpm build # 生产环境构建
239
- pnpm preview # 预览生产包
240
- ```
241
-
242
- ## 相关链接
243
-
244
- - [NPM 包地址](https://www.npmjs.com/package/@363045841yyt/klinechart)
245
- - [GitHub 仓库](https://github.com/363045841/KLineChartQuant)
246
- - [Vue.js 官方文档](https://vuejs.org/guide/introduction.html)
247
- - [Vite 官方文档](https://vite.dev/guide/)
248
- - [BaoStock 官方文档](http://baostock.com/)
249
- - [AKTools 官方文档](https://github.com/akfamily/aktools)
250
- - [Canvas API MDN 文档](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)
251
- - [Vitest 官方文档](https://vitest.dev/)
252
- - [语义化配置文档](./docs/semantic-config.md) - Agent JSON 配置说明
253
- - [架构文档（ResizeObserver 重构版）](./docs/architecture.md)
254
- - [系统架构综述](./docs/system-architecture-overview.md)
255
- - [渲染器开发指南](./docs/renderer-development-guide.md)
256
-
257
- ## 许可证
258
-
259
- 本项目采用 MIT 许可证，详情请见 [LICENSE](./LICENSE) 文件。
1
+ <div align="center">
2
+
3
+ English | [简体中文](README_CN.md)
4
+
5
+ # 📈 KLineChartQuant
6
+
7
+ **Crisp Rendering · High Performance · Optimized Interaction**
8
+
9
+ [![npm version](https://img.shields.io/npm/v/@363045841yyt/klinechart.svg?style=flat&color=blue)](https://www.npmjs.com/package/@363045841yyt/klinechart) [![npm downloads](https://img.shields.io/npm/dm/@363045841yyt/klinechart.svg?style=flat&color=green)](https://www.npmjs.com/package/@363045841yyt/klinechart) [![license](https://img.shields.io/npm/l/@363045841yyt/klinechart.svg?style=flat&color=orange)](https://github.com/363045841/klinechart/blob/main/LICENSE) [![demo](https://img.shields.io/badge/Demo-Online-purple?style=flat)](http://8.130.98.164/)
10
+
11
+ [![qq](https://img.shields.io/badge/QQ群-672011965-blue?style=flat)](https://qm.qq.com/q/672011965) [![tg](https://img.shields.io/badge/Telegram-Join-26A5E4?style=flat&logo=telegram)](https://t.me/+1o-6B-wVRTU2MjQ9)
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ A lightweight financial K-line charting library focused on quantitative trading scenarios. **Agent is a first-class citizen** — supports AI Agent direct control of chart operations, providing TradingView-level interaction experience.
18
+
19
+ <div align="center">
20
+ <img src="https://files.seeusercontent.com/2026/05/13/vF8x/pasted-image-1778672929115.webp" width="400" style="border-radius: 12px; margin: 8px;" />
21
+ <img src="https://files.seeusercontent.com/2026/05/13/J8xd/pasted-image-1778672926979.webp" width="400" style="border-radius: 12px; margin: 8px;" />
22
+ <br/>
23
+ <img src="https://files.seeusercontent.com/2026/05/13/vV4u/pasted-image-1778672925611.webp" width="400" style="border-radius: 12px; margin: 8px;" />
24
+ <img src="https://files.seeusercontent.com/2026/05/13/Vyy8/pasted-image-1778672923956.webp" width="400" style="border-radius: 12px; margin: 8px;" />
25
+ </div>
26
+
27
+ ## ✨ Core Features
28
+
29
+ - **Agent First** - Supports AI Agent direct control of charts, zoom, pan, and draw operations can all be called programmatically
30
+ - **Crisp Rendering** - Full-chain ResizeObserver driven, physical pixel alignment, K-lines, wicks, and lines are sharp and clear on all DPR screens
31
+ - **Plugin Architecture** - Renderer plugin-based design, supporting dynamic registration, configuration, and lifecycle management
32
+ - **Custom Markers** - Supports semantic configuration of custom markers and custom information
33
+ - **High Performance** - Smoothly handles tens of thousands of data points, no lag during zoom or pan
34
+ - **Optimized Interaction** - Stable zoom anchor, precise crosshair cursor, smooth drag
35
+
36
+ ## 🚀 Quick Start
37
+
38
+ ### Prerequisites
39
+
40
+ KLineChart requires a stock data backend. Please ensure `kmap` and `stockbao` are in the same directory:
41
+
42
+ ```
43
+ workspace/
44
+ ├── kmap/ # This repository
45
+ └── stockbao/ # Data backend repository
46
+ ```
47
+
48
+ ### 1. Clone Repositories
49
+
50
+ ```bash
51
+ git clone https://github.com/363045841/kmap.git
52
+ git clone https://github.com/363045841/stockbao.git
53
+ ```
54
+
55
+ ### 2. Start Data Backend
56
+
57
+ ```bash
58
+ cd kmap
59
+ npm run stockbao
60
+ ```
61
+
62
+ After startup, the API is available at `http://localhost:8000`
63
+
64
+ ### 3. Install and Use
65
+
66
+ ```bash
67
+ npm install @363045841yyt/klinechart
68
+ ```
69
+
70
+ ```vue
71
+ <script setup lang="ts">
72
+ import KLineChart from '@363045841yyt/klinechart';
73
+ import type { SemanticChartConfig } from '@363045841yyt/klinechart';
74
+
75
+ const config: SemanticChartConfig = {
76
+ version: '1.0.0',
77
+ data: {
78
+ source: 'baostock',
79
+ code: 'sh.000001',
80
+ startDate: '2024-01-01',
81
+ endDate: '2024-12-31',
82
+ frequency: 'day'
83
+ },
84
+ indicators: {
85
+ main: [{ type: 'MA', params: [5, 10, 20] }],
86
+ sub: [{ type: 'MACD' }]
87
+ }
88
+ };
89
+ </script>
90
+
91
+ <template>
92
+ <KLineChart
93
+ :semanticConfig="config"
94
+ :kWidth="7"
95
+ :kGap="3"
96
+ :yPaddingPx="24"
97
+ />
98
+ </template>
99
+ ```
100
+
101
+ ## 📖 More Documentation
102
+
103
+ - [Rendering Engine Architecture](./docs/rendering-engine-architecture.md) - Core rendering pipeline and physical pixel alignment mechanism
104
+ - [Plugin System](./docs/PLUGIN_SYSTEM.md) - Extension mechanism and custom development
105
+ - [Renderer Development Guide](./docs/renderer-development-guide.md) - Custom renderer development
106
+
107
+ ## 🗺️ Roadmap
108
+
109
+ - [x] K-line zoom anchor stability, improved zoom feel
110
+ - [x] Right axis detached from scroll container, completely solving clipping issues
111
+ - [x] Blank area drawing support
112
+ - [x] Limit vertical pan range to prevent viewport from leaving data
113
+ - [x] Drawing system
114
+ - [x] Right axis zoom
115
+ - [x] Latest price line and right axis label style optimization
116
+ - [ ] Area primitive tools and rendering
117
+ - [ ] More advanced drawing tools
118
+
119
+ ## 🚀 What's New
120
+
121
+ - **v0.5.0** Complete drawing tool system, supporting line, rectangle, text drawing and style editing
122
+ - **v0.4** Modern UI, left toolbar, right axis optimization, TradingView-style zoom feel
123
+
124
+ ## 📄 License
125
+
126
+ [MIT](LICENSE)