@363045841yyt/klinechart-core 0.7.3

package/src/engine/layout/pane.ts

@@ -0,0 +1,161 @@
+import type { KLineData } from '../../types/price'
+import { getVisiblePriceRange } from '../viewport/viewport'
+import type { PriceRange } from '../scale/price'
+import { PriceScale } from '../scale/priceScale'
+import type { MarkerManager } from '../marker/registry'
+import type { PaneCapabilities, PaneRole } from '../../plugin'
+
+/**
+ * 更新级别枚举 - 用于双层 Canvas 架构
+ * Main: 只更新主画布（K线、指标等静态内容）
+ * Overlay: 只更新覆盖层（十字线、Tooltip等动态内容）
+ * All: 更新所有层
+ */
+export enum UpdateLevel {
+  Main = 'main',
+  Overlay = 'overlay',
+  All = 'all'
+}
+
+export type VisibleRange = { start: number; end: number }
+
+export interface PaneInitOptions {
+  role?: PaneRole
+  capabilities?: Partial<PaneCapabilities>
+}
+
+function defaultCapabilitiesByRole(role: PaneRole): PaneCapabilities {
+  if (role === 'price') {
+    return {
+      showPriceAxisTicks: true,
+      showCrosshairPriceLabel: true,
+      candleHitTest: true,
+      supportsPriceTranslate: true,
+    }
+  }
+  if (role === 'indicator') {
+    return {
+      showPriceAxisTicks: false,
+      showCrosshairPriceLabel: true,
+      candleHitTest: false,
+      supportsPriceTranslate: true,
+    }
+  }
+  return {
+    showPriceAxisTicks: false,
+    showCrosshairPriceLabel: false,
+    candleHitTest: false,
+    supportsPriceTranslate: false,
+  }
+}
+
+/**
+ * Pane 级渲染器接口：在单个 pane 的坐标系中绘制内容
+ */
+export interface PaneRenderer {
+  /**
+   * 在指定 pane 坐标系中绘制内容
+   * @param ctx Canvas 绘图上下文，Chart 已执行 translate(0, pane.top)，y=0 对应 pane 顶部
+   * @param pane 当前 pane 实例
+   * @param data 全量 K 线数据
+   * @param range 当前视口可见的索引范围
+   * @param scrollLeft 滚动偏移量，renderer 内部如需 world 坐标需执行 ctx.translate(-scrollLeft, 0)
+   * @param kWidth K 线宽度
+   * @param kGap K 线间隔
+   * @param dpr 设备像素比
+   * @param paneWidth pane 宽度
+   * @param kLinePositions 可选，K 线起始 x 坐标数组（由 Chart 统一计算）
+   */
+  draw(args: {
+    ctx: CanvasRenderingContext2D
+    pane: Pane
+    data: KLineData[]
+    range: VisibleRange
+    scrollLeft: number
+    kWidth: number
+    kGap: number
+    dpr: number
+    paneWidth: number
+    kLinePositions: number[]
+    markerManager?: MarkerManager
+  }): void
+}
+
+/**
+ * Pane：代表一个"窗口区域"（主图 / 副图）
+ */
+export class Pane {
+  readonly id: string
+  readonly role: PaneRole
+  readonly capabilities: PaneCapabilities
+  top = 0
+  height = 0
+
+  /** 当前 pane 的可视价格范围（用于右侧轴、以及渲染器内部） */
+  priceRange: PriceRange = { maxPrice: 100, minPrice: 0 }
+
+  /** pane 独立 Y 轴 */
+  readonly yAxis = new PriceScale()
+
+  /** 该 pane 的渲染器列表 */
+  readonly renderers: PaneRenderer[] = []
+
+  /**
+   * 创建 pane 实例
+   * @param id pane 标识符（例如 'main'、'sub'），用于在 Chart/Interaction 中识别 pane
+   */
+  constructor(id: string, options: PaneInitOptions = {}) {
+    this.id = id
+    this.role = options.role ?? (id === 'main' ? 'price' : 'indicator')
+    this.capabilities = {
+      ...defaultCapabilitiesByRole(this.role),
+      ...(options.capabilities ?? {}),
+    }
+  }
+
+  /**
+   * 设置 pane 的垂直布局
+   * @param top 相对 plotCanvas 顶部的偏移（逻辑像素）
+   * @param height pane 高度（逻辑像素）
+   */
+  setLayout(top: number, height: number) {
+    this.top = top
+    this.height = Math.max(1, height)
+    this.yAxis.setHeight(this.height)
+  }
+
+  /**
+   * 设置 Y 轴上下 padding
+   * @param top 上内边距，影响 priceToY 映射的顶部留白
+   * @param bottom 下内边距，影响 priceToY 映射的底部留白
+   */
+  setPadding(top: number, bottom: number) {
+    this.yAxis.setPadding(top, bottom)
+  }
+
+  /**
+   * 注册一个 pane 级渲染器
+   * @param renderer pane 级渲染器实例
+   */
+  addRenderer(renderer: PaneRenderer) {
+    this.renderers.push(renderer)
+  }
+
+  /**
+   * 根据当前可见索引区间更新 priceRange 并同步到 yAxis
+   * @param data 全量 K 线数据
+   * @param range 当前视口可见的索引范围（由 getVisibleRange 计算）
+   * @param indicatorRange 可选的指标极值范围，与K线极值合并
+   */
+  updateRange(data: KLineData[], range: VisibleRange, indicatorRange?: { min: number; max: number } | null) {
+    this.priceRange = getVisiblePriceRange(data, range.start, range.end)
+
+    // 如果有指标极值，合并到价格范围
+    if (indicatorRange && Number.isFinite(indicatorRange.min) && Number.isFinite(indicatorRange.max)) {
+      this.priceRange.minPrice = Math.min(this.priceRange.minPrice, indicatorRange.min)
+      this.priceRange.maxPrice = Math.max(this.priceRange.maxPrice, indicatorRange.max)
+    }
+
+    this.yAxis.setRange(this.priceRange)
+  }
+}

