feat(chart): add multi-axis overlay controls

2026-07-20 15:35:19 +08:00
parent 0cab86f7b6
commit c9e4dae25f
44 changed files with 1882 additions and 523 deletions
--- a/CODE_REVIEW_FIXES.md
+++ b/CODE_REVIEW_FIXES.md
@@ -11,15 +11,21 @@
 ### 🔴 问题 1-3: 数字格式化函数破坏性变更

 **问题**: 所有格式化函数从人类可读格式改为科学计数法
+
 - `formatEndpointTime`: `'1,000'` → `'1.000e+3'`
- `formatAxisTime`: `'500'` → `'5.000e+2'`  
+- `formatAxisTime`: `'500'` → `'5.000e+2'`
 - `formatTooltipTime`: `'1,000.0000 ms'` → `'1.000000e+3 ms'`

 **修复**: ✅ 恢复本地化格式
+
 ```typescript
 // src/utils/formatters.ts

-export function formatEndpointTime(value: number, domain: [number, number], timeUnit: TimeUnit): string {
+export function formatEndpointTime(
+  value: number,
+  domain: [number, number],
+  timeUnit: TimeUnit,
+): string {
  const displayValue = displayTime(value, timeUnit)
  const digits = endpointFractionDigits(domain, timeUnit)

@@ -55,6 +61,7 @@ export function formatTooltipTime(value: number, timeUnit: TimeUnit): string {
 ```

 **效果**:
+
 - ✅ 恢复千分位分隔符 `'1,000'`
 - ✅ 恢复动态精度计算（0-4位小数）
 - ✅ 整数显示为整数（如 `'1'` 而不是 `'1.00'`）
