@363045841yyt/klinechart-core 0.7.3

package/src/engine/controller/markerInteraction.ts

@@ -0,0 +1,130 @@
+import type { MarkerEntity, CustomMarkerEntity, MarkerManager } from '../marker/registry'
+
+/** Marker交互状态，管理标记 hover/click 状态和回调，与 InteractionController 正交。 */
+export class MarkerInteractionState {
+  hoveredMarkerId: string | null = null
+  clickedMarkerId: string | null = null
+  hoveredMarkerData: MarkerEntity | null = null
+  clickedMarkerData: MarkerEntity | null = null
+  hoveredCustomMarker: CustomMarkerEntity | null = null
+
+  private onMarkerHoverCallback?: (marker: MarkerEntity | null) => void
+  private onMarkerClickCallback?: (marker: MarkerEntity) => void
+  private onCustomMarkerHoverCallback?: (marker: CustomMarkerEntity | null) => void
+  private onCustomMarkerClickCallback?: (marker: CustomMarkerEntity) => void
+
+  setOnMarkerHover(callback: (marker: MarkerEntity | null) => void) {
+    this.onMarkerHoverCallback = callback
+  }
+
+  setOnMarkerClick(callback: (marker: MarkerEntity) => void) {
+    this.onMarkerClickCallback = callback
+  }
+
+  setOnCustomMarkerHover(callback: (marker: CustomMarkerEntity | null) => void) {
+    this.onCustomMarkerHoverCallback = callback
+  }
+
+  setOnCustomMarkerClick(callback: (marker: CustomMarkerEntity) => void) {
+    this.onCustomMarkerClickCallback = callback
+  }
+
+  handleClick(hitMarker: MarkerEntity): void {
+    this.clickedMarkerId = hitMarker.id
+    this.clickedMarkerData = hitMarker
+    this.onMarkerClickCallback?.(hitMarker)
+  }
+
+  /** 从坐标更新 hover 状态。返回 true 表示命中 marker/custom-marker，调用方应跳过后续 hover 逻辑。 */
+  updateHoverFromPoint(
+    worldX: number,
+    mouseX: number,
+    mouseY: number,
+    markerManager: MarkerManager,
+  ): boolean {
+    const hitMarker = markerManager.hitTest(worldX, mouseY, 3)
+    if (hitMarker) {
+      return this.enterMarkerHover(hitMarker, markerManager)
+    }
+    this.leaveMarkerHover(markerManager)
+
+    const hitCustomMarker = markerManager.hitTestCustomMarker(mouseX, mouseY)
+    if (hitCustomMarker) {
+      return this.enterCustomMarkerHover(hitCustomMarker, markerManager)
+    }
+    this.leaveCustomMarkerHover()
+
+    return false
+  }
+
+  private enterMarkerHover(hitMarker: MarkerEntity, markerManager: MarkerManager): true {
+    if (this.hoveredMarkerId !== hitMarker.id) {
+      this.hoveredMarkerId = hitMarker.id
+      this.hoveredMarkerData = hitMarker
+      markerManager.setHover(hitMarker.id)
+      this.onMarkerHoverCallback?.(hitMarker)
+    }
+    if (this.hoveredCustomMarker !== null) {
+      this.hoveredCustomMarker = null
+      this.onCustomMarkerHoverCallback?.(null)
+    }
+    return true
+  }
+
+  private leaveMarkerHover(markerManager: MarkerManager): void {
+    if (this.hoveredMarkerId !== null) {
+      this.hoveredMarkerId = null
+      this.hoveredMarkerData = null
+      markerManager.setHover(null)
+      this.onMarkerHoverCallback?.(null)
+    } else {
+      this.hoveredMarkerData = null
+    }
+  }
+
+  private enterCustomMarkerHover(hitCustomMarker: CustomMarkerEntity, markerManager: MarkerManager): true {
+    if (this.hoveredCustomMarker?.id !== hitCustomMarker.id) {
+      this.hoveredCustomMarker = hitCustomMarker
+      this.onCustomMarkerHoverCallback?.(hitCustomMarker)
+    }
+    if (this.hoveredMarkerId !== null) {
+      this.hoveredMarkerId = null
+      this.hoveredMarkerData = null
+      markerManager.setHover(null)
+      this.onMarkerHoverCallback?.(null)
+    }
+    return true
+  }
+
+  private leaveCustomMarkerHover(): void {
+    if (this.hoveredCustomMarker !== null) {
+      this.hoveredCustomMarker = null
+      this.onCustomMarkerHoverCallback?.(null)
+    }
+  }
+
+  /** 清空 hover 状态并触发回调（拖拽/离开时调用）。需要 markerManager 以便同步清除 Native hover。 */
+  clearAll(markerManager: MarkerManager): void {
+    if (this.hoveredMarkerId !== null) {
+      this.hoveredMarkerId = null
+      this.hoveredMarkerData = null
+      markerManager.setHover(null)
+      this.onMarkerHoverCallback?.(null)
+    } else {
+      this.hoveredMarkerData = null
+    }
+    if (this.hoveredCustomMarker !== null) {
+      this.hoveredCustomMarker = null
+      this.onCustomMarkerHoverCallback?.(null)
+    }
+  }
+
+  /** 全量重置（数据更新时调用，不触发热点回调） */
+  reset(): void {
+    this.hoveredMarkerId = null
+    this.clickedMarkerId = null
+    this.hoveredMarkerData = null
+    this.clickedMarkerData = null
+    this.hoveredCustomMarker = null
+  }
+}

