@363045841yyt/klinechart 0.1.4 → 0.2.0

package/dist/core/chart.d.ts

@@ -1,7 +1,12 @@
 import { KLineData } from '../types/price';
-import { Pane, VisibleRange } from './layout/pane';
+import { VisibleRange } from './layout/pane';
 import { InteractionController } from './controller/interaction';
 import { PaneRenderer } from './paneRenderer';
+import { MarkerManager, CustomMarkerEntity } from './marker/registry';
+import { getPhysicalKLineConfig, calcKWidthPx } from './utils/klineConfig';
+import { PluginHostImpl, RendererPlugin, RendererPluginWithHost } from '../plugin';
+import { SubIndicatorType } from './renderers/Indicator';
+export { getPhysicalKLineConfig, calcKWidthPx };
 /**
  * 图表 DOM 元素引用
  * @property container 图表容器 div
@@ -19,10 +24,12 @@ export type ChartDom = {
  * Pane 面板配置
  * @property id Pane 标识符
  * @property ratio Pane 高度占比
+ * @property visible 是否可见（默认 true）
  */
 export type PaneSpec = {
     id: string;
     ratio: number;
+    visible?: boolean;
 };
 export type PaneRendererDom = {
     plotCanvas: HTMLCanvasElement;
@@ -42,30 +49,6 @@ export type ChartOptions = {
     /** 价格标签额外宽度（用于显示涨跌幅，默认 60px） */
     priceLabelWidth?: number;
 };
-/**
- * 计算奇数化后的 K 线宽度（物理像素），确保影线能完美居中显示
- * @param kWidth K 线宽度（逻辑像素）
- * @param dpr 设备像素比
- * @returns 奇数化后的物理像素宽度
- */
-export declare function calcKWidthPx(kWidth: number, dpr: number): number;
-/**
- * 获取图表渲染使用的物理像素配置
- * @param kWidth K 线宽度（逻辑像素）
- * @param kGap K 线间隙（逻辑像素）
- * @param dpr 设备像素比
- * @returns 物理像素和逻辑像素的配置对象
- */
-export declare function getPhysicalKLineConfig(kWidth: number, kGap: number, dpr: number): {
-    kWidthPx: number;
-    kGapPx: number;
-    unitPx: number;
-    startXPx: number;
-    kWidthLogical: number;
-    kGapLogical: number;
-    unitLogical: number;
-    startXLogical: number;
-};
 /** K 线起始 x 坐标数组，positions[i] 表示第 i 根 K 线的起始 x 坐标（逻辑像素） */
 export type KLinePositions = number[];
 export type Viewport = {
@@ -83,14 +66,33 @@ export declare class Chart {
     private raf;
     private viewport;
     private paneRenderers;
+    private markerManager;
     readonly interaction: InteractionController;
+    /** 插件宿主 */
+    private pluginHost;
+    /** 渲染器插件管理器 */
+    private rendererPluginManager;
     /**
      * 创建图表实例
      * @param dom 由 Vue 组件传入的 DOM 句柄
      * @param opt 初始配置
      */
     constructor(dom: ChartDom, opt: ChartOptions);
-    /** 绘制一帧完整图表 */
+    /** 获取插件宿主 */
+    get plugin(): PluginHostImpl;
+    /** 安装渲染器插件 */
+    useRenderer(plugin: RendererPlugin | RendererPluginWithHost, config?: Record<string, unknown>): void;
+    /** 移除渲染器插件 */
+    removeRenderer(name: string): void;
+    /** 获取渲染器插件 */
+    getRenderer<T extends RendererPlugin = RendererPlugin>(name: string): T | undefined;
+    /** 更新渲染器配置（自动重绘） */
+    updateRendererConfig(name: string, config: Record<string, unknown>): void;
+    /** 启用/禁用渲染器 */
+    setRendererEnabled(name: string, enabled: boolean): void;
+    /** 获取所有渲染器 */
+    getAllRenderers(): RendererPlugin[];
+    /** 绘制一帧 */
     draw(): void;
     /**
      * 以鼠标位置为中心缩放 K 线，保持鼠标指向的 K 线位置不变
@@ -99,6 +101,13 @@ export declare class Chart {
      * @param deltaY 滚动方向（大于 0 缩小，小于 0 放大）
      */
     zoomAt(mouseX: number, scrollLeft: number, deltaY: number): void;
+    /**
+     * 由外部（Vue 组件）在 scrollLeft 落地后调用，原子性地应用缩放参数
+     * 确保 draw() 看到的 (kWidth, kGap, scrollLeft) 是一致的
+     * @param kWidth 新的 K 线宽度
+     * @param kGap 新的 K 线间隙
+     */
+    applyZoom(kWidth: number, kGap: number): void;
     /** 缩放回调函数，用于通知外部同步 kWidth、kGap 与 scrollLeft */
     private onZoomChange?;
     /**
@@ -108,12 +117,12 @@ export declare class Chart {
     setOnZoomChange(cb: (kWidth: number, kGap: number, targetScrollLeft: number) => void): void;
     /** 获取所有 PaneRenderer */
     getPaneRenderers(): PaneRenderer[];
-    /**
-     * 设置指定 pane 的渲染器链
-     * @param paneId pane 标识（如 'main' 或 'sub'）
-     * @param renderers 渲染器数组
-     */
-    setPaneRenderers(paneId: string, renderers: Pane['renderers']): void;
+    /** 获取 MarkerManager（供 InteractionController 使用） */
+    getMarkerManager(): MarkerManager;
+    /** 更新自定义标记 */
+    updateCustomMarkers(markers: CustomMarkerEntity[]): void;
+    /** 清除自定义标记 */
+    clearCustomMarkers(): void;
     /** 获取 ChartDom（供 InteractionController 使用） */
     getDom(): ChartDom;
     /** 获取当前 ChartOptions（返回内部当前快照） */
@@ -124,25 +133,53 @@ export declare class Chart {
      * @returns x 坐标数组（逻辑像素，经过物理像素对齐）
      */
     calcKLinePositions(range: VisibleRange): KLinePositions;
-    /**
-     * 获取 K 线渲染使用的物理像素配置，确保渲染器和交互逻辑使用一致的坐标计算
-     * @returns 物理像素配置对象
-     */
-    getKLinePhysicalConfig(): {
-        kWidthPx: number;
-        kGapPx: number;
-        unitPx: number;
-        startXPx: number;
-        kWidthLogical: number;
-        kGapLogical: number;
-        unitLogical: number;
-        startXLogical: number;
-    };
     /**
      * 更新配置并触发布局/重绘
      * @param partial 部分配置项
      */
     updateOptions(partial: Partial<ChartOptions>): void;
+    /**
+     * 更新 pane 布局配置
+     * @param panes 新的 pane 配置数组
+     */
+    updatePaneLayout(panes: PaneSpec[]): void;
+    /**
+     * 动态添加 pane
+     * @param paneId pane 标识符
+     */
+    addPane(paneId: string): void;
+    /**
+     * 动态移除 pane
+     * @param paneId pane 标识符
+     */
+    removePane(paneId: string): void;
+    /**
+     * 检查 pane 是否存在
+     * @param paneId pane 标识符
+     */
+    hasPane(paneId: string): boolean;
+    /** 副图渲染器名称前缀 */
+    private static readonly SUB_PANE_PREFIX;
+    /**
+     * 创建副图面板并注册指标渲染器
+     * @param indicatorId 指标类型
+     * @param params 指标参数
+     * @returns 是否创建成功
+     */
+    createSubPane(indicatorId: SubIndicatorType, params?: Record<string, number>): boolean;
+    /**
+     * 移除副图面板及其渲染器
+     * @param indicatorId 指标类型
+     */
+    removeSubPane(indicatorId: SubIndicatorType): void;
+    /**
+     * 清除所有副图面板
+     */
+    clearSubPanes(): void;
+    /**
+     * 获取当前所有副图指标类型
+     */
+    getSubPaneIndicators(): SubIndicatorType[];
     /**
      * 更新数据并请求重绘
      * @param data K 线数据数组
@@ -157,7 +194,7 @@ export declare class Chart {
     /** 请求下一帧重绘（RAF 合并） */
     scheduleDraw(): void;
     /** 销毁图表实例 */
-    destroy(): void;
+    destroy(): Promise<void>;
     /** 初始化所有 pane */
     private initPanes;
     /** 计算每个 pane 的布局（top 和 height） */

package/dist/core/controller/interaction.d.ts

@@ -1,14 +1,19 @@
 import { Chart } from '../chart';
+import { MarkerEntity, CustomMarkerEntity } from '../marker/registry';
+/** 标记 hover 事件数据 */
+export interface MarkerHoverEvent {
+    type: 'volume-price' | 'custom';
+    marker: MarkerEntity | CustomMarkerEntity;
+}
 /**
  * 交互控制器，处理拖拽滚动、缩放、十字线 hover 等交互逻辑
- * 只依赖 Chart 公共 API，不依赖 Vue
  */
 export declare class InteractionController {
     private chart;
     private isDragging;
     private dragStartX;
     private scrollStartX;
-    /** 触摸会话标记，避免触摸触发的模拟 mouse 事件干扰 */
+    /** [触屏]:触摸会话标记，避免触摸触发的模拟 mouse 事件干扰 */
     private isTouchSession;
     /** 十字线位置 */
     crosshairPos: {
@@ -31,21 +36,49 @@ export declare class InteractionController {
         width: number;
         height: number;
     };
+    /** 当前 hover 的 marker ID */
+    hoveredMarkerId: string | null;
+    /** 当前点击的 marker ID */
+    clickedMarkerId: string | null;
+    /** 当前 hover 的 marker 数据（供外部显示 tooltip 使用） */
+    hoveredMarkerData: MarkerEntity | null;
+    /** 当前点击的 marker 数据（供外部显示 tooltip 使用） */
+    clickedMarkerData: MarkerEntity | null;
+    /** marker hover 回调函数 */
+    private onMarkerHoverCallback?;
+    /** marker click 回调函数 */
+    private onMarkerClickCallback?;
+    /** 当前 hover 的自定义标记 */
+    hoveredCustomMarker: CustomMarkerEntity | null;
+    /** 自定义标记 hover 回调 */
+    private onCustomMarkerHoverCallback?;
+    /** 自定义标记 click 回调 */
+    private onCustomMarkerClickCallback?;
     /** 当前帧的 K 线起始 x 坐标数组 */
     private kLinePositions;
     /** 当前帧的可见 K 线索引范围 */
     private visibleRange;
+    /** K 线宽度（物理像素），用于计算 K 线中心偏移 */
+    private kWidthPx;
     constructor(chart: Chart);
     /**
-     * 处理 Pointer 按下事件（支持触屏设备）
+     * 处理滚轮缩放事件
+     * @param e WheelEvent
+     */
+    onWheel(e: WheelEvent): void;
+    /**
+     * [触屏]:处理 Pointer 按下事件
      * @param e PointerEvent
      */
     onPointerDown(e: PointerEvent): void;
     /**
-     * 处理 Pointer 移动事件
-     * @param e PointerEvent
+     * 设置 tooltip 尺寸
+     * @param size 宽高对象
      */
-    onPointerMove(e: PointerEvent): void;
+    setTooltipSize(size: {
+        width: number;
+        height: number;
+    }): void;
     /**
      * 处理 Pointer 抬起事件
      * @param e PointerEvent
@@ -73,29 +106,30 @@ export declare class InteractionController {
     /** 处理滚动事件 */
     onScroll(): void;
     /**
-     * 处理滚轮缩放事件
-     * @param e WheelEvent
-     */
-    onWheel(e: WheelEvent): void;
-    /**
-     * 设置 tooltip 尺寸
-     * @param size 宽高对象
+     * [触屏]:处理 Pointer 移动事件
+     * @param e PointerEvent
      */
-    setTooltipSize(size: {
-        width: number;
-        height: number;
-    }): void;
+    onPointerMove(e: PointerEvent): void;
     /**
      * 设置当前帧的 K 线起始 x 坐标数组和可见范围
      * @param positions K 线起始 x 坐标数组
      * @param visibleRange 可见 K 线索引范围
+     * @param kWidthPx K 线宽度（物理像素）
      */
     setKLinePositions(positions: number[] | null, visibleRange: {
         start: number;
         end: number;
-    } | null): void;
+    } | null, kWidthPx?: number): void;
     /** 检查是否正在拖拽 */
     isDraggingState(): boolean;
+    /** 设置 marker hover 回调 */
+    setOnMarkerHover(callback: (marker: MarkerEntity | null) => void): void;
+    /** 设置 marker click 回调 */
+    setOnMarkerClick(callback: (marker: MarkerEntity) => void): void;
+    /** 设置自定义标记 hover 回调 */
+    setOnCustomMarkerHover(callback: (marker: CustomMarkerEntity | null) => void): void;
+    /** 设置自定义标记 click 回调 */
+    setOnCustomMarkerClick(callback: (marker: CustomMarkerEntity) => void): void;
     /** 清除 hover 状态 */
     private clearHover;
     /**
@@ -109,4 +143,8 @@ export declare class InteractionController {
      * @param clientY 屏幕 y 坐标
      */
     private updateHoverFromPoint;
+    /**
+     * 重置所有交互状态（数据更新时调用）
+     */
+    reset(): void;
 }

package/dist/core/layout/pane.d.ts

@@ -1,6 +1,7 @@
 import { KLineData } from '../../types/price';
 import { PriceRange } from '../scale/price';
 import { PriceScale } from '../scale/priceScale';
+import { MarkerManager } from '../marker/registry';
 export type VisibleRange = {
     start: number;
     end: number;
@@ -33,6 +34,7 @@ export interface PaneRenderer {
         dpr: number;
         paneWidth: number;
         kLinePositions: number[];
+        markerManager?: MarkerManager;
     }): void;
 }
 /**

package/dist/core/marker/registry.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 标记类型
+ */
+export type MarkerShape = 'triangle' | 'circle';
+/**
+ * 标记状态
+ */
+export type MarkerState = 'normal' | 'hovered';
+/**
+ * 标记类型描述注册表
+ */
+export declare const MARKER_TYPE_DESCRIPTIONS: Record<string, string>;
+/**
+ * 注册新的标记类型描述
+ * @param type 标记类型
+ * @param description 描述文本
+ */
+export declare function registerMarkerTypeDescription(type: string, description: string): void;
+/**
+ * 标记实体
+ */
+export interface MarkerEntity {
+    id: string;
+    type: MarkerShape;
+    /** 标记类型描述 */
+    markerType: string;
+    /** 包围盒左上角 x 坐标 */
+    x: number;
+    /** 包围盒左上角 y 坐标 */
+    y: number;
+    /** 包围盒宽度 */
+    width: number;
+    /** 包围盒高度 */
+    height: number;
+    /** 对应的 K 线索引 */
+    dataIndex: number;
+    /** 额外元数据（如量价关系类型等） */
+    metadata: Record<string, any>;
+}
+/** 自定义标记形状 */
+export type CustomMarkerShape = 'arrow_up' | 'arrow_down' | 'flag' | 'circle' | 'rectangle' | 'diamond';
+/** 自定义标记样式 */
+export interface CustomMarkerStyle {
+    fillColor?: string;
+    strokeColor?: string;
+    textColor?: string;
+    size?: number;
+    lineWidth?: number;
+    opacity?: number;
+}
+/** 自定义标记标签 */
+export interface CustomMarkerLabel {
+    text: string;
+    position?: 'left' | 'right' | 'top' | 'bottom' | 'inside';
+    align?: 'start' | 'center' | 'end';
+    fontSize?: number;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+}
+/** 自定义标记实体 */
+export interface CustomMarkerEntity {
+    id: string;
+    /**
+     * 日期时间字符串
+     * - 日K/周K/月K: "YYYY-MM-DD"
+     * - 分钟K: "YYYY-MM-DD HH:mm"
+     */
+    date: string;
+    /** Unix 毫秒时间戳（由 date 解析生成，用于二分查找） */
+    timestamp: number;
+    shape: CustomMarkerShape;
+    groupKey?: string;
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    style?: CustomMarkerStyle;
+    label?: CustomMarkerLabel;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 标记 Manager
+ */
+export declare class MarkerManager {
+    /** 当前帧可见的标记集合（key: marker.id） */
+    private markers;
+    /** 当前 hover 的标记 ID（跨帧持久） */
+    private hoveredMarkerId;
+    /** 上一帧 hover 的标记 ID（用于触发 enter/leave 事件） */
+    private lastHoveredId;
+    /** 自定义标记集合 */
+    private customMarkers;
+    /** 自定义标记位置缓存（用于 hitTest） */
+    private customMarkerPositions;
+    /**
+     * 清空标记集合
+     * 注意：不清除 hoveredMarkerId，保持 hover 状态跨帧持久
+     */
+    clear(): void;
+    /**
+     * 注册标记
+     * @param marker 标记实体
+     */
+    register(marker: MarkerEntity): void;
+    /**
+     * 获取标记状态
+     * @param id 标记 ID
+     * @returns 'hovered' 或 'normal'
+     */
+    getState(id: string): MarkerState;
+    /**
+     * 命中测试
+     * @param x 鼠标 x 坐标
+     * @param y 鼠标 y 坐标
+     * @param padding 命中区域扩展（默认 3px）
+     * @returns 命中的标记，未命中返回 null
+     */
+    hitTest(x: number, y: number, padding?: number): MarkerEntity | null;
+    /**
+     * 设置 hover 状态
+     * @param id 标记 ID，null 表示清除 hover
+     */
+    setHover(id: string | null): void;
+    /**
+     * 验证 hover 状态
+     * 检查当前 hover 的标记是否仍在视口内，不在则清除
+     */
+    validateHoverState(): void;
+    /**
+     * 获取当前 hover 的标记实体
+     * @returns hover 的标记，不存在返回 null
+     */
+    getHoveredMarker(): MarkerEntity | null;
+    /**
+     * 获取上一帧 hover 的标记 ID
+     * 用于检测 hover 状态变化
+     * @returns 上一帧的 hover ID
+     */
+    getLastHoverId(): string | null;
+    /**
+     * 获取所有当前可见的标记
+     * @returns 标记数组
+     */
+    getAllMarkers(): MarkerEntity[];
+    /**
+     * 注册自定义标记
+     */
+    registerCustomMarker(marker: CustomMarkerEntity): void;
+    /**
+     * 批量设置自定义标记
+     */
+    setCustomMarkers(markers: CustomMarkerEntity[]): void;
+    /**
+     * 清空自定义标记（含位置缓存）
+     */
+    clearCustomMarkers(): void;
+    /**
+     * 获取所有自定义标记
+     */
+    getCustomMarkers(): CustomMarkerEntity[];
+    /**
+     * 记录自定义标记位置（render 时调用）
+     */
+    setCustomMarkerPosition(id: string, x: number, y: number, size: number, shape: CustomMarkerShape): void;
+    /**
+     * 自定义标记点击测试
+     * @param x 鼠标 x 坐标
+     * @param y 鼠标 y 坐标
+     * @returns 命中的自定义标记，未命中返回 null
+     */
+    hitTestCustomMarker(x: number, y: number): CustomMarkerEntity | null;
+}

package/dist/core/paneRenderer.d.ts

@@ -1,5 +1,3 @@
-import { KLineData } from '../types/price';
-import { Pane, VisibleRange } from './layout/pane';
 export type PaneRendererDom = {
     plotCanvas: HTMLCanvasElement;
     yAxisCanvas: HTMLCanvasElement;
@@ -8,29 +6,19 @@ export type PaneRendererOptions = {
     rightAxisWidth: number;
     yPaddingPx: number;
     priceLabelWidth?: number;
-    isLast?: boolean;
 };
 /**
- * PaneRenderer：负责单个 Pane 的独立渲染
+ * PaneRenderer：负责单个 Pane 的 Canvas 管理
+ * 渲染逻辑由 Chart 通过 RendererPluginManager 统一调度
  */
 export declare class PaneRenderer {
     private dom;
     private pane;
     private opt;
-    /**
-     * 创建 PaneRenderer 实例
-     * @param dom plotCanvas 和 yAxisCanvas DOM 元素
-     * @param pane 关联的 Pane 实例
-     * @param opt 渲染选项
-     */
-    constructor(dom: PaneRendererDom, pane: Pane, opt: PaneRendererOptions);
-    /**
-     * 获取关联的 Pane 实例
-     */
-    getPane(): Pane;
-    /**
-     * 获取 DOM 元素
-     */
+    constructor(dom: PaneRendererDom, pane: import('./layout/pane').Pane, opt: PaneRendererOptions);
+    /** 获取关联的 Pane 实例 */
+    getPane(): import('./layout/pane').Pane;
+    /** 获取 DOM 元素 */
     getDom(): PaneRendererDom;
     /**
      * 调整 Canvas 尺寸
@@ -39,27 +27,6 @@ export declare class PaneRenderer {
      * @param dpr 设备像素比
      */
     resize(width: number, height: number, dpr: number): void;
-    /**
-     * 绘制该 Pane 的内容
-     * @param args 绘制参数，包含 K 线数据、可见范围、滚动位置、K 线尺寸、DPR、十字线位置和标题
-     */
-    draw(args: {
-        data: KLineData[];
-        range: VisibleRange;
-        scrollLeft: number;
-        kWidth: number;
-        kGap: number;
-        dpr: number;
-        crosshairPos?: {
-            x: number;
-            y: number;
-        } | null;
-        crosshairIndex?: number | null;
-        title?: string;
-        kLinePositions: number[];
-    }): void;
-    /**
-     * 销毁 PaneRenderer 实例
-     */
+    /** 销毁 PaneRenderer 实例 */
     destroy(): void;
 }

package/dist/core/renderers/Indicator/boll.d.ts

@@ -0,0 +1,28 @@
+import { RendererPlugin } from '../../../plugin';
+import { KLineData } from '../../../types/price';
+export interface BOLLConfig {
+    /** 周期（默认20） */
+    period?: number;
+    /** 标准差倍数（默认2） */
+    multiplier?: number;
+    /** 是否显示上轨 */
+    showUpper?: boolean;
+    /** 是否显示下轨 */
+    showMiddle?: boolean;
+    /** 是否显示下轨 */
+    showLower?: boolean;
+    /** 是否填充带状区域 */
+    showBand?: boolean;
+}
+/**
+ * 创建 BOLL（布林带）渲染器插件
+ */
+export declare function createBOLLRendererPlugin(initialConfig?: BOLLConfig): RendererPlugin;
+/**
+ * 计算指定索引处的 BOLL 值（供图例使用）
+ */
+export declare function calcBOLLAtIndex(data: KLineData[], index: number, period?: number, multiplier?: number): {
+    upper: number;
+    middle: number;
+    lower: number;
+} | null;

package/dist/core/renderers/Indicator/bollLegend.d.ts

@@ -0,0 +1,16 @@
+import { RendererPlugin } from '../../../plugin';
+export interface BOLLLegendConfig {
+    /** 周期（默认20） */
+    period?: number;
+    /** 标准差倍数（默认2） */
+    multiplier?: number;
+    /** 是否显示图例 */
+    show?: boolean;
+}
+/**
+ * 创建 BOLL 图例渲染器插件
+ */
+export declare function createBOLLLegendRendererPlugin(options: {
+    yPaddingPx: number;
+    config?: BOLLLegendConfig;
+}): RendererPlugin;

package/dist/core/renderers/Indicator/cci.d.ts

@@ -0,0 +1,34 @@
+import { RendererPlugin } from '../../../plugin';
+import { KLineData } from '../../../types/price';
+export interface CCIConfig {
+    /** 周期（默认 14） */
+    period?: number;
+    /** 是否显示 CCI 线 */
+    showCCI?: boolean;
+}
+export interface CCIRendererOptions {
+    /** 目标 pane ID（默认 'sub'） */
+    paneId?: string;
+    /** 初始配置 */
+    config?: CCIConfig;
+}
+/**
+ * 创建 CCI 渲染器插件
+ */
+export declare function createCCIRendererPlugin(options?: CCIRendererOptions): RendererPlugin;
+/**
+ * 计算指定索引处的 CCI 值
+ */
+export declare function calcCCIAtIndex(data: KLineData[], index: number, period: number): number | undefined;
+/**
+ * 获取 CCI 标题信息（供 paneTitle 使用）
+ */
+export declare function getCCITitleInfo(data: KLineData[], index: number, period?: number): {
+    name: string;
+    params: number[];
+    values: Array<{
+        label: string;
+        value: number;
+        color: string;
+    }>;
+} | null;