时间线交互引擎：从像素到帧的逆向映射与磁吸网格

时间线交互引擎：从像素到帧的逆向映射与磁吸网格

在视频编辑器里，时间线（timeline）是最核心的交互层。用户拖拽一段素材、对齐到另一段、按 0.5s 网格吸附、撤销上一步------每一个"流畅"的操作背后，都是 absolute 定位百分比映射、client 坐标反向投影、原子操作打包、历史栈快照的精密配合。本文拆解一个工程级时间线引擎的设计，重点谈那些"看起来只是 UI"实则关乎数据一致性的细节。

一、为什么不用 Canvas 而用 DOM

时间线有两种实现思路：

• Canvas 渲染：性能上限高，10 万 clip 也能流畅。但失去 DOM 的事件、accessibility、CSS 动画，拖拽/选中/键盘导航都要从零实现。
• DOM 渲染：clip 数量在数百到数千时性能足够，复用浏览器原生事件系统，CSS 一行做磁吸高亮动画。

对桌面视频编辑器（典型 clip 数 50~500），DOM 方案是工程性价比最高的选择。性能关键不在渲染，而在响应式更新的范围控制------下面会展开。

二、absolute + 百分比：zoom 不再是噩梦

时间线最朴素的设计：clip 用 position: absolute + left: x px; width: w px。但当你想加 zoom（缩放）时，每个 clip 的 left/width 都要重新计算，几百个 clip 一起改 style，性能拉胯。

工程化方案：clip 的 left/width 用百分比表达，缩放因子收敛到一个 CSS 变量。

<div class="timeline-track" :style="{ '--zoom': zoomFactor }">
  <div
    v-for="clip in clips"
    class="clip"
    :style="{
      left: (clip.start / totalDuration * 100) + '%',
      width: (clip.duration / totalDuration * 100) + '%'
    }"
  />
</div>

.timeline-track {
  position: relative;
  width: calc(100% * var(--zoom));
}

zoom 改变时，只更新根容器的 --zoom，clip 的百分比不变，浏览器自动 reflow。CSS 百分比是相对父元素，父元素宽度随 zoom 变，clip 跟着变。一次属性更新替代 N 个 style 重写。

但百分比有个隐藏陷阱：父元素必须有明确 width 。如果父是 width: auto，百分比回退到 0。解决方案是显式给 track 容器一个基准宽度（如 100%），zoom 通过 calc(100% * var(--zoom)) 在其上叠加。

三、client 坐标逆向映射：从鼠标位置到时间戳

拖拽 clip 时，鼠标移动事件给的是 event.clientX（视口像素坐标），但我们要改的是 clip.start（秒）。需要一个逆向映射函数：

function clientXToSeconds(clientX: number, trackEl: HTMLElement, totalDuration: number): number {
  const rect = trackEl.getBoundingClientRect()
  const offsetX = clientX - rect.left
  // 注意：rect.width 已经是 zoom 之后的宽度
  const ratio = offsetX / rect.width
  const seconds = ratio * totalDuration
  return Math.max(0, Math.min(seconds, totalDuration))
}

要点：

1. getBoundingClientRect() 返回的是 zoom 之后的实际宽度 ------因为 CSS width: calc(100% * var(--zoom)) 让 track 元素物理宽度变了。这意味着 zoom 越大，每秒对应的像素越多，鼠标移动同样距离对应的时间变化越小，符合直觉。
2. 边界 clamp：拖到 track 左侧之外应固定到 0，右侧之外固定到 totalDuration。
3. 不要在 mousemove 里读 layout ：getBoundingClientRect 会触发 reflow，频繁调用会卡。优化：拖拽开始时读一次 rect 存起来，移动期间用缓存的 rect + scrollLeft 偏移修正。

let cachedRect: DOMRect | null = null
let cachedScrollLeft = 0

function onDragStart(e: MouseEvent) {
  cachedRect = trackEl.getBoundingClientRect()
  cachedScrollLeft = scrollContainer.scrollLeft
}

