@363045841yyt/klinechart 0.7.3-alpha.1 → 0.7.3-alpha.3

package/src/components/KLineChart.vue

@@ -146,27 +146,27 @@ import {
 
 const props = withDefaults(
   defineProps<{
-    /** ??????????????? */
+    /** 语义化配置（必需，唯一控制源） */
     semanticConfig: SemanticChartConfig
 
-    /** ??????????????????????????? */
+    /** 数据获取函数（必需）。框架不绑定数据源，由使用者注入。 */
     dataFetcher: DataFetcher
 
     yPaddingPx?: number
     minKWidth?: number
     maxKWidth?: number
-    /** ??????? */
+    /** 右侧价格轴宽度 */
     rightAxisWidth?: number
-    /** ??????? */
+    /** 底部时间轴高度 */
     bottomAxisHeight?: number
-    /** ??????????????????? 60px? */
+    /** 价格标签额外宽度（用于显示涨跌幅，默认 60px） */
     priceLabelWidth?: number
 
-    /** ????????? 10? */
+    /** 缩放级别数量（默认 10） */
     zoomLevels?: number
-    /** ???????1 ~ zoomLevels?????? */
+    /** 初始缩放级别（1 ~ zoomLevels，默认居中） */
     initialZoomLevel?: number
-    /** ???? */
+    /** 是否全屏 */
     isFullscreen?: boolean
   }>(),
   {
@@ -195,13 +195,13 @@ const chartMainRef = ref<HTMLDivElement | null>(null)
 const tooltipLayerRef = ref<HTMLDivElement | null>(null)
 const toolbarRef = ref<InstanceType<typeof LeftToolbar> | null>(null)
 
-/* ========== ??????????? ========== */
+/* ========== 十字线（鼠标悬停位置） ========== */
 const chartRef = shallowRef<Chart | null>(null)
 
-/* ========== ?????? ========== */
+/* ========== 语义化控制器 ========== */
 const semanticController = shallowRef<SemanticChartController | null>(null)
 
-/* ========== ChartStore????????? ========== */
+/* ========== ChartStore（响应式状态中心） ========== */
 const store = createChartStore({
   initialZoomLevel: props.initialZoomLevel ?? 1,
   minKWidth: props.minKWidth,
@@ -211,10 +211,10 @@ const store = createChartStore({
   priceLabelWidth: props.priceLabelWidth,
 })
 
-/* ========== ???? ========== */
+/* ========== 主题状态 ========== */
 const chartTheme = ref<'light' | 'dark'>('light')
 
-// ??? kWidth / kGap
+// 初始化 kWidth / kGap
 store.actions.setZoomState(
   store.state.zoomLevel,
   zoomLevelToKWidth(store.state.zoomLevel, {
@@ -234,7 +234,7 @@ store.actions.setZoomState(
   ),
 )
 
-// ????????????
+// 为逐步迁移保留的局部别名
 const dataLength = computed(() => store.state.dataLength)
 const viewportDpr = computed(() => store.state.viewportDpr)
 const zoomLevel = computed(() => store.state.zoomLevel)
@@ -251,7 +251,7 @@ function scheduleRender() {
 function handleSettingsChange(settings: Record<string, boolean | string>) {
   chartRef.value?.updateSettings(settings)
 
-  // ??K?????
+  // 万条K线性能测试
   if (settings.performanceTest10kKlines) {
     const testData = generate10kKLineData()
     console.time('updateData-10k')
@@ -260,28 +260,28 @@ function handleSettingsChange(settings: Record<string, boolean | string>) {
     store.actions.setDataLength(testData.length)
     store.actions.bumpDataVersion()
   } else {
-    // ???????????????
-    // ??????????????
+    // 如果关闭性能测试，恢复原始数据
+    // 通过重新应用语义化配置来恢复
     if (semanticController.value && chartRef.value?.getData()?.length === 10000) {
       semanticController.value.applyConfig(props.semanticConfig)
     }
   }
 }
 
-// ??1??K?????
+// 生成1万条K线测试数据
 function generate10kKLineData() {
   const data: KLineData[] = []
   const startTime = new Date('2020-01-01').getTime()
   const dayMs = 24 * 60 * 60 * 1000
 
-  let lastClose = 3000 // ????
+  let lastClose = 3000 // 起始价格
 
   for (let i = 0; i < 10000; i++) {
     const timestamp = startTime + i * dayMs
 
-    // ??????
-    const volatility = 0.02 // 2%????
-    const trend = 0.0001 // ??????
+    // 生成随机波动
+    const volatility = 0.02 // 2%日波动率
+    const trend = 0.0001 // 轻微上涨趋势
     const change = (Math.random() - 0.5) * 2 * volatility + trend
 
     const open = lastClose
@@ -330,11 +330,11 @@ function setMarkerTooltipEl(el: HTMLDivElement | null) {
   })
 }
 
-// ===== Marker tooltip ?? =====
+// ===== Marker tooltip 状态 =====
 const mousePos = ref({ x: 0, y: 0 })
 const useAnchorPositioning = ref(false)
 
-// ?? rect ????? pointermove ??? getBoundingClientRect ??????
+// 容器 rect 缓存，避免 pointermove 中反复 getBoundingClientRect 强制同步布局
 let _cachedContainerRect: DOMRect | null = null
 function invalidateContainerRectCache(): void {
   _cachedContainerRect = null
@@ -346,7 +346,7 @@ function getContainerRect(container: HTMLDivElement): DOMRect {
   return _cachedContainerRect
 }
 
-// ===== ??????????InteractionController snapshot? =====
+// ===== 交互状态（单一来源：InteractionController snapshot） =====
 const interactionState = shallowRef<InteractionSnapshot>({
   crosshairPos: null,
   crosshairIndex: null,
@@ -392,7 +392,7 @@ const isHoveringRightAxis = computed(() => interactionState.value.isHoveringRigh
 const hoveredIdx = computed(() => interactionState.value.hoveredIndex)
 const crosshairIdx = computed(() => interactionState.value.crosshairIndex)
 
-// ?????????? style ?? CSS ??????????????
+// 统一光标样式：用内联 style 替代 CSS 类后代选择器，切断级联失效链
 const containerCursor = computed(() => {
   if (isDragging.value) return 'grabbing'
   if (isResizingPane.value || isHoveringPaneSeparator.value) return 'ns-resize'
@@ -403,7 +403,7 @@ const containerCursor = computed(() => {
 const hovered = computed(() => {
   const idx = interactionState.value.hoveredIndex
   if (typeof idx !== 'number') return null
-  void dataVersion.value // ???????
+  void dataVersion.value // 建立响应式依赖
   const data = chartRef.value?.getData()
   if (data && idx >= 0 && idx < data.length) {
     return data[idx]
@@ -441,13 +441,13 @@ const markerTooltipAnchorPlacement = computed<'right-bottom' | 'left-bottom'>(()
   return wouldOverflowRight ? 'left-bottom' : 'right-bottom'
 })
 
-// ????????
+// 获取当前图表数据
 const chartData = computed(() => {
-  void dataVersion.value // ???????????????????
+  void dataVersion.value // 建立响应式依赖，确保数据变化时重新求值
   return chartRef.value?.getData() ?? []
 })
 
-// ????????????????
+// 通知数据变化（在数据更新后调用）
 function handleSelectTool(toolId: string) {
   drawingController.value?.setTool(toolId as DrawingToolId)
 }
@@ -514,7 +514,7 @@ function onPointerUp(e: PointerEvent) {
 }
 
 function onPointerLeave(e: PointerEvent) {
-  // pointerleave ???????????????
+  // pointerleave 不需要绘图控制器路由，直接调用
   chartRef.value?.handlePointerEvent(e)
 }
 
@@ -538,10 +538,10 @@ function onScroll() {
   chartRef.value?.handleScrollEvent()
 }
 
-// ?????????????? subPanes ???
+// 主图指标显式状态（副图指标从 subPanes 派生）
 const mainActiveIndicators = ref<string[]>([])
 
-// ??????? subPanes ????
+// 副图指标列表从 subPanes 自动派生
 const subActiveIndicators = computed(() => {
   const ids: string[] = []
   const seen = new Set<string>()
@@ -554,26 +554,26 @@ const subActiveIndicators = computed(() => {
   return ids
 })
 
-// ????????? + ??????????
+// 最终合并列表（主图 + 副图），保持显示顺序
 const activeIndicators = computed(() => [
   ...mainActiveIndicators.value,
   ...subActiveIndicators.value,
 ])
 
-// ???????MA ? periods ?????????????
+// 指标参数配置（MA 的 periods 是数组，需要更宽松的类型）
 const indicatorParams = ref<Record<string, Record<string, unknown>>>({})
 
-// ??????
+// 副图槽位状态
 interface SubPaneSlot {
   id: string // pane ID: 'RSI_0', 'MACD_0', ...
   indicatorId: SubIndicatorType
   params: Record<string, unknown>
 }
 
-// ?????????????
+// 副图槽位数组（支持多副图）
 const subPanes = ref<SubPaneSlot[]>([])
 
-// ??????
+// 最大副图数量
 const maxSubPanes = 4
 
 function buildPaneLayoutIntent(): PaneSpec[] {
@@ -591,14 +591,14 @@ function buildPaneLayoutIntent(): PaneSpec[] {
       ]
 }
 
-// ????????
+// 获取指标默认参数
 function getDefaultParams(
   indicatorId: SubIndicatorType,
 ): Record<string, number | boolean | string> {
   return { ...SUB_PANE_INDICATOR_CONFIGS[indicatorId].defaultParams }
 }
 
-// ???????????? 'RSI_0', 'MACD_0' ??? paneId
+// 副图实例计数器：用于生成 'RSI_0', 'MACD_0' 这样的 paneId
 const subPaneCounters = new Map<SubIndicatorType, number>()
 
 function generatePaneId(indicatorId: SubIndicatorType): string {
@@ -607,7 +607,7 @@ function generatePaneId(indicatorId: SubIndicatorType): string {
   return `${indicatorId}_${count}`
 }
 
-// paneTitle ????????paneId -> rendererName?
+// paneTitle 渲染器名称映射（paneId -> rendererName）
 const paneTitleRendererNames = new Map<string, string>()
 
 function mountSubPaneTitle(paneId: string, indicatorId: SubIndicatorType): void {
@@ -628,7 +628,7 @@ function unmountSubPaneTitle(paneId: string): void {
   }
 }
 
-// ??????? Chart API?
+// 添加副图（使用 Chart API）
 function addSubPane(
   indicatorId: SubIndicatorType = 'VOLUME',
   params?: Record<string, number | boolean | string>,
@@ -639,14 +639,14 @@ function addSubPane(
 
   const mergedParams = params ?? getDefaultParams(indicatorId)
 
-  // ???? Facade API ??????
+  // 使用高层 Facade API 创建副图指标
   const paneId = chartRef.value?.addIndicator(indicatorId, 'sub', mergedParams)
   if (!paneId) return false
 
-  // ?? paneTitle ????UI ????
+  // 创建 paneTitle 渲染器（UI 层职责）
   mountSubPaneTitle(paneId, indicatorId)
 
-  // ??????
+  // 更新本地状态
   subPanes.value.push({
     id: paneId,
     indicatorId,
@@ -657,7 +657,7 @@ function addSubPane(
   return true
 }
 
-// ????????? Facade API?
+// 移除副图（使用高层 Facade API）
 function removeSubPane(paneId: string): void {
   const index = subPanes.value.findIndex((p) => p.id === paneId)
   if (index === -1) return
@@ -665,50 +665,50 @@ function removeSubPane(paneId: string): void {
   const pane = subPanes.value[index]
   if (!pane) return
 
-  // ?? paneTitle ???
+  // 移除 paneTitle 渲染器
   unmountSubPaneTitle(paneId)
 
-  // ???? Facade API ????
+  // 使用高层 Facade API 移除指标
   chartRef.value?.removeIndicator(paneId)
 
-  // ??????
+  // 更新本地状态
   subPanes.value.splice(index, 1)
 }
 
-// ??????????? Facade API?
+// 清除所有副图（使用高层 Facade API）
 function clearAllSubPanes(): void {
-  // ???? Facade API ????
+  // 使用高层 Facade API 逐个移除
   for (const pane of subPanes.value) {
     chartRef.value?.removeIndicator(pane.id)
     unmountSubPaneTitle(pane.id)
   }
 
-  // ??????
+  // 清空本地状态
   subPanes.value = []
   subPaneCounters.clear()
   paneTitleRendererNames.clear()
 }
 
-// ????????????????????config ? chart?
+// 从语义化配置初始化指标状态（单向数据流：config → chart）
 function initIndicatorsFromConfig(): void {
   const config = props.semanticConfig
   const chart = chartRef.value
   if (!chart) return
 
-  // ??????? - ????Chart API
+  // 初始化主图指标 - 直接调用Chart API
   const mainIndicators = config.indicators?.main
   if (mainIndicators) {
     for (const indicator of mainIndicators) {
       if (indicator.enabled) {
-        // ??Vue?????UI???
+        // 同步Vue状态（用于UI展示）
         if (!mainActiveIndicators.value.includes(indicator.type)) {
           mainActiveIndicators.value.push(indicator.type)
         }
-        // ????
+        // 保存参数
         if (indicator.params) {
           indicatorParams.value[indicator.type] = indicator.params as Record<string, unknown>
         }
-        // ?????Chart????????
+        // 启用指标（Chart内部管理渲染器）
         chart.enableMainIndicator(
           indicator.type,
           indicator.params as Record<string, number | boolean | string>,
@@ -717,18 +717,18 @@ function initIndicatorsFromConfig(): void {
     }
   }
 
-  // ??????? syncSubPanesFromChart ??
+  // 副图指标参数由 syncSubPanesFromChart 处理
 }
 
-// ??????????????Chart????Chart???Vue??????
+// 监听主图指标参数变化，同步到Chart（状态由Chart管理，Vue只同步参数）
 watch(
   [activeIndicators, indicatorParams],
   ([indicators]) => {
     const chart = chartRef.value
     if (!chart) return
 
-    // ???mainIndicatorLegend???????????
-    // ??????/???Chart????
+    // 只更新mainIndicatorLegend的配置（用于图例显示）
+    // 渲染器的启用/禁用由Chart内部管理
     chart.updateRendererConfig('mainIndicatorLegend', {
       indicators: {
         MA: {
@@ -755,18 +755,18 @@ watch(
   { deep: true },
 )
 
-// ? Chart ???????????????????
+// 从 Chart 同步副图状态到本地（语义化配置后调用）
 function syncSubPanesFromChart(): void {
   const chartSubPaneEntries = chartRef.value?.getSubPaneEntries() ?? []
 
-  // ??????
+  // 清空本地状态
   subPanes.value = []
   paneTitleRendererNames.clear()
 
   for (const entry of chartSubPaneEntries) {
     const { paneId, indicatorId, params } = entry
 
-    // ???????
+    // 恢复计数器状态
     const match = paneId.match(/^(.+)_(\d+)$/)
     if (match) {
       const [, indicator, countStr] = match
@@ -777,10 +777,10 @@ function syncSubPanesFromChart(): void {
       }
     }
 
-    // ?? paneTitle ???
+    // 创建 paneTitle 渲染器
     mountSubPaneTitle(paneId, indicatorId)
 
-    // ??????
+    // 更新本地状态
     subPanes.value.push({
       id: paneId,
       indicatorId,
@@ -791,23 +791,23 @@ function syncSubPanesFromChart(): void {
   scheduleRender()
 }
 
-// ????????? Chart API?
+// 切换副图指标（使用 Chart API）
 function switchSubIndicator(paneId: string, newIndicatorId: SubIndicatorType): void {
   const pane = subPanes.value.find((p) => p.id === paneId)
   if (!pane) return
 
   const nextParams = getDefaultParams(newIndicatorId)
 
-  // ???? paneTitle ???
+  // 移除旧的 paneTitle 渲染器
   unmountSubPaneTitle(paneId)
 
-  // ?? Chart API ???????paneId ??????????
+  // 使用 Chart API 替换副图指标（paneId 不变，只换指标类型）
   chartRef.value?.replaceSubPaneIndicator(paneId, newIndicatorId, nextParams)
 
-  // ???? paneTitle ???
+  // 创建新的 paneTitle 渲染器
   mountSubPaneTitle(paneId, newIndicatorId)
 
-  // ???????paneId ?????
+  // 更新本地状态（paneId 保持不变）
   const index = subPanes.value.findIndex((p) => p.id === paneId)
   if (index !== -1) {
     subPanes.value[index] = {
@@ -818,7 +818,7 @@ function switchSubIndicator(paneId: string, newIndicatorId: SubIndicatorType): v
   }
 }
 
-// ??????????????? crosshairIdx ? data ??????
+// 获取副图标题信息（带缓存，只在 crosshairIdx 或 data 变化时重算）
 const _titleInfoCache = new Map<
   string,
   { idx: number | null; dataLen: number; result: TitleInfo | null }
@@ -834,7 +834,7 @@ function getSubPaneTitleInfo(paneId: string): TitleInfo | null {
   const idx = crosshairIdx.value
   const dataLen = data.length
 
-  // ?????crosshairIdx ? dataLen ???
+  // 缓存命中：crosshairIdx 和 dataLen 都没变
   const cached = _titleInfoCache.get(paneId)
   if (cached && cached.idx === idx && cached.dataLen === dataLen) {
     return cached.result
@@ -849,12 +849,12 @@ function getSubPaneTitleInfo(paneId: string): TitleInfo | null {
   return result
 }
 
-// ??????????? Facade API?
+// 指标切换处理（使用高层 Facade API）
 function handleIndicatorToggle(indicatorId: string, active: boolean) {
   const chart = chartRef.value
   if (!chart) return
 
-  // ??????
+  // 主图指标处理
   const mainIndicatorIds = [
     'MA',
     'BOLL',
@@ -879,11 +879,11 @@ function handleIndicatorToggle(indicatorId: string, active: boolean) {
     const existingIndicator = mainActiveIndicators.value.find((id) => id === indicatorId)
 
     if (active && !existingIndicator) {
-      // ??????
+      // 添加主图指标
       chart.addIndicator(indicatorId, 'main', indicatorParams.value[indicatorId])
       mainActiveIndicators.value.push(indicatorId)
     } else if (!active && existingIndicator) {
-      // ??????
+      // 移除主图指标
       const instanceId = indicatorId.toUpperCase()
       chart.removeIndicator(instanceId)
       mainActiveIndicators.value = mainActiveIndicators.value.filter((id) => id !== indicatorId)
@@ -891,34 +891,34 @@ function handleIndicatorToggle(indicatorId: string, active: boolean) {
     return
   }
 
-  // ??????
+  // 副图指标处理
   if (SUB_PANE_INDICATORS.includes(indicatorId as SubIndicatorType)) {
     if (active) {
-      // ?????????? pane???
+      // 如果已存在同类型指标 pane，跳过
       const existingPane = subPanes.value.find((p) => p.indicatorId === indicatorId)
       if (existingPane) return
 
-      // ????????
+      // 副图数量上限检查
       if (subPanes.value.length >= maxSubPanes) return
 
-      // ???? API ??????
+      // 使用高层 API 添加副图指标
       const paneId = chart.addIndicator(indicatorId, 'sub', indicatorParams.value[indicatorId])
       if (paneId) {
-        // ?? paneTitle ???
+        // 创建 paneTitle 渲染器
         mountSubPaneTitle(paneId, indicatorId as SubIndicatorType)
-        // ??????
+        // 同步本地状态
         subPanes.value.push({
           id: paneId,
           indicatorId: indicatorId as SubIndicatorType,
           params: { ...indicatorParams.value[indicatorId] },
         })
       } else if (subPanes.value.length > 0) {
-        // ???????????????????
+        // 添加失败（可能达到上限），替换最后一个
         const lastPane = subPanes.value[subPanes.value.length - 1]
         switchSubIndicator(lastPane.id, indicatorId as SubIndicatorType)
       }
     } else {
-      // ??????????? pane
+      // 找到并移除该指标的所有 pane
       const panesToRemove = subPanes.value.filter((p) => p.indicatorId === indicatorId)
       panesToRemove.forEach((pane) => {
         chart.removeIndicator(pane.id)
@@ -930,7 +930,7 @@ function handleIndicatorToggle(indicatorId: string, active: boolean) {
   }
 }
 
-// ??????????
+// 更新主图指标图例配置
 function updateMainIndicatorLegendConfig() {
   chartRef.value?.updateRendererConfig('mainIndicatorLegend', {
     indicators: {
@@ -954,12 +954,12 @@ function updateMainIndicatorLegendConfig() {
   })
 }
 
-// ????????
+// 指标参数更新处理
 function handleUpdateParams(indicatorId: string, params: Record<string, unknown>) {
-  // ??????
+  // 保存参数配置
   indicatorParams.value[indicatorId] = params
 
-  // ???????? - ??Chart API
+  // 主图指标参数更新 - 使用Chart API
   if (
     indicatorId === 'MA' ||
     indicatorId === 'BOLL' ||
@@ -1022,21 +1022,21 @@ function handleReorderSubIndicators(orderedIndicatorIds: string[]) {
 
   subPanes.value = nextSubPanes
 
-  // activeIndicators ? computed ???????????
+  // activeIndicators 由 computed 自动派生，无需手动同步
 
   const chart = chartRef.value
   if (!chart) return
   chart.updatePaneLayout(buildPaneLayoutIntent())
 }
 
-/* ??????? Vue ????????zoom ??????? */
+/* 计算总宽度：从 Vue 响应式状态读取，zoom 变化时自动重算 */
 const axisHostWidth = computed(() => props.rightAxisWidth + props.priceLabelWidth)
 
 const TRAILING_DRAWING_SLOTS_VAL = TRAILING_DRAWING_SLOTS
 
 const totalWidth = store.computed.totalWidth
 
-// ??? Chart ???? scrollLeft ??????
+// 缩放由 Chart 回调驱动 scrollLeft 与渲染时序。
 
 function scrollToRight() {
   const container = containerRef.value
@@ -1049,13 +1049,13 @@ function scrollToRight() {
   const dpr = chart.getCurrentDpr()
   const { unitPx, startXPx } = getPhysicalKLineConfig(kWidth.value, kGap.value, dpr)
 
-  // ??????K????????? TRAILING_DRAWING_SLOTS?
+  // 计算最后一根K线的结束位置（不含 TRAILING_DRAWING_SLOTS）
   const lastKLineEndPx = (startXPx + dataLength * unitPx) / dpr
 
-  // ?????????
+  // 计算最大可滚动距离
   const maxScrollLeft = Math.max(0, container.scrollWidth - container.clientWidth)
 
-  // ???????????????K??????
+  // 计算需要的滚动位置，使最后一根K线紧贴最右侧
   const targetScrollLeft = Math.min(
     maxScrollLeft,
     Math.max(0, lastKLineEndPx - container.clientWidth),
@@ -1065,7 +1065,7 @@ function scrollToRight() {
   scheduleRender()
 }
 
-/* ?????????? Chart facade API? */
+/* 缩放到指定级别（通过 Chart facade API） */
 function applyZoomToLevel(targetLevel: number, anchorX?: number) {
   const chart = chartRef.value
   if (!chart) return
@@ -1083,7 +1083,7 @@ defineExpose({
     return chartRef.value?.plugin
   },
 
-  // Zoom Level API?Vue SSOT?
+  // Zoom Level API（Vue SSOT）
   zoomToLevel: applyZoomToLevel,
   zoomIn: (anchorX?: number) => applyZoomToLevel(zoomLevel.value + 1, anchorX),
   zoomOut: (anchorX?: number) => applyZoomToLevel(zoomLevel.value - 1, anchorX),
@@ -1091,7 +1091,7 @@ defineExpose({
   getZoomLevelCount: () => chartRef.value?.getZoomLevelCount() ?? 10,
 })
 
-// ==================== onMounted ???? ====================
+// ==================== onMounted 拆分函数 ====================
 
 function setupWheelHandler(container: HTMLDivElement): (e: WheelEvent) => void {
   const onWheelHandler = (e: WheelEvent) => {
@@ -1099,7 +1099,7 @@ function setupWheelHandler(container: HTMLDivElement): (e: WheelEvent) => void {
     const chart = chartRef.value
     if (!chart) return
 
-    // ?? Chart facade API ??????
+    // 使用 Chart facade API 处理滚轮事件
     chart.handleWheelEvent(e)
   }
   container.addEventListener('wheel', onWheelHandler, { passive: false })
@@ -1131,10 +1131,10 @@ function initChart(
 }
 
 function setupChartCallbacks(chart: Chart): void {
-  // ???setOnViewportChange ???? viewport signal ????
+  // 注意：setOnViewportChange 已合并到 viewport signal 订阅者中
 
   chart.setOnPaneLayoutChange(() => {
-    // ????????????????????????
+    // 分隔线位置计算（需要实际像素位置，保留在回调中）
     invalidateContainerRectCache()
     const renderers = chart.getPaneRenderers()
     const borderTop = containerRef.value
@@ -1149,27 +1149,27 @@ function setupChartCallbacks(chart: Chart): void {
     })
   })
 
-  // ?? paneRatios signal???? Vue store
+  // 订阅 paneRatios signal，同步到 Vue store
   const unsubscribePaneRatios = chart.paneRatios.subscribe(() => {
     const ratios = chart.paneRatios.peek()
     store.actions.setPaneRatios({ ...ratios })
   })
 
-  // ?? viewport signal??????DPR?width ??? scrollLeft ??
+  // 订阅 viewport signal，处理缩放、DPR、width 变化和 scrollLeft 更新
   const unsubscribeViewport = chart.viewport.subscribe(() => {
     const vp = chart.viewport.peek()
 
-    // DPR ?????? store
+    // DPR 变化时同步到 store
     if (store.state.viewportDpr !== vp.dpr) {
       store.actions.setViewportDpr(vp.dpr)
     }
 
-    // ViewWidth ?????? store
+    // ViewWidth 变化时同步到 store
     if (store.state.viewWidth !== vp.plotWidth) {
       store.actions.setViewWidth(vp.plotWidth)
     }
 
-    // ???? zoom state ? Vue store?Chart ? SSOT?
+    // 完整同步 zoom state 到 Vue store（Chart 是 SSOT）
     if (
       store.state.zoomLevel !== vp.zoomLevel ||
       store.state.kWidth !== vp.kWidth ||
@@ -1178,7 +1178,7 @@ function setupChartCallbacks(chart: Chart): void {
       store.actions.setZoomState(vp.zoomLevel, vp.kWidth, vp.kGap)
     }
 
-    // ? nextTick ??? desiredScrollLeft
+    // 在 nextTick 中应用 desiredScrollLeft
     const desiredLeft = vp.desiredScrollLeft
     if (desiredLeft !== undefined && desiredLeft !== containerRef.value?.scrollLeft) {
       invalidateContainerRectCache()
@@ -1193,20 +1193,20 @@ function setupChartCallbacks(chart: Chart): void {
     }
   })
 
-  // ?? data signal??? onDataChange ??
+  // 订阅 data signal，替换 onDataChange 回调
   const unsubscribeData = chart.data.subscribe(() => {
     const data = chart.data.peek()
     store.actions.setDataLength(data.length)
     store.actions.bumpDataVersion()
   })
 
-  // ?? theme signal???? CSS data-theme
+  // 订阅 theme signal，同步到 CSS data-theme
   const unsubscribeTheme = chart.theme.subscribe(() => {
     const theme = chart.theme.peek()
     chartTheme.value = theme
   })
 
-  // ?? unsubscribe ??????
+  // 保存 unsubscribe 函数以便清理
   onUnmounted(() => {
     unsubscribeViewport()
     unsubscribeData()
@@ -1251,7 +1251,7 @@ function setupInteractionCallbacks(chart: Chart): void {
     if (!chart) return
     const container = containerRef.value
     if (!container) return
-    // centerClientX ? clientX????????????
+    // centerClientX 是 clientX，需要转换为视口局部坐标
     const rect = container.getBoundingClientRect()
     const centerX = centerClientX - rect.left
     chart.handlePinchZoom(delta, centerX)
@@ -1262,7 +1262,7 @@ function setupInteractionCallbacks(chart: Chart): void {
   chart.resize()
 }
 
-/** ??????????? ? Chart API ??? */
+/** 语义化控制器：外部配置 → Chart API 的桥梁 */
 function setupSemanticController(chart: Chart): void {
   __setDataFetcher(props.dataFetcher)
   semanticController.value = new SemanticChartController(chart)
@@ -1271,13 +1271,13 @@ function setupSemanticController(chart: Chart): void {
     console.error('Semantic config error:', error)
   })
 
-  // config:ready ? Chart ???????Vue ????
+  // config:ready → Chart 侧已完成创建，Vue 回读状态
   semanticController.value.on('config:ready', () => {
     initIndicatorsFromConfig()
     syncSubPanesFromChart()
     nextTick(() => scrollToRight())
   })
-  // ?????????
+  // 应用副图、主图配置
   semanticController.value.applyConfig(props.semanticConfig).then((result) => {
     if (result && !result.success) {
       console.error('Semantic config apply failed:', result.errors)
@@ -1294,32 +1294,32 @@ onMounted(() => {
   const xAxisCanvas = xAxisCanvasRef.value
   if (!container || !canvasLayer || !rightAxisLayer || !xAxisCanvas) return
 
-  // 1) ?????passive:false ???????
+  // 1) 滚轮缩放：passive:false 以阻止页面滚动
   const onWheelHandler = setupWheelHandler(container)
 
-  // 2) ?? Chart ??????????
+  // 2) 创建 Chart 实例并注册全部渲染器
   const chart = initChart(container, canvasLayer, rightAxisLayer, xAxisCanvas)
   chartRef.value = chart
 
-  // 3) ?? / ???? / ??????
+  // 3) 视口 / 面板布局 / 数据变更回调
   setupChartCallbacks(chart)
 
-  // 4) ?? zoom ???Vue SSOT ? Chart?
+  // 4) 同步 zoom 状态（Vue SSOT → Chart）
   chart.applyRenderState(store.state.kWidth, store.state.kGap, store.state.zoomLevel)
 
-  // 5) ????????????????
+  // 5) 工具栏初始设置（含性能测试数据）
   applyInitialSettings(chart)
 
-  // 6) ??????????/????
+  // 6) 绘图交互控制器（线段/箭头等）
   setupDrawingController(chart)
 
-  // 7) ???????????????
+  // 7) 十字线、捏合缩放、初始交互快照
   setupInteractionCallbacks(chart)
 
-  // 8) ??????????????????
+  // 8) 语义化配置控制器（最终驱动数据加载）
   setupSemanticController(chart)
 
-  // ? onUnmounted ?? wheel ??
+  // 供 onUnmounted 移除 wheel 监听
   ;(chart as any).__onWheel = onWheelHandler
 })
 
@@ -1337,10 +1337,10 @@ onUnmounted(() => {
   drawingController.value = null
 })
 
-// kWidth/kGap ? zoomLevel ??????? props ????
-// ????????????? expose ? zoomToLevel/zoomIn/zoomOut ??
+// kWidth/kGap 由 zoomLevel 派生，不再通过 props 直接修改
+// 如需程序化控制缩放，请使用 expose 的 zoomToLevel/zoomIn/zoomOut 方法
 
-// ?? yPaddingPx ??
+// 监听 yPaddingPx 变化
 watch(
   () => props.yPaddingPx,
   (newVal) => {
@@ -1348,7 +1348,7 @@ watch(
   },
 )
 
-// ?? semanticConfig ?????????
+// 监听 semanticConfig 变化（唯一数据源）
 watch(
   () => props.semanticConfig,
   async (newConfig, oldConfig) => {