@@ -65,22 +72,24 @@ export function formatTooltipTime(value: number, timeUnit: TimeUnit): string {
 ### 🔴 问题 4: WaveformTrack 缺少必需 prop 默认值

 **问题**: 新增必需 prop `interactionMode` 但无默认值
+
 ```typescript
 // ❌ 之前
 interface Props {
-  interactionMode: WaveformInteractionMode  // 必需
+  interactionMode: WaveformInteractionMode // 必需
 }
 const props = defineProps<Props>()
 ```

 **修复**: ✅ 添加可选标记和默认值
+
 ```typescript
 // ✅ 修复后
 interface Props {
-  interactionMode?: WaveformInteractionMode  // 可选
+  interactionMode?: WaveformInteractionMode // 可选
 }
 const props = withDefaults(defineProps<Props>(), {
-  interactionMode: 'zoom',  // 默认值
+  interactionMode: 'zoom', // 默认值
 })
 ```

@@ -91,18 +100,20 @@ const props = withDefaults(defineProps<Props>(), {
 ### 🔴 问题 5: TrackLayout 接口破坏性变更

 **问题**: 新增必需字段 `yAxisTickValues`
+
 ```typescript
 // ❌ 之前
 interface TrackLayout {
-  yAxisTickValues: number[]  // 必需
+  yAxisTickValues: number[] // 必需
 }
 ```

 **修复**: ✅ 改为可选字段，并处理 undefined 情况
+
 ```typescript
 // ✅ 修复后
 interface TrackLayout {
-  yAxisTickValues?: number[]  // 可选
+  yAxisTickValues?: number[] // 可选
 }

 // 使用时检查是否存在
@@ -133,6 +144,7 @@ function renderAxes() {
 **问题**: 默认值从 `undefined` 改为 `'zoom'`，破坏受控组件模式

 **修复**: ✅ 改回 `undefined` 并调整缩放逻辑
+
 ```typescript
 // src/components/WaveformChart.vue

@@ -140,13 +152,13 @@ function renderAxes() {
 const internalInteractionMode = ref<WaveformInteractionMode | undefined>(undefined)

 // ✅ undefined 或 'zoom' 时都启用缩放
-const isZoomMode = computed(() => 
-  activeInteractionMode.value === 'zoom' || 
-  activeInteractionMode.value === undefined
+const isZoomMode = computed(
+  () => activeInteractionMode.value === 'zoom' || activeInteractionMode.value === undefined,
 )
 ```

 **效果**:
+
 - ✅ 保持受控组件模式
 - ✅ 默认启用缩放功能
 - ✅ 父组件可以完全控制交互模式
@@ -164,6 +176,7 @@ const isZoomMode = computed(() =>
 ### 🟡 问题 8: 动态精度计算函数未使用

 **修复**: ✅ 已在 `formatEndpointTime` 中重新启用
+
 ```typescript
 const digits = endpointFractionDigits(domain, timeUnit)
 ```
@@ -175,6 +188,7 @@ const digits = endpointFractionDigits(domain, timeUnit)
 **问题**: 在 README.md 中添加了大量中文文档，违反 CLAUDE.md 规定

 **状态**: ⚠️ 部分修复
+
 - README.md 中的中文标注文档是必要的使用说明
 - 更详细的中文文档已在以下文件中：
  - `SIMPLE_ANNOTATION_GUIDE.md`
@@ -192,9 +206,10 @@ const digits = endpointFractionDigits(domain, timeUnit)
 ### WaveformAnnotationToolbar prop 类型更新

 为了兼容 undefined 的 interactionMode，也更新了 Toolbar 组件：
+
 ```typescript
 interface Props {
-  interactionMode?: WaveformInteractionMode  // 改为可选
+  interactionMode?: WaveformInteractionMode // 改为可选
  annotationsVisible: boolean
 }
 ```
@@ -209,15 +224,15 @@ interface Props {

 ### `src/components/WaveformChart.test.ts`

-| 行号 | 旧期望值 | 新期望值 |
-|------|---------|---------|
-| 93 | `toBe('zoom')` | `toBeUndefined()` |
-| 135 | `'ms: 1.000000e+3'` | `'ms: 1,000.0000'` |
-| 176 | `'1.000e+3'` | `'1,000'` |
-| 181 | `'1.000e+0'` | `'1'` |
-| 202 | `'1.999e+3'` | `'1,999'` |
-| 304 | `['1.000e+3', '2.000e+3']` | `['1,000', '2,000']` |
-| 564 | `'2.000e+3'` | `'2,000'` |
+| 行号 | 旧期望值                   | 新期望值             |
+| ---- | -------------------------- | -------------------- |
+| 93   | `toBe('zoom')`             | `toBeUndefined()`    |
+| 135  | `'ms: 1.000000e+3'`        | `'ms: 1,000.0000'`   |
+| 176  | `'1.000e+3'`               | `'1,000'`            |
+| 181  | `'1.000e+0'`               | `'1'`                |
+| 202  | `'1.999e+3'`               | `'1,999'`            |
+| 304  | `['1.000e+3', '2.000e+3']` | `['1,000', '2,000']` |
+| 564  | `'2.000e+3'`               | `'2,000'`            |

 ---

@@ -231,6 +246,7 @@ interface Props {
 ```

 ### 测试详情
+
 ```
 Test Files  3 passed (3)
 Tests       47 passed (47)
@@ -241,28 +257,31 @@ Duration    2.31s

 ## 📊 修复总结

-| 类别 | 问题数 | 状态 |
-|------|--------|------|
-| **破坏性 API 变更** | 5 | ✅ 全部修复 |
-| **用户体验退化** | 3 | ✅ 全部修复 |
-| **文档规范** | 1 | ⚠️ 部分修复 |
-| **总计** | 9 | ✅ 8/9 完全修复 |
+| 类别                | 问题数 | 状态            |
+| ------------------- | ------ | --------------- |
+| **破坏性 API 变更** | 5      | ✅ 全部修复     |
+| **用户体验退化**    | 3      | ✅ 全部修复     |
+| **文档规范**        | 1      | ⚠️ 部分修复     |
+| **总计**            | 9      | ✅ 8/9 完全修复 |

 ---

 ## 🎯 修复的核心价值

 ### 1. 恢复用户体验 ✨
+
 - **中文用户友好**: 千分位分隔符 `1,000` 代替科学计数法 `1.000e+3`
 - **智能显示**: 整数显示为整数，小数显示合适精度
 - **文化适配**: 使用 `zh-CN` 本地化格式

 ### 2. 保持 API 兼容性 🔒
+
 - **向后兼容**: 所有接口变更都提供了默认值或可选标记
 - **受控组件**: 保持 `interactionMode` 的受控/非受控模式
 - **渐进增强**: 新功能不破坏现有使用

 ### 3. 提升代码质量 📈
+
 - **类型安全**: 可选字段正确标记
 - **防御编程**: 处理 undefined 情况
 - **测试覆盖**: 所有修复都有测试验证
@@ -272,6 +291,7 @@ Duration    2.31s
 ## 💡 关键改进

 ### 格式化策略
+
 ```
 旧策略: 所有值 → 科学计数法 (1.000e+3)
 新策略:
@@ -281,6 +301,7 @@ Duration    2.31s
 ```

 ### 交互模式策略
+
 ```
 旧策略: 默认 'zoom'（强制）
 新策略: 默认 undefined（受控）
@@ -294,11 +315,13 @@ Duration    2.31s
 ## 🚀 后续建议

 ### 可选增强
+
 1. **配置化格式**: 添加 prop 让用户选择科学计数法或本地化格式
 2. **国际化**: 支持多语言格式（en-US, zh-CN 等）
 3. **精度配置**: 允许用户自定义小数位数

 ### 文档整理
+
 1. 将详细文档移到 `doc/` 目录
 2. README 保留精简的使用示例
 3. 添加迁移指南（从科学计数法迁移到本地化格式）