package/src/engine/controller/pinchTracker.ts

@@ -0,0 +1,82 @@
+/** 触屏双指捏合跟踪，与 InteractionController 正交。 */
+export class PinchTracker {
+  private activePointers = new Map<number, { x: number; y: number }>()
+  private lastPinchDistance = 0
+  private pinchCenter = { x: 0, y: 0 }
+  private isPinching = false
+  private onPinchZoomCallback?: (delta: number, centerX: number) => void
+
+  setOnPinchZoom(callback: (delta: number, centerX: number) => void) {
+    this.onPinchZoomCallback = callback
+  }
+
+  getIsPinching(): boolean {
+    return this.isPinching
+  }
+
+  getPointerCount(): number {
+    return this.activePointers.size
+  }
+
+  /** Returns true if pinch started (caller should early-return, not process drag). */
+  handlePointerDown(e: PointerEvent, isTouchSession: boolean): boolean {
+    this.activePointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+
+    if (this.activePointers.size === 2 && isTouchSession) {
+      this.isPinching = true
+      const pointers = Array.from(this.activePointers.values())
+      const p1 = pointers[0]!
+      const p2 = pointers[1]!
+      this.lastPinchDistance = Math.hypot(p2.x - p1.x, p2.y - p1.y)
+      this.pinchCenter = { x: (p1.x + p2.x) / 2, y: (p1.y + p2.y) / 2 }
+      return true
+    }
+    return false
+  }
+
+  handlePointerUp(e: PointerEvent): void {
+    this.activePointers.delete(e.pointerId)
+    if (this.isPinching && this.activePointers.size < 2) {
+      this.isPinching = false
+      this.lastPinchDistance = 0
+    }
+  }
+
+  handlePointerLeave(e: PointerEvent): void {
+    this.activePointers.delete(e.pointerId)
+    if (this.activePointers.size < 2) {
+      this.isPinching = false
+      this.lastPinchDistance = 0
+    }
+  }
+
+  /** Returns true if pinch zoom was processed (caller should skip further pointer-move handling). */
+  handlePointerMove(e: PointerEvent): boolean {
+    if (this.activePointers.has(e.pointerId)) {
+      this.activePointers.set(e.pointerId, { x: e.clientX, y: e.clientY })
+    }
+
+    if (this.isPinching && this.activePointers.size === 2) {
+      const pointers = Array.from(this.activePointers.values())
+      const p1 = pointers[0]!
+      const p2 = pointers[1]!
+      const distance = Math.hypot(p2.x - p1.x, p2.y - p1.y)
+      const deltaDistance = distance - this.lastPinchDistance
+
+      if (Math.abs(deltaDistance) > 10) {
+        const pinchDelta = deltaDistance > 0 ? 1 : -1
+        const centerX = (p1.x + p2.x) / 2
+        this.onPinchZoomCallback?.(pinchDelta, centerX)
+        this.lastPinchDistance = distance
+      }
+      return true
+    }
+    return false
+  }
+
+  reset(): void {
+    this.activePointers.clear()
+    this.isPinching = false
+    this.lastPinchDistance = 0
+  }
+}

