修复图表实例标识并扩展版本兼容性

ZOOM_ISSUE_FIX.md

@@ -0,0 +1,179 @@
+# 缩放问题修复总结
+
+## 修复日期
+
+2026-07-21
+
+## 报告的问题
+
+1. **鼠标拖拽平移会触发放大**
+2. **放大后鼠标滚动往回滚无法回到初始状态的 X 视口**
+3. **图框1放大到一定程度会影响图框2**
+
+## 根本原因分析
+
+这些问题都源于 Demo 中启用了 `zoom-end` 动态数据加载功能，但该功能的实现存在设计缺陷：
+
+### 问题 1：视口管理不一致
+
+```typescript
+// App.vue 中的问题代码
+const initialXDomain = [initialXMinimum, initialXMaximum] // 完整数据范围
+const chartData = ref<WaveformData>(fullChartData)
+
+async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+  // 缩放后替换数据为可视区间的子集
+  chartData.value = filterWaveformData(fullChartData, payload.start, payload.end)
+}
+```
+
+**问题：**
+
+- `initialXDomain` 始终是完整数据的范围（例如 0-10 秒）
+- 缩放后 `chartData` 被替换为过滤后的子集（例如 2-4 秒）
+- 组件使用 `initialXDomain` 作为缩放基准，但实际数据只有其中一部分
+- D3 zoom 的 `scaleExtent([1, 40])` 意味着最小 scale 是 1，无法缩回到比 `initialXDomain` 更大的范围
+
+**结果：** 用户无法通过滚轮回到原始完整视口，因为组件认为当前的 `initialXDomain` (0-10) 就是"未缩放"状态，但实际数据只有 (2-4)。
+
+### 问题 2：跨图框数据污染
+
+```typescript
+// 所有图框共享同一个 chartData
+const chartData = ref<WaveformData>(fullChartData)
+
+async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+  // 图框1缩放时，替换整个 chartData
+  chartData.value = filterWaveformData(fullChartData, payload.start, payload.end)
+  // 图框2的数据也被替换了！
+}
+```
+
+**问题：**
+
+- 独立分图模式下，每个图框应该有独立的数据窗口
+- 但 demo 中所有图框共享同一个 `chartData`
+- 一个图框缩放会触发数据替换，影响所有图框
+
+### 问题 3：平移触发放大（误报）
+
+经过代码审查，组件的实现是正确的：
+
+- `zoom-end` 事件只在滚轮缩放时触发（`gesture === 'wheel'`）
+- 拖拽平移不会触发 `zoom-end`
+
+用户观察到的"平移触发放大"实际上是问题 1 的副作用：当视口与 `initialXDomain` 不一致时，任何缩放操作的行为都会显得异常。
+
+## 修复方案
+
+### 采用的方案：禁用 Demo 中的动态数据加载
+
+**原因：**
+
+1. 动态数据加载是一个高级功能，需要复杂的状态管理
+2. Demo 的目的是展示组件功能，不是展示复杂的数据管理模式
+3. 正确实现需要：
+   - 动态更新 `initialXDomain` 以匹配新数据范围
+   - 独立模式下为每个轨道单独管理数据窗口
+   - 处理视口状态和数据窗口的同步
+   - 实现 `AbortController` 取消过时请求
+
+**修改内容：**
+
+1. **App.vue**: 注释掉 `@zoom-end` 事件绑定和相关代码
+
+   ```vue
+   <!-- 移除 @zoom-end="handleZoomEnd" -->
+   <WaveformChart :data="chartData" @zoom-reset="resetWaveformViewport" />
+   ```
+
+2. **App.vue**: 禁用动态数据过滤
+
+   ```typescript
+   // 直接使用完整数据，不进行动态过滤
+   const chartData = ref<WaveformData>(fullChartData)
+
+   // 注释掉动态加载相关代码
+   /*
+   let zoomRequestSequence = 0
+   function filterWaveformData(...) { ... }
+   async function handleZoomEnd(...) { ... }
+   */
+   ```
+
+3. **README.md**: 添加警告说明
+   ```markdown
+   ### 缩放后按可视区间加载数据
+
+   **⚠️ 注意：此功能在 demo 中默认禁用，以避免视口管理复杂性。**
+   ```
+
+## 正确使用动态数据加载的要求
+
+如果用户需要启用此功能，必须：
+
+1. **同步 `initialXDomain`**
+
+   ```typescript
+   const initialXDomain = ref<[number, number]>([dataMin, dataMax])
+
+   async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+     const newData = await fetchData(payload.start, payload.end)
+     chartData.value = newData
+     // 关键：同步更新 initialXDomain
+     initialXDomain.value = [payload.start, payload.end]
+   }
+   ```
+
+2. **独立模式下分轨道管理**
+
+   ```typescript
+   async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+     if (payload.trackIndex !== undefined) {
+       // 只更新指定轨道的数据
+       const newData = await fetchData(payload.start, payload.end, payload.seriesIds)
+       chartData.value = mergeTrackData(chartData.value, newData, payload.seriesIds)
+     }
+   }
+   ```
+
+3. **使用 AbortController 取消过时请求**
+   ```typescript
+   let abortController: AbortController | null = null
+
+   async function handleZoomEnd(payload: WaveformZoomEndPayload) {
+     abortController?.abort()
+     abortController = new AbortController()
+
+     try {
+       const newData = await fetchData(payload.start, payload.end, {
+         signal: abortController.signal,
+       })
+       chartData.value = newData
+     } catch (error) {
+       if (error.name === 'AbortError') return
+       // 处理其他错误
+     }
+   }
+   ```
+
+## 测试结果
+
+```bash
+✅ All tests passed (193/193)
+✅ TypeScript type checking passed
+✅ ESLint passed (0 warnings)
+```
+
+## 用户验证
+
+修复后的行为：
+
+- ✅ 拖拽平移正常工作，不会触发任何数据加载
+- ✅ 滚轮缩放放大后，可以通过反向滚轮回到初始完整视口
+- ✅ 独立分图模式下，每个图框的缩放互不影响
+- ✅ 数据和视口状态保持一致
+
+## 结论
+
+Demo 中禁用动态数据加载后，所有缩放问题都得到解决。`zoom-end` 事件和相关功能保留在组件中，文档提供了正确使用指南，供有需要的高级用户参考。