Web Animations API 如何中途反向播放：currentTime、playbackRate 与取消边界

做一个可展开的筛选面板时，最容易遇到的不是“动画怎么写”，而是用户在动画走到一半又点了一次按钮：面板应该顺着当前进度收回，而不是跳到终点再倒放。Web Animations API 把这段播放过程暴露成 Animation 对象，可以读取 currentTime，用 reverse() 改变方向，也能在必要时用 cancel() 清掉效果。

这项能力解决的是“半程切换”

CSS 的 animation-direction 适合声明固定的播放方向，但交互组件常常需要在运行时改变决定：抽屉打开到 40% 时，用户再次点击关闭；提示条刚出现，路由切换要求它立即收起；拖拽结束后还要从当前位置继续播放。

这时把动画保存为变量，比反复调用 element.animate() 更容易维护。保存后的对象同时承担播放控制和状态查询，业务代码可以根据 playState 做按钮禁用、焦点处理和收尾。

最小写法：保存 Animation，再切换方向

下面的例子让一个面板从透明和下移状态进入可见状态。再次点击时不计算剩余时长，直接把当前 Animation 反向播放：

const panel = document.querySelector('.panel');
const toggle = document.querySelector('#toggle');

const motion = panel.animate(
  [
    { opacity: 0, transform: 'translateY(-12px)' },
    { opacity: 1, transform: 'translateY(0)' }
  ],
  { duration: 260, easing: 'ease-out', fill: 'both' }
);

motion.pause();
let opened = false;

toggle.addEventListener('click', () => {
  opened = !opened;
  motion.reverse();
  console.log({ opened, time: motion.currentTime, state: motion.playState });
});

这里第一次调用 reverse() 会把原本的正向播放改为反向，因此更稳妥的实际组件通常会在创建后先把动画暂停并设置到合适的初始位置，再根据 opened 决定调用 play() 还是 reverse()。不要把“方向”误解成“立刻跳到另一端”；它仍然以当前时间位置为基础。

currentTime、playbackRate 和 reverse() 怎么分工

用 currentTime 定位，用 reverse 改方向

currentTime 的单位是毫秒。需要把动画恢复到 120 毫秒处，直接写 motion.currentTime = 120；但读取时要先处理 null，因为尚未关联时间轴或尚未启动的 Animation 没有可用时间。

reverse() 更像“沿当前轨道掉头”。它适合关闭面板、收起菜单这类从任意中间位置反向返回的操作，也比手工计算剩余时间少一个容易出错的分支。

用 playbackRate 表示速度意图

playbackRate = 1 是正常速度，2 会加速，负值会反向。若只是一次方向切换，用 reverse() 更清楚；若产品确实有“慢速预览”或“快速收起”，可以使用 updatePlaybackRate() 让播放位置先同步再改变速度。

motion.updatePlaybackRate(opened ? 1 : -1);
motion.play();

不要把 playbackRate = 0 当成标准暂停状态。它会让时间不再前进，但 playState 不一定变成 paused；需要暂停时调用 pause()，状态判断会更直接。

连续点击时，先看状态再处理收尾

一个常见错误是每次点击都新建动画。这样不仅会叠加多个效果，旧对象还可能在完成后继续影响样式。更简单的做法是保留一个 Animation，并把完成和取消当成两个不同结果：

function setPanel(open) {
  if (open) {
    motion.play();
  } else {
    motion.reverse();
  }

  motion.finished
    .then(() => {
      console.log('finished', motion.playState, motion.currentTime);
    })
    .catch(() => {
      console.log('animation interrupted');
    });
}

如果下一次操作发生在 Promise 完成前，旧的 finished 可能会被取消。把它当作正常的中断分支即可，不要在 catch 里重复创建另一套动画。

cancel() 不是暂停：重置与保留进度要分开

pause() 会保留当前位置，之后还能继续播放；cancel() 则会中止播放并移除这个 Animation 造成的效果，startTime 和 currentTime 也会回到未激活状态。关闭组件后要彻底回到 CSS 初始状态，才使用 cancel()。

如果动画由 CSS 类名控制，重置时还要同步移除打开状态，否则 JavaScript 已经取消效果，CSS 规则仍可能把面板留在可见状态。对于需要保留最终视觉结果的场景，可以在确认结束后再决定是否持久化样式，而不是把 cancel() 当作“提交最终状态”。

和纯 CSS 方案怎么选

静态 hover、页面首次出现和固定的进入/离开效果，CSS 仍然更短，也更容易交给设计同学调整。Web Animations API 的价值在于运行时控制：读取时间、响应连续输入、统一处理完成/取消、动态调整速度。

• 只有固定方向：优先 CSS transition 或 animation。
• 需要中途掉头：复用一个 Animation，优先考虑 reverse()。
• 需要按业务事件定位：使用 currentTime，并处理 null。
• 需要彻底撤销效果：使用 cancel()，同时清理组件状态和焦点。

兼容性要求较宽时，可以保留 CSS 类名作为视觉降级；JavaScript 控制逻辑只在确认 Element.prototype.animate 存在后启用。降级版本宁可少一个中途反向效果，也不要因为控制器缺失让面板无法打开。

常见问题

currentTime 为什么是 null？

Animation 尚未开始、没有可用时间轴或已经取消时都可能得到 null。读取前先判断，写入时也不要把 null 当成 0。

reverse() 和设置负 playbackRate 有什么区别？

两者都能改变播放方向，但 reverse() 直接表达“沿当前进度掉头”；负 playbackRate 更适合同时表达速度，代码中应明确处理播放状态。

动画完成后还能 reverse() 吗？

可以，但要留意完成端点和播放状态。组件可以复用同一个 Animation，也可以在需要独立生命周期时重新创建，关键是不要让旧对象和新对象同时作用于同一个元素。

什么时候应该调用 cancel()？

当组件销毁、路由离开或需要恢复 CSS 初始样式时调用。只是暂时停住时使用 pause()，不要丢掉可继续的进度。

把控制面收进一个小状态机

Web Animations API 并不替组件决定业务状态。实际项目里，把“目标状态”与 Animation 的“播放状态”分开记录，再在每次用户操作时复用同一个对象，通常就能解决半程切换、快速重复点击和销毁清理这三类问题。先用 currentTime 验证时间位置，再选择 reverse()、pause() 或 cancel()，动画代码会比不断叠加 CSS 类更容易复查。