package/src/engine/controller/tooltipPosition.ts

@@ -0,0 +1,48 @@
+export interface TooltipPositionInput {
+  mouseX: number
+  mouseY: number
+  viewWidth: number
+  viewHeight: number
+  plotWidth: number
+  plotHeight: number
+  tooltipSize: { width: number; height: number }
+  useAnchorPositioning: boolean
+}
+
+export interface TooltipPositionOutput {
+  pos: { x: number; y: number }
+  anchorPlacement?: 'right-bottom' | 'left-bottom'
+}
+
+export function computeTooltipPosition(input: TooltipPositionInput): TooltipPositionOutput {
+  const padding = 12
+  const preferGap = 14
+
+  if (input.useAnchorPositioning) {
+    const tooltipW = input.tooltipSize.width
+    const rightCandidateX = input.mouseX + preferGap
+    const rightWouldOverflow = rightCandidateX + tooltipW + padding > input.plotWidth
+    return {
+      anchorPlacement: rightWouldOverflow ? 'left-bottom' : 'right-bottom',
+      pos: {
+        x: Math.min(Math.max(input.mouseX, padding), Math.max(padding, input.plotWidth - padding)),
+        y: Math.min(Math.max(input.mouseY, padding), Math.max(padding, input.plotHeight - padding)),
+      },
+    }
+  }
+
+  const tooltipW = input.tooltipSize.width
+  const tooltipH = input.tooltipSize.height
+  const rightX = input.mouseX + preferGap
+  const leftX = input.mouseX - preferGap - tooltipW
+  const desiredX = rightX + tooltipW + padding <= input.viewWidth ? rightX : leftX
+  const desiredY = input.mouseY + preferGap
+  const maxX = Math.max(padding, input.viewWidth - tooltipW - padding)
+  const maxY = Math.max(padding, input.viewHeight - tooltipH - padding)
+  return {
+    pos: {
+      x: Math.min(Math.max(desiredX, padding), maxX),
+      y: Math.min(Math.max(desiredY, padding), maxY),
+    },
+  }
+}