function onDragMove(e: MouseEvent) {
  if (!cachedRect) return
  const adjustedClientX = e.clientX + (scrollContainer.scrollLeft - cachedScrollLeft)
  const seconds = clientXToSecondsWithRect(adjustedClientX, cachedRect, totalDuration)
  // ...
}

如果拖拽过程中用户滚动了横向滚动条，需要把 scrollLeft 的 delta 加回去------否则鼠标不动、滚动条动了，clip 会"跟着"滚动条反向漂移。

四、全局事件绑定：window 而非 element

function onDragStart(e: MouseEvent) {
  window.addEventListener('mousemove', onDragMove)
  window.addEventListener('mouseup', onDragUp)
}

function onDragUp() {
  window.removeEventListener('mousemove', onDragMove)
  window.removeEventListener('mouseup', onDragUp)
}

为什么不绑在 clip 元素上？因为鼠标快速移动时可能"飞出"clip 元素，clip 上的 mousemove 就停了。绑在 window 上，鼠标到屏幕边缘都能继续追踪。

陷阱：组件卸载时必须清理：

onBeforeUnmount(() => {
  window.removeEventListener('mousemove', onDragMove)
  window.removeEventListener('mouseup', onDragUp)
})

否则用户在拖拽过程中切了路由，window 上的 listener 永远不释放，下次进入这个组件再绑一份，事件回调里访问的 clip 是旧引用，状态错乱。Composition API 的 onBeforeUnmount 是必选项，不是可选项。

五、磁吸：0.5s 网格与 snapToStep

视频时间线的磁吸（snap）能让用户精确对齐，但实现不当会让拖拽"卡顿"。两种方案：

方案 A：硬吸附

function onDragMove(e: MouseEvent) {
  let seconds = clientXToSeconds(...)
  // 吸附到最近的 0.5s 整数倍
  const step = 0.5
  const remainder = seconds % step
  if (remainder < step * 0.2 || remainder > step * 0.8) {
    seconds = Math.round(seconds / step) * step
  }
  clip.start = seconds
}

简单但体验差------靠近网格线时 clip 突然"跳"过去，用户感觉失控。

方案 B：软磁吸 + 视觉反馈

function onDragMove(e: MouseEvent) {
  let seconds = clientXToSeconds(...)
  const step = 0.5
  const nearestStep = Math.round(seconds / step) * step
  const distance = Math.abs(seconds - nearestStep)

  if (distance < step * 0.15) {
    // 在吸附范围内：吸附 + 显示磁吸线
    seconds = nearestStep
    showSnapIndicator(nearestStep)
  } else {
    hideSnapIndicator()
  }
  clip.start = seconds
}

step * 0.15 是吸附阈值（150ms 内），用户拖到这个范围就吸附并显示一根磁吸辅助线（vertical line），用户能看到"我吸附到了哪里"。出范围后辅助线消失，clip 跟随鼠标自由移动。

磁吸候选不止时间网格，还应包括：

• 其他 clip 的边界 ：start / end，吸附让两段无缝衔接。
• 播放头（playhead）位置：吸附让对齐到当前预览点。
• 字幕时间戳：吸附让 clip 与字幕同步。

每帧候选排序后取最近的，吸附距离加权（时间网格权重高、其他 clip 边界权重低）。这是 FCP/Premiere 的实现思路，体验远好于单一网格吸附。

六、剪切：双 op 原子操作

把一段 clip 在 t = 3s 处切成两段，状态变更其实是两个独立操作：

1. 把原 clip 的 duration 从 5s 改为 3s
2. 新增一段 clip，start = 3s, duration = 2s，其他属性继承自原 clip

如果两个 op 分别下发，中间任何一次失败都会留下不一致状态------原 clip 被截短了但新 clip 没创建，2 秒素材凭空消失。

工程方案：把多个 op 打包成一个 batch，applyTimelinePatchOps 原子执行：

interface TimelineOp {
  type: 'addClip' | 'updateClip' | 'removeClip' | 'moveClip'
  payload: any
}

interface BatchOps {
  ops: TimelineOp[]
  /** 该 batch 是否整体进入历史栈（true=一次撤销即可回退） */
  atomic: true
}

