# 媒体预览触控板缩放经验

更新日期：2026-04-30

## 背景

图片、视频预览里使用触控板放大缩小时，缩放速度太快，细微手势也会明显跳变，导致用户很难停在想要的比例。

这类问题不要只看“最大/最小缩放值”。真正影响手感的通常是 wheel 事件的粒度、单次缩放步进、连续事件同步方式。

## 根因

### 1. 高频 wheel 不能用固定大步进

触控板会连续发出很多小 `wheel` 事件。若每次都固定 `+0.1` 或 `-0.1`，微小手势也会被放大成大幅缩放。

经验：

- 触控板/滚轮缩放要按 `deltaY` 计算比例，而不是只看方向。
- 要限制单个事件最大缩放量，防止鼠标滚轮或系统加速度造成跳变。
- `deltaMode` 不是像素时要先归一化，避免不同设备手感差异过大。

### 2. 首次自适应不能制造视觉跳动

预览容器、图片/视频元信息和 CSS 尺寸可能不是同一帧就绪。如果先显示原始比例，再下一帧自适应，会让用户看到明显跳动。

经验：

- 首次进入预览时可以等 auto-fit 计算完成后再显示媒体内容。
- 容器尺寸变化要重新触发 auto-fit，但用户手动拖拽/缩放后不要再自动覆盖视图。
- auto-fit 相关隐藏样式要只作用于媒体内容，不影响工具栏和视频控件交互状态。

### 3. 连续缩放要读取最新值

React 事件回调在高频输入下容易遇到闭包值滞后。连续 wheel 中如果一直基于旧 `localZoom` 计算，会让缩放节奏不稳定。

经验：

- 高频交互中的当前值可用 `ref` 保存。
- 状态更新仍走 `setState`，但计算基准优先读 ref 中的最新缩放。
- 只有缩放值实际变化超过极小阈值时才通知父层，减少无意义渲染。

### 4. 同步模式不要传相对增量

媒体预览内部已经算出了目标缩放值，父层若再用 `z - zoomLevel` 转为相对增量，高频事件下容易叠加闭包误差。

经验：

- 子组件已经得到目标 zoom 时，父级 action 应支持设置绝对缩放值。
- 快捷键、按钮这类明确步进仍适合保留相对 `zoom(delta)`。
- wheel/pinch 这类连续输入更适合 `setZoomLevel(value)`。

## 修复规则

1. 媒体预览 wheel 缩放按归一化 `deltaY` 计算。
2. 单次 wheel 缩放增量必须有限幅。
3. 首次 auto-fit 完成前隐藏媒体内容，避免先大后小的闪跳。
4. 用户手动拖拽/缩放后，auto-fit 不再覆盖当前视图。
5. 触控板缩放基准值使用 ref 保持最新。
6. 父层同步缩放使用绝对值 setter，避免连续事件误差。
7. 按钮和快捷键步进保持原有节奏，不和触控板手感绑定。

## 验证清单

- 图片预览中触控板轻推时缩放变化更细。
- 视频预览中触控板轻推时缩放变化更细。
- 工具栏放大/缩小按钮仍按原步进工作。
- 对比联动模式下缩放同步稳定，不出现过度叠加。
- `pnpm nx typecheck drawnix` 通过。

## 相关文件

- `packages/drawnix/src/components/shared/media-preview/MediaViewport.tsx`
- `packages/drawnix/src/components/shared/media-preview/MediaViewport.scss`
- `packages/drawnix/src/components/shared/media-preview/useViewerState.ts`
- `packages/drawnix/src/components/shared/media-preview/UnifiedMediaViewer.tsx`
- `packages/drawnix/src/components/shared/media-preview/types.ts`