package/src/engine/marker/registry.ts

@@ -0,0 +1,266 @@
+import { hitTestShape } from '../../semantic/drawShape'
+
+/**
+ * 标记类型
+ */
+export type MarkerShape = 'triangle' | 'circle'
+
+/**
+ * 标记状态
+ */
+export type MarkerState = 'normal' | 'hovered'
+
+/**
+ * 标记类型描述注册表
+ */
+export const MARKER_TYPE_DESCRIPTIONS: Record<string, string> = {
+    'RISE_WITH_VOLUME': '量价齐升',
+    'RISE_WITHOUT_VOLUME': '量缩价升',
+    'FALL_WITH_VOLUME': '量价齐缩',
+    'FALL_WITHOUT_VOLUME': '量升价缩',
+}
+
+/**
+ * 注册新的标记类型描述
+ * @param type 标记类型
+ * @param description 描述文本
+ */
+export function registerMarkerTypeDescription(type: string, description: string): void {
+    MARKER_TYPE_DESCRIPTIONS[type] = description
+}
+
+/**
+ * 标记实体
+ */
+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 class MarkerManager {
+    /** 当前帧可见的标记集合（key: marker.id） */
+    private markers: Map<string, MarkerEntity> = new Map()
+    /** 当前 hover 的标记 ID（跨帧持久） */
+    private hoveredMarkerId: string | null = null
+    /** 上一帧 hover 的标记 ID（用于触发 enter/leave 事件） */
+    private lastHoveredId: string | null = null
+
+    // ============ 自定义标记状态管理 ============
+    /** 自定义标记集合 */
+    private customMarkers: Map<string, CustomMarkerEntity> = new Map()
+    /** 自定义标记位置缓存（用于 hitTest） */
+    private customMarkerPositions: Map<string, { x: number; y: number; size: number; shape: CustomMarkerShape }> = new Map()
+
+    /**
+     * 清空标记集合
+     * 注意：不清除 hoveredMarkerId，保持 hover 状态跨帧持久
+     */
+    clear(): void {
+        this.markers.clear()
+    }
+
+    /**
+     * 注册标记
+     * @param marker 标记实体
+     */
+    register(marker: MarkerEntity): void {
+        this.markers.set(marker.id, marker)
+    }
+
+    /**
+     * 获取标记状态
+     * @param id 标记 ID
+     * @returns 'hovered' 或 'normal'
+     */
+    getState(id: string): MarkerState {
+        if (this.hoveredMarkerId === id) {
+            return 'hovered'
+        }
+        return 'normal'
+    }
+
+    /**
+     * 命中测试
+     * @param x 鼠标 x 坐标
+     * @param y 鼠标 y 坐标
+     * @param padding 命中区域扩展（默认 3px）
+     * @returns 命中的标记，未命中返回 null
+     */
+    hitTest(x: number, y: number, padding: number = 3): MarkerEntity | null {
+        for (const marker of this.markers.values()) {
+            if (x >= marker.x - padding && x <= marker.x + marker.width + padding &&
+                y >= marker.y - padding && y <= marker.y + marker.height + padding
+            ) {
+                return marker
+            }
+        }
+        return null
+    }
+
+    /**
+     * 设置 hover 状态
+     * @param id 标记 ID，null 表示清除 hover
+     */
+    setHover(id: string | null): void {
+        this.hoveredMarkerId = id
+        this.lastHoveredId = id
+    }
+
+    /**
+     * 验证 hover 状态
+     * 检查当前 hover 的标记是否仍在视口内，不在则清除
+     */
+    validateHoverState(): void {
+        if (this.hoveredMarkerId !== null && !this.markers.has(this.hoveredMarkerId)) {
+            this.hoveredMarkerId = null
+        }
+    }
+
+    /**
+     * 获取当前 hover 的标记实体
+     * @returns hover 的标记，不存在返回 null
+     */
+    getHoveredMarker(): MarkerEntity | null {
+        if (this.hoveredMarkerId !== null) {
+            return this.markers.get(this.hoveredMarkerId) || null
+        }
+        return null
+    }
+
+    /**
+     * 获取上一帧 hover 的标记 ID
+     * 用于检测 hover 状态变化
+     * @returns 上一帧的 hover ID
+     */
+    getLastHoverId(): string | null {
+        return this.lastHoveredId
+    }
+
+    /**
+     * 获取所有当前可见的标记
+     * @returns 标记数组
+     */
+    getAllMarkers(): MarkerEntity[] {
+        return Array.from(this.markers.values())
+    }
+
+    // ============ 自定义标记管理方法 ============
+
+    /**
+     * 注册自定义标记
+     */
+    registerCustomMarker(marker: CustomMarkerEntity): void {
+        this.customMarkers.set(marker.id, marker)
+    }
+
+    /**
+     * 批量设置自定义标记
+     */
+    setCustomMarkers(markers: CustomMarkerEntity[]): void {
+        this.clearCustomMarkers()
+        for (const marker of markers) {
+            this.customMarkers.set(marker.id, marker)
+        }
+    }
+
+    /**
+     * 清空自定义标记（含位置缓存）
+     */
+    clearCustomMarkers(): void {
+        this.customMarkers.clear()
+        this.customMarkerPositions.clear()
+    }
+
+    /**
+     * 获取所有自定义标记
+     */
+    getCustomMarkers(): CustomMarkerEntity[] {
+        return Array.from(this.customMarkers.values())
+    }
+
+    /**
+     * 记录自定义标记位置（render 时调用）
+     */
+    setCustomMarkerPosition(id: string, x: number, y: number, size: number, shape: CustomMarkerShape): void {
+        this.customMarkerPositions.set(id, { x, y, size, shape })
+    }
+
+    /**
+     * 自定义标记点击测试
+     * @param x 鼠标 x 坐标
+     * @param y 鼠标 y 坐标
+     * @returns 命中的自定义标记，未命中返回 null
+     */
+    hitTestCustomMarker(x: number, y: number): CustomMarkerEntity | null {
+        for (const marker of this.customMarkers.values()) {
+            const pos = this.customMarkerPositions.get(marker.id)
+            if (pos) {
+                // 使用实际渲染的大小进行命中测试
+                if (hitTestShape(x, y, pos.shape, pos.x, pos.y, pos.size)) {
+                    return marker
+                }
+            }
+        }
+        return null
+    }
+}