function splitClip(clipId: string, atSeconds: number): BatchOps {
  const original = findClip(clipId)
  const leftDuration = atSeconds - original.start
  const rightDuration = original.duration - leftDuration

  return {
    atomic: true,
    ops: [
      { type: 'updateClip', payload: { id: clipId, duration: leftDuration } },
      {
        type: 'addClip',
        payload: {
          ...original,
          id: generateId(),
          start: atSeconds,
          duration: rightDuration,
        },
      },
    ],
  }
}

function applyTimelinePatchOps(batch: BatchOps) {
  // 1. 在内存草稿上顺序应用所有 op
  const draft = produce(currentDoc, d => {
    for (const op of batch.ops) applyOp(d, op)
  })

  // 2. 一次性 schema 校验（Layer 2/3）
  const parsed = projectDocumentSchema.safeParse(draft)
  if (!parsed.success) {
    throw new PatchError('POST_PATCH_INVALID', parsed.error.issues)
  }

  // 3. 一次写盘
  persistDocument(parsed.data)

  // 4. 一次历史快照
  pushHistorySnapshot(parsed.data)

  currentDoc = parsed.data
}

要点：

• 原子性 ：内存、磁盘、历史栈三者要么全成功要么全失败。produce 给了内存层原子性，schema 校验失败前不写盘，写盘失败前不入历史栈。
• 一次校验、一次写盘、一次历史：而不是每个 op 各跑一遍。性能与一致性双赢。
• 历史栈只记一次：用户 Ctrl+Z 一次恢复整段剪切，而不是按 op 顺序逐个回退（那会让撤销变成"取消左半段、再取消右半段、再取消原段"的三步诡异行为）。

七、撤销/重做：50 步历史栈

历史栈设计要点：

class HistoryStack {
  private past: ProjectDocument[] = []
  private future: ProjectDocument[] = []
  private readonly maxSteps = 50

  push(doc: ProjectDocument) {
    // 截断 future（一旦有新动作，redo 路径作废）
    this.future = []
    this.past.push(doc)
    if (this.past.length > this.maxSteps) {
      this.past.shift()  // 丢弃最老
    }
  }

  undo(): ProjectDocument | null {
    if (this.past.length === 0) return null
    const current = this.past.pop()!
    this.future.push(current)
    return this.past[this.past.length - 1] ?? current
  }

  redo(): ProjectDocument | null {
    if (this.future.length === 0) return null
    const doc = this.future.pop()!
    this.past.push(doc)
    return doc
  }
}

设计决策：

1. 存全量 document 还是存 diff？全量简单但内存占用大（50 步 × 1MB document = 50MB），diff 省内存但回退路径复杂。生产用全量 + gzip，50MB 压到 5MB 以内，简单可控。
2. maxSteps = 50：业界惯例。太多没意义（用户记不住 100 步前做了什么），太少不友好。Premiere 默认 32，FCP 默认 20。
3. 截断 future：标准行为，新动作后 redo 路径作废。但有些产品（如 Figma）保留 future，给"分支历史"------那是另一个故事。
4. undo() 返回的是"上一个状态"而非"当前状态弹出"：常见 bug 是 pop 出来当 current，结果用户连续 undo 两次只回退一步。

与持久化的协调

历史栈是内存对象，磁盘上是最新 document。用户撤销后必须主动写盘：

function undo() {
  const prev = historyStack.undo()
  if (prev) {
    currentDoc = prev
    persistDocument(prev)  // ← 别忘了
  }
}

否则用户撤销后关闭应用，下次打开还是撤销前的版本------"撤销不生效"的灵异 bug。

八、空 ops 的妙用：恢复写盘

function applyTimelinePatchOps(batch: BatchOps) {
  if (batch.ops.length === 0) {
    // 空 batch：仅触发写盘 + 历史快照，不改 document
    persistDocument(currentDoc)
    pushHistorySnapshot(currentDoc)
    return
  }
  // ...
}

这个"空 apply"是工程上很实用的口子------外部加载了一份新 document（如打开项目、导入 srt）想触发一次"持久化 + 历史"但不动 document 内容时，发个空 batch 即可。比单独写一个 persistAndSnapshot() 函数少一个 API。