package/src/engine/draw/__tests__/pixelAlign.spec.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest'
+import {
+  roundToPhysicalPixel,
+  alignToPhysicalPixelCenter,
+  alignRect,
+  createVerticalLineRect,
+  createHorizontalLineRect,
+} from '../pixelAlign'
+
+describe('roundToPhysicalPixel', () => {
+  it('应该正确对齐到物理像素边界（dpr=1）', () => {
+    expect(roundToPhysicalPixel(0.5, 1)).toBe(1) // 0.5 * 1 = 0.5 -> round(0.5) = 1
+    expect(roundToPhysicalPixel(1.2, 1)).toBe(1) // 1.2 * 1 = 1.2 -> round(1.2) = 1
+    expect(roundToPhysicalPixel(1.8, 1)).toBe(2) // 1.8 * 1 = 1.8 -> round(1.8) = 2
+  })
+
+  it('应该正确对齐到物理像素边界（dpr=2）', () => {
+    expect(roundToPhysicalPixel(0.25, 2)).toBe(0.5) // 0.25 * 2 = 0.5 -> round(0.5) = 1 -> 1/2 = 0.5
+    expect(roundToPhysicalPixel(1.25, 2)).toBe(1.5) // 1.25 * 2 = 2.5 -> round(2.5) = 3 -> 3/2 = 1.5
+    expect(roundToPhysicalPixel(1.75, 2)).toBe(2) // 1.75 * 2 = 3.5 -> round(3.5) = 4 -> 4/2 = 2
+  })
+
+  it('应该正确处理整数', () => {
+    expect(roundToPhysicalPixel(0, 1)).toBe(0)
+    expect(roundToPhysicalPixel(10, 1)).toBe(10)
+    expect(roundToPhysicalPixel(10, 2)).toBe(10)
+  })
+
+  it('应该正确处理负值', () => {
+    expect(roundToPhysicalPixel(-0.5, 1)).toBe(-0) // -0.5 * 1 = -0.5 -> round(-0.5) = -0
+    expect(roundToPhysicalPixel(-1.2, 1)).toBe(-1) // -1.2 * 1 = -1.2 -> round(-1.2) = -1
+    expect(roundToPhysicalPixel(-1.8, 1)).toBe(-2) // -1.8 * 1 = -1.8 -> round(-1.8) = -2
+  })
+})
+
+describe('alignToPhysicalPixelCenter', () => {
+  it('应该正确对齐到物理像素中心（dpr=1）', () => {
+    expect(alignToPhysicalPixelCenter(0, 1)).toBe(0.5) // 0 * 1 = 0 -> floor(0) = 0 -> (0 + 0.5) / 1 = 0.5
+    expect(alignToPhysicalPixelCenter(1, 1)).toBe(1.5) // 1 * 1 = 1 -> floor(1) = 1 -> (1 + 0.5) / 1 = 1.5
+    expect(alignToPhysicalPixelCenter(1.9, 1)).toBe(1.5) // 1.9 * 1 = 1.9 -> floor(1.9) = 1 -> (1 + 0.5) / 1 = 1.5
+  })
+
+  it('应该正确对齐到物理像素中心（dpr=2）', () => {
+    expect(alignToPhysicalPixelCenter(0, 2)).toBe(0.25) // 0 * 2 = 0 -> floor(0) = 0 -> (0 + 0.5) / 2 = 0.25
+    expect(alignToPhysicalPixelCenter(1, 2)).toBe(1.25) // 1 * 2 = 2 -> floor(2) = 2 -> (2 + 0.5) / 2 = 1.25
+    expect(alignToPhysicalPixelCenter(1.9, 2)).toBe(1.75) // 1.9 * 2 = 3.8 -> floor(3.8) = 3 -> (3 + 0.5) / 2 = 1.75
+  })
+
+  it('应该正确处理负值', () => {
+    expect(alignToPhysicalPixelCenter(0, 1)).toBe(0.5)
+    expect(alignToPhysicalPixelCenter(-0.9, 1)).toBe(-0.5) // -0.9 * 1 = -0.9 -> floor(-0.9) = -1 -> (-1 + 0.5) / 1 = -0.5
+    expect(alignToPhysicalPixelCenter(-1.9, 1)).toBe(-1.5) // -1.9 * 1 = -1.9 -> floor(-1.9) = -2 -> (-2 + 0.5) / 1 = -1.5
+  })
+})
+
+describe('alignRect', () => {
+  it('应该正确对齐矩形到物理像素边界（dpr=1）', () => {
+    const result = alignRect(0.5, 0.5, 10.5, 10.5, 1)
+    expect(result.x).toBe(1) // round(0.5) = 1
+    expect(result.y).toBe(1) // round(0.5) = 1
+    expect(result.width).toBe(10) // round(11) - 1 = 10
+    expect(result.height).toBe(10) // round(11) - 1 = 10
+  })
+
+  it('应该正确对齐矩形到物理像素边界（dpr=2）', () => {
+    const result = alignRect(0.25, 0.25, 5.25, 5.25, 2)
+    expect(result.x).toBe(0.5)
+    expect(result.y).toBe(0.5)
+    expect(result.width).toBe(5)
+    expect(result.height).toBe(5)
+  })
+
+  it('应该确保宽度和高度至少为 1/dpr', () => {
+    const result = alignRect(0, 0, 0.1, 0.1, 2)
+    expect(result.width).toBe(0.5) // 1/dpr = 1/2 = 0.5
+    expect(result.height).toBe(0.5)
+  })
+
+  it('应该正确处理负坐标', () => {
+    const result = alignRect(-0.5, -0.5, 10, 10, 1)
+    expect(result.x).toBe(-0) // round(-0.5) = -0
+    expect(result.y).toBe(-0) // round(-0.5) = -0
+    expect(result.width).toBe(10) // round(9.5) - (-0) = 10
+    expect(result.height).toBe(10) // round(9.5) - (-0) = 10
+  })
+})
+
+describe('createVerticalLineRect', () => {
+  it('应该创建1物理像素宽的垂直线矩形（dpr=1）', () => {
+    const result = createVerticalLineRect(10, 0, 20, 1)
+    expect(result).not.toBeNull()
+    expect(result?.x).toBe(10)
+    expect(result?.y).toBe(0)
+    expect(result?.width).toBe(1) // 1/dpr = 1/1 = 1
+    expect(result?.height).toBe(20)
+  })
+
+  it('应该创建1物理像素宽的垂直线矩形（dpr=2）', () => {
+    const result = createVerticalLineRect(10, 0, 20, 2)
+    expect(result).not.toBeNull()
+    expect(result?.x).toBe(10)
+    expect(result?.y).toBe(0)
+    expect(result?.width).toBe(0.5) // 1/dpr = 1/2 = 0.5
+    expect(result?.height).toBe(20)
+  })
+
+  it('应该正确处理反转的y坐标', () => {
+    const result = createVerticalLineRect(10, 20, 0, 1)
+    expect(result?.y).toBe(0)
+    expect(result?.height).toBe(20)
+  })
+
+  it('应该返回null当y1等于y2时', () => {
+    const result = createVerticalLineRect(10, 5, 5, 1)
+    expect(result).toBeNull()
+  })
+
+  it('应该正确对齐到物理像素边界', () => {
+    const result = createVerticalLineRect(10.25, 0, 20, 2)
+    expect(result?.x).toBe(10.5) // 对齐到物理像素边界
+  })
+
+  it('应该确保高度至少为1', () => {
+    const result = createVerticalLineRect(10, 0, 0.5, 1)
+    expect(result?.height).toBe(1)
+  })
+})
+
+describe('createHorizontalLineRect', () => {
+  it('应该创建1物理像素高的水平线矩形（dpr=1）', () => {
+    const result = createHorizontalLineRect(0, 20, 10, 1)
+    expect(result).not.toBeNull()
+    expect(result?.x).toBe(0)
+    expect(result?.y).toBe(10)
+    expect(result?.width).toBe(20)
+    expect(result?.height).toBe(1) // 1/dpr = 1/1 = 1
+  })
+
+  it('应该创建1物理像素高的水平线矩形（dpr=2）', () => {
+    const result = createHorizontalLineRect(0, 20, 10, 2)
+    expect(result).not.toBeNull()
+    expect(result?.x).toBe(0)
+    expect(result?.y).toBe(10)
+    expect(result?.width).toBe(20)
+    expect(result?.height).toBe(0.5) // 1/dpr = 1/2 = 0.5
+  })
+
+  it('应该正确处理反转的x坐标', () => {
+    const result = createHorizontalLineRect(20, 0, 10, 1)
+    expect(result?.x).toBe(0)
+    expect(result?.width).toBe(20)
+  })
+
+  it('应该返回null当x1等于x2时', () => {
+    const result = createHorizontalLineRect(10, 10, 5, 1)
+    expect(result).toBeNull()
+  })
+
+  it('应该正确对齐到物理像素边界', () => {
+    const result = createHorizontalLineRect(0.25, 20.25, 10, 2)
+    expect(result?.x).toBe(0.5) // 对齐到物理像素边界
+    expect(result?.width).toBe(20)
+  })
+
+  it('应该确保宽度至少为1', () => {
+    const result = createHorizontalLineRect(0, 0.5, 10, 1)
+    expect(result?.width).toBe(1)
+  })
+
+  it('应该正确处理小数坐标（dpr=1）', () => {
+    const result = createHorizontalLineRect(1.3, 5.7, 10.2, 1)
+    expect(result?.x).toBe(1) // 1.3 * 1 = 1.3 -> round(1.3) = 1 -> 1/1 = 1
+    expect(result?.width).toBe(5) // left=1.3 -> physLeft=1, right=5.7 -> physRight=6 -> (6-1)/1 = 5
+    expect(result?.y).toBe(10) // 10.2 * 1 = 10.2 -> round(10.2) = 10 -> 10/1 = 10 (对齐到物理像素)
+    expect(result?.height).toBe(1)
+  })
+})