package/src/engine/paneRenderer.ts

@@ -0,0 +1,169 @@
+import { CandleWebGLSurface, LineWebGLSurface } from './renderers/webgl/candleSurface'
+import type { SharedWebGLSurface, WebGLRegion } from './renderers/webgl/sharedWebGLSurface'
+
+export type PaneRendererDom = {
+    mainCanvas: HTMLCanvasElement      // 主画布：K线、指标、网格
+    overlayCanvas: HTMLCanvasElement   // 覆盖层：十字线、Tooltip（透明）
+    yAxisCanvas: HTMLCanvasElement     // Y轴刻度
+}
+
+export type PaneRendererContexts = {
+    mainCtx: CanvasRenderingContext2D | null
+    overlayCtx: CanvasRenderingContext2D | null
+    yAxisCtx: CanvasRenderingContext2D | null
+}
+
+export type PaneRendererOptions = {
+    rightAxisWidth: number
+    yPaddingPx: number
+    priceLabelWidth?: number
+}
+
+export type PaneRendererWebGLHandles = {
+    candleSurface: CandleWebGLSurface | null
+    lineSurface: LineWebGLSurface | null
+}
+
+/* PaneRenderer：负责单个 Pane 的 Canvas 管理与运行时状态持有
+   创建并管理 mainCanvas / overlayCanvas / yAxisCanvas
+   持有 Pane 实例（布局、Y 轴、价格范围）
+   响应 Chart 的 resize / layout 信号
+   渲染逻辑由 RendererPluginManager 统一调度 */
+export class PaneRenderer {
+    private dom: PaneRendererDom
+    private pane: import('./layout/pane').Pane
+    private opt: PaneRendererOptions
+    private contexts: PaneRendererContexts | null = null
+    private webgl: PaneRendererWebGLHandles
+
+    constructor(
+        dom: PaneRendererDom,
+        pane: import('./layout/pane').Pane,
+        opt: PaneRendererOptions,
+        sharedWebGLSurface: SharedWebGLSurface,
+    ) {
+        this.dom = dom
+        this.pane = pane
+        this.opt = {
+            ...opt,
+            priceLabelWidth: opt.priceLabelWidth || 60,
+        }
+        this.webgl = {
+            candleSurface: new CandleWebGLSurface(sharedWebGLSurface),
+            lineSurface: new LineWebGLSurface(sharedWebGLSurface),
+        }
+    }
+
+    /** 获取关联的 Pane 实例 */
+    getPane(): import('./layout/pane').Pane {
+        return this.pane
+    }
+
+    /** 获取 DOM 元素 */
+    getDom(): PaneRendererDom {
+        return this.dom
+    }
+
+    getContexts(): PaneRendererContexts {
+        if (!this.contexts) {
+            this.contexts = {
+                mainCtx: this.dom.mainCanvas.getContext('2d'),
+                overlayCtx: this.dom.overlayCanvas.getContext('2d'),
+                yAxisCtx: this.dom.yAxisCanvas.getContext('2d'),
+            }
+        }
+        return this.contexts
+    }
+
+    getWebGL(): PaneRendererWebGLHandles {
+        return this.webgl
+    }
+
+    setWebGLRegion(region: WebGLRegion): void {
+        this.webgl.candleSurface?.setRegion(region)
+        this.webgl.lineSurface?.setRegion(region)
+    }
+
+    /**
+     * 调整 Canvas 尺寸
+     * @param width pane 宽度（逻辑像素）
+     * @param height pane 高度（逻辑像素）
+     * @param dpr 设备像素比
+     */
+    resize(width: number, height: number, dpr: number) {
+        const mainCanvas = this.dom.mainCanvas
+        const overlayCanvas = this.dom.overlayCanvas
+        const yAxisCanvas = this.dom.yAxisCanvas
+
+        // 先读取 parentClientWidth，避免在写入样式后读取触发强制回流
+        const fallbackYAxisWidth = this.opt.rightAxisWidth + (this.opt.priceLabelWidth || 60)
+        const parentClientWidth = yAxisCanvas.parentElement?.clientWidth ?? 0
+        const canvasYAxisWidth = parentClientWidth > 0 ? parentClientWidth : fallbackYAxisWidth
+
+        // Main Canvas
+        const mainWidth = Math.round(width * dpr)
+        if (mainCanvas.width !== mainWidth) {
+            mainCanvas.width = mainWidth
+        }
+
+        const mainHeight = Math.round(height * dpr)
+        if (mainCanvas.height !== mainHeight) {
+            mainCanvas.height = mainHeight
+        }
+
+        const mainCssWidth = `${mainWidth / dpr}px`
+        if (mainCanvas.style.width !== mainCssWidth) {
+            mainCanvas.style.width = mainCssWidth
+        }
+
+        const mainCssHeight = `${mainHeight / dpr}px`
+        if (mainCanvas.style.height !== mainCssHeight) {
+            mainCanvas.style.height = mainCssHeight
+        }
+
+        // Overlay Canvas - 与 Main Canvas 相同尺寸
+        if (overlayCanvas.width !== mainWidth) {
+            overlayCanvas.width = mainWidth
+        }
+        if (overlayCanvas.height !== mainHeight) {
+            overlayCanvas.height = mainHeight
+        }
+        if (overlayCanvas.style.width !== mainCssWidth) {
+            overlayCanvas.style.width = mainCssWidth
+        }
+        if (overlayCanvas.style.height !== mainCssHeight) {
+            overlayCanvas.style.height = mainCssHeight
+        }
+
+        // YAxis Canvas
+        const yAxisWidth = Math.round(canvasYAxisWidth * dpr)
+        if (yAxisCanvas.width !== yAxisWidth) {
+            yAxisCanvas.width = yAxisWidth
+        }
+
+        const yAxisHeight = Math.round(height * dpr)
+        if (yAxisCanvas.height !== yAxisHeight) {
+            yAxisCanvas.height = yAxisHeight
+        }
+
+        const yAxisCssWidth = `${yAxisWidth / dpr}px`
+        if (yAxisCanvas.style.width !== yAxisCssWidth) {
+            yAxisCanvas.style.width = yAxisCssWidth
+        }
+
+        const yAxisCssHeight = `${yAxisHeight / dpr}px`
+        if (yAxisCanvas.style.height !== yAxisCssHeight) {
+            yAxisCanvas.style.height = yAxisCssHeight
+        }
+
+        this.webgl.candleSurface?.resize(width, height, dpr)
+        this.webgl.lineSurface?.resize(width, height, dpr)
+    }
+
+    /** 销毁 PaneRenderer 实例 */
+    destroy() {
+        this.contexts = null
+        this.webgl.candleSurface?.destroy()
+        this.webgl.lineSurface?.destroy()
+    }
+}