九、轨道头与标尺的自适应

时间线上方要有标尺（ruler），左侧要有轨道头（track header）。两者都依赖 totalDuration 和 zoomFactor：

const totalDuration = computed(() =>
  Math.max(60, Math.ceil(...clips.value.map(c => c.start + c.duration)))
)

// 标尺刻度间隔：根据 zoom 动态选 0.5s / 1s / 5s / 10s
const rulerStep = computed(() => {
  const pixelsPerSecond = trackWidth.value / totalDuration.value
  if (pixelsPerSecond > 200) return 0.5
  if (pixelsPerSecond > 80) return 1
  if (pixelsPerSecond > 30) return 5
  return 10
})

const rulerTicks = computed(() => {
  const ticks: { second: number; label: string }[] = []
  for (let s = 0; s <= totalDuration.value; s += rulerStep.value) {
    ticks.push({ second: s, label: formatTimecode(s) })
  }
  return ticks
})

formatTimecode 把秒转成 MM:SS 或 MM:SS.fff，避免用户看到"75.3s"这种裸数字。

轨道头动态统计：

const trackStats = computed(() => {
  return tracks.value.map(track => {
    const trackClips = clips.value.filter(c => c.trackId === track.id)
    return {
      trackId: track.id,
      clipCount: trackClips.length,
      totalDuration: trackClips.reduce((acc, c) => acc + c.duration, 0),
      lastEnd: Math.max(0, ...trackClips.map(c => c.start + c.duration)),
    }
  })
})

用户看到"轨道 1：12 个素材，总时长 03:25"，比单纯一列轨道名信息密度高得多。

十、性能：响应式更新的范围控制

时间线最大的性能陷阱是全量响应式------改一个 clip 的 start，整个 clips 数组重新 render。500 个 clip 一起重排，掉帧。

工程手段：

1. v-for + :key="clip.id"：Vue 复用 DOM，只更新变化的 clip。
2. clip 组件用 v-memo：

<div
  v-for="clip in clips"
  :key="clip.id"
  v-memo="[clip.id, clip.start, clip.duration, clip.selected]"
>
  <ClipView :clip="clip" />
</div>

v-memo 让 Vue 跳过子树 diff------只有指定依赖变化才重渲染。改 clipA 的 start，clipB/C/D 的 diff 都跳过。

3. 拖拽期间降级 ：拖拽过程中频繁更新 clip.start，每帧都触发响应式。优化：拖拽时改一个临时变量 dragPreviewStart，松手时才写回 clip.start：

const draggingClipId = ref<string | null>(null)
const dragPreviewStart = ref(0)

function onDragMove(e: MouseEvent) {
  if (!draggingClipId.value) return
  dragPreviewStart.value = clientXToSeconds(...)
  // 不直接改 clip.start，只更新 preview
}

function onDragUp() {
  if (draggingClipId.value) {
    applyTimelinePatchOps({
      atomic: true,
      ops: [{ type: 'updateClip', payload: { id: draggingClipId.value, start: dragPreviewStart.value } }],
    })
  }
  draggingClipId.value = null
}

拖拽预览用一个独立的浮层 div 显示"clip 即将落在哪里"，松手才提交真实修改。响应式更新次数从"每帧一次"降到"每次拖拽一次"，性能天差地别。

十一、小结

时间线引擎的复杂度不在某一处，而在层与层之间的契约：

层	关键决策
渲染层	absolute + 百分比 + CSS 变量 zoom
输入层	client 坐标逆向映射 + window 全局事件
交互层	软磁吸 + 视觉反馈 + 拖拽预览
操作层	双 op 原子 batch + 一次校验/写盘/历史
历史层	全量快照 + 50 步上限 + 截断 future
性能层	v-memo + 拖拽降级 + 局部响应式

每一层单独看都不难，但合在一起就是"工程"------细节决定一个时间线是"能用"还是"顺手"。下次再看到一段流畅的拖拽吸附，可以想想：那 200ms 的吸附阈值、那次原子 batch、那次缓存的 rect、那次 v-memo 跳过的 diff------它们一起，才让"流畅"成为可能。