WebAnimationAPI获取动画持续时间详解

本文深入剖析了 Web Animation API 中 `getComputedTiming().duration` 的常见误解与使用陷阱，指出它返回的并非动画实际运行耗时，而是声明的原始时长（常为 `Infinity` 或 `0`），并明确揭示真正可靠获取真实流逝时间的方法：手动设置 `animation.startTime = performance.now()` 后通过 `performance.now() - animation.startTime` 精确计算，同时提醒开发者警惕 CSS 动画的只读限制、`progress` 的不可靠性以及暂停/中断场景下的计时补偿需求——掌握这些细节，才能避开“看似正确实则失效”的时间计算坑。

getComputedTiming 返回的 duration 为什么总是 Infinity 或 0

直接调用 getComputedTiming() 获取动画实际持续时间，大概率得不到你想要的数值——它返回的 duration 字段不是“动画跑完花了多久”，而是“动画定义的时长”，且受动画状态影响极大。duration 来自动画效果（KeyframeEffect）的原始配置，若动画未显式设置 duration（比如用 CSS 声明、或 JS 中传了 {}），就可能为 Infinity；若动画已结束且没设 fill，也可能退化为 0。

真正反映“动画从开始到当前帧实际经过的时间”的字段是 activeDuration（活跃时长），但它仍不等于“实际运行耗时”——你需要结合 startTime 和当前时间手动计算。

• getComputedTiming().duration：只读取声明值，和执行无关
• getComputedTiming().activeDuration：等于 effect.getTiming().duration × 播放速率，但仍是预设值
• 真实流逝时间 = performance.now() - animation.startTime（需确保 startTime 已被设置）

animation.startTime 为空或 null 怎么办

刚创建的 Animation 实例，startTime 默认是 null。它只在动画**被添加到文档 timeline** 后才自动赋值（如调用 animation.play()），但这个时机不可控——浏览器可能延迟调度。

更可靠的做法是手动设置：

• 用 animation.startTime = performance.now() 强制绑定起始时间（推荐在 play() 前）
• 或监听 onstart 回调，在回调里读取 startTime（注意：该事件仅触发一次，且可能错过首帧）
• 避免依赖 getComputedTiming().startTime——它只是对 animation.startTime 的镜像，不解决源头问题

示例：

const anim = element.animate(keyframes, { duration: 1000 });
anim.startTime = performance.now(); // 立即锁定起点
anim.play();
<p>// 后续任意时刻获取已运行毫秒数：
const elapsed = performance.now() - anim.startTime;
</p>

CSS 动画能否用 getComputedTiming 获取持续时间

不能直接用。CSS 动画（@keyframes + animation）生成的 Animation 实例，其 effect 是只读的，getComputedTiming() 虽可调用，但返回的 duration 值来自 CSS 的 animation-duration，且无法覆盖或修正。

• 若 CSS 中写的是 animation-duration: 2s，getComputedTiming().duration 就是 2000（毫秒）
• 若用了 animation-duration: inherit 或未声明，可能得 0 或 Infinity
• 想动态获取真实运行时长？只能靠 performance.now() 手动打点 + 监听 animationstart/animationend 事件

为什么不用 getComputedTiming().progress 计算耗时

progress 是归一化的播放进度（0–1），但它依赖 activeDuration 和 currentTime 推算，而 currentTime 本身在动画暂停或未激活时会失真。更重要的是：progress 不提供时间基准——你不知道分母（即完整时长）是否真实有效。

• 当动画循环（iterations: Infinity）时，progress 会超过 1，甚至无限增长
• 当动画被 pause() 后，currentTime 停滞，但 progress 仍按旧节奏推算（取决于实现）
• 真正可控的耗时 = performance.now() - anim.startTime，只要 startTime 是你亲手设的

复杂点在于：动画可能被用户交互、样式重置、timeline 暂停等打断，startTime 一旦设定就不再更新——所以如果你需要“累计活跃时间”，得自己维护计时器或监听 onfinish/oncancel 事件做补偿。

好了，本文到此结束，带大家了解了《WebAnimationAPI获取动画持续时间详解》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！