package/src/engine/draw/pixelAlign.ts

@@ -0,0 +1,260 @@
+/**
+ * 像素对齐工具函数 - 逻辑像素空间（配合 ctx.scale(dpr) 使用）
+ */
+
+import { getColors } from '../theme/colors'
+
+/**
+ * 将逻辑坐标对齐到物理像素边界（用于矩形填充）
+ * @param value - 逻辑坐标值
+ * @param dpr - 设备像素比
+ * @returns 对齐后的逻辑坐标
+ */
+export function roundToPhysicalPixel(value: number, dpr: number, theme?: 'light' | 'dark'): number {
+    return Math.round(value * dpr) / dpr
+}
+
+/**
+ * 将逻辑坐标对齐到物理像素中心（用于 1px 线条）
+ * @param value - 逻辑坐标值
+ * @param dpr - 设备像素比
+ * @returns 对齐后的逻辑坐标
+ */
+export function alignToPhysicalPixelCenter(value: number, dpr: number, theme?: 'light' | 'dark'): number {
+    return (Math.floor(value * dpr) + 0.5) / dpr
+}
+
+/**
+ * 对齐矩形到物理像素边界
+ * @param x - 矩形左边界 X 坐标
+ * @param y - 矩形顶部 Y 坐标
+ * @param width - 矩形宽度
+ * @param height - 矩形高度
+ * @param dpr - 设备像素比
+ * @returns 对齐后的矩形信息
+ */
+export function alignRect(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    dpr: number,
+    theme?: 'light' | 'dark'
+): { x: number; y: number; width: number; height: number } {
+    const alignedX = roundToPhysicalPixel(x, dpr)
+    const alignedY = roundToPhysicalPixel(y, dpr)
+    const alignedEndX = roundToPhysicalPixel(x + width, dpr)
+    const alignedEndY = roundToPhysicalPixel(y + height, dpr)
+
+    return {
+        x: alignedX,
+        y: alignedY,
+        width: Math.max(1 / dpr, alignedEndX - alignedX),
+        height: Math.max(1 / dpr, alignedEndY - alignedY),
+    }
+}
+
+/**
+ * 创建用于绘制垂直线的矩形（1 物理像素宽）
+ * @param centerX - 垂直线中心 X 坐标
+ * @param y1 - 垂直线起始点 Y 坐标
+ * @param y2 - 垂直线结束点 Y 坐标
+ * @param dpr - 设备像素比
+ * @returns 对齐到物理像素的矩形信息，如果 y1 和 y2 相等则返回 null
+ */
+export function createVerticalLineRect(
+    centerX: number,
+    y1: number,
+    y2: number,
+    dpr: number,
+    theme?: 'light' | 'dark'
+): { x: number; y: number; width: number; height: number } | null {
+    if (y1 === y2) return null
+
+    const top = Math.min(y1, y2)
+    const bottom = Math.max(y1, y2)
+
+    // 转换到物理像素空间取整，再转回逻辑像素
+    const physX = Math.round(centerX * dpr)
+    const physTop = Math.round(top * dpr)
+    const physBottom = Math.round(bottom * dpr)
+
+    return {
+        x: physX / dpr,
+        y: physTop / dpr,
+        width: 1 / dpr,
+        height: Math.max(1, physBottom - physTop) / dpr,
+    }
+}
+
+/**
+ * 创建用于绘制水平线的矩形（1 物理像素高）
+ * @param x1 - 水平线起始点的 X 坐标
+ * @param x2 - 水平线结束点的 X 坐标
+ * @param centerY - 水平线中心 Y 坐标
+ * @param dpr - 设备像素比
+ * @returns 对齐到物理像素的矩形信息，如果 x1 和 x2 相等则返回 null
+ */
+export function createHorizontalLineRect(
+    x1: number,
+    x2: number,
+    centerY: number,
+    dpr: number,
+    theme?: 'light' | 'dark'
+): { x: number; y: number; width: number; height: number } | null {
+    if (x1 === x2) return null
+
+    const left = Math.min(x1, x2)
+    const right = Math.max(x1, x2)
+
+    const physLeft = Math.round(left * dpr)
+    const physRight = Math.round(right * dpr)
+    const physY = Math.round(centerY * dpr)
+
+    return {
+        x: physLeft / dpr,
+        y: physY / dpr,
+        width: Math.max(1, physRight - physLeft) / dpr,
+        height: 1 / dpr,
+    }
+}
+
+/**
+ * 创建对齐的K线实体和影线
+ * @param rectX - 实体左边界 X 坐标（逻辑像素）
+ * @param rectY - 实体顶部 Y 坐标（逻辑像素）
+ * @param kWidth - 实体宽度（逻辑像素）
+ * @param height - 实体高度（逻辑像素）
+ * @param dpr - 设备像素比
+ * @returns 对齐后的实体和影线信息
+ */
+export function createAlignedKLine(
+    rectX: number,
+    rectY: number,
+    kWidth: number,
+    height: number,
+    dpr: number,
+    theme?: 'light' | 'dark'
+): {
+    bodyRect: { x: number; y: number; width: number; height: number }
+    physBodyLeft: number
+    physBodyRight: number
+    physBodyWidth: number
+    physBodyCenter: number
+    physWickX: number
+    wickRect: { x: number; width: number }
+    isPerfectlyAligned: boolean
+} {
+    // 1. 统一在物理像素空间计算，避免二次round
+    
+    // 1.1 左边界：round到整数像素列
+    const leftPx = Math.round(rectX * dpr)
+    
+    // 1.2 宽度：round到整数，并确保是奇数
+    let widthPx = Math.round(kWidth * dpr)
+    if (widthPx % 2 === 0) {
+        widthPx += 1
+    }
+    widthPx = Math.max(1, widthPx)
+    
+    // 1.3 右边界：由左边界+宽度决定
+    const rightPx = leftPx + widthPx
+    
+    // 1.4 物理宽度
+    const physBodyWidth = widthPx
+    
+    // 2. Y轴对齐
+    const topPx = Math.round(rectY * dpr)
+    const bottomPx = Math.round((rectY + height) * dpr)
+    const heightPx = Math.max(1, bottomPx - topPx)
+    
+    // 3. 计算物理中心和影线位置
+    const physWickX = leftPx + (widthPx - 1) / 2
+    const physBodyCenter = physWickX
+    const isPerfectlyAligned = physBodyWidth % 2 === 1
+    
+    // 4. 返回逻辑像素坐标
+    return {
+        bodyRect: {
+            x: leftPx / dpr,
+            y: topPx / dpr,
+            width: widthPx / dpr,
+            height: heightPx / dpr,
+        },
+        physBodyLeft: leftPx,
+        physBodyRight: rightPx,
+        physBodyWidth,
+        physBodyCenter,
+        physWickX,
+        wickRect: {
+            x: physWickX / dpr,
+            width: 1 / dpr,
+        },
+        isPerfectlyAligned,
+    }
+}
+
+/**
+ * 创建对齐的K线实体和影线（物理像素直接版）
+ * @param leftPx - 实体左边界物理像素坐标（整数）
+ * @param rectY - 实体顶部 Y 坐标（逻辑像素）
+ * @param widthPx - 实体宽度物理像素（奇数）
+ * @param height - 实体高度（逻辑像素）
+ * @param dpr - 设备像素比
+ * @returns 对齐后的实体和影线信息
+ */
+export function createAlignedKLineFromPx(
+    leftPx: number,
+    rectY: number,
+    widthPx: number,
+    height: number,
+    dpr: number,
+    theme?: 'light' | 'dark'
+): {
+    bodyRect: { x: number; y: number; width: number; height: number }
+    physBodyLeft: number
+    physBodyRight: number
+    physBodyWidth: number
+    physBodyCenter: number
+    physWickX: number
+    wickRect: { x: number; width: number }
+    isPerfectlyAligned: boolean
+} {
+    // 1. 物理像素空间计算
+    
+    // 1.1 左边界直接使用传入的整数
+    // 1.2 宽度直接使用传入的奇数
+    // 1.3 右边界由左边界+宽度决定
+    const rightPx = leftPx + widthPx
+    const physBodyWidth = widthPx
+    
+    // 2. Y轴对齐
+    const topPx = Math.round(rectY * dpr)
+    const bottomPx = Math.round((rectY + height) * dpr)
+    const heightPx = Math.max(1, bottomPx - topPx)
+    
+    // 3. 计算影线位置
+    const physWickX = leftPx + (widthPx - 1) / 2
+    const physBodyCenter = physWickX
+    const isPerfectlyAligned = physBodyWidth % 2 === 1
+
+    // 4. 返回逻辑像素坐标
+    return {
+        bodyRect: {
+            x: leftPx / dpr,
+            y: topPx / dpr,
+            width: widthPx / dpr,
+            height: heightPx / dpr,
+        },
+        physBodyLeft: leftPx,
+        physBodyRight: rightPx,
+        physBodyWidth,
+        physBodyCenter,
+        physWickX,
+        wickRect: {
+            x: physWickX / dpr,
+            width: 1 / dpr,
+        },
+        isPerfectlyAligned,
+    }
+}