HTML Web Animation API 速查教程

Web Animations API 常被误解为与 CSS 动画一样，只需添加属性即可。实际上，需要显式调用 element.animate()，并将返回的 Animation 对象保存为变量，否则动画播放后会失去控制，无法管理。该 API 属于“手动操作”类型，而非“声明式”。

Web Animations API 并非“添加属性即可动”，需要显式调用 element.animate()，且返回的 Animation 对象必须保存引用才能控制——若遗漏此步骤，动画播放后便会失控。

如何使用 element.animate() 启动最简动画

核心操作包括两项：准备关键帧数组，以及配置 timing 对象。常见错误包括：缺少 fill: 'forwards' 会导致动画结束后元素跳回初始状态；未设置 duration 时默认为 0ms，动画无法播放。

• keyframes 推荐使用数组，每个对象描述一个时间点的状态，例如 [{ opacity: 0 }, { opacity: 1 }]，浏览器会自动沿时间轴插值，无需手动计算中间帧
• options 中的 duration 单位为毫秒，非秒；easing 支持 CSS 缓动关键字（如 'ease-in-out'）和贝塞尔曲线（如 'cubic-bezier(0.42,0,0.58,1)'），但不支持 'step-start' 等步进函数
• 动画调用后立即播放，无需手动调用 play()；若需暂停、反转或取消，必须将返回值保存为变量，例如 const anim = el.animate(...)

为什么 anim.pause() 没有反应

常见问题在于调用了 pause() 但动画未停止。原因通常有三种：动画已结束、已被取消，或未获取有效的 Animation 实例。DOM 元素被移除时，关联动画会自动进入 finished 状态，此时调用 pause() 无效。

• 检查 anim.playState：值为 'idle' 表示未启动，'running' 时才可暂停，'finished' 或 'cancelled' 状态调用 pause() 无效
• 避免重复调用 animate() 创建新动画而不取消旧动画，否则旧动画持续运行，新动画覆盖样式，导致视觉混乱
• 监听 anim.onfinish 事件优于轮询 playState，但需注意该事件仅触发一次，且动画被 cancel() 时不会触发

与 CSS @keyframes 动画混用时的冲突点

CSS 动画与 Web Animations API 使用同一底层引擎，但优先级存在差异。element.animate() 的关键帧会覆盖同名 CSS 动画属性（如 transform、opacity），但不会影响 JS 未声明的属性。例如，JS 动画仅修改 opacity，CSS 中定义的 color 动画仍正常运行，互不干扰。

• 若页面上已有 animation: slide 2s infinite;，同时对同一元素调用 animate([{ transform: 'none' }], { duration: 1000 })，则 transform 由 JS 接管，color 等其他属性仍由 CSS 动画控制
• animation-play-state: paused 等 CSS 控制对 JS 创建的动画无效；反之，anim.pause() 也不会影响纯 CSS 动画
• 调试时，建议查看 DevTools 的“Animations”面板，其中会同时列出 CSS 和 JS 创建的动画实例，状态清晰，便于排查

兼容性与 polyfill 的实际取舍

兼容性方面，Chrome 36+、Firefox 48+、Safari 16.4+、Edge 79+ 原生支持。iOS Safari 16.4 之前需要 polyfill，但需注意 polyfill 无法实现真正的合成器线程动画，所有动画在主线程执行，复杂场景下可能出现卡顿。

• 简单交互动画（如 hover 暂停、点击触发）使用原生 API 足够；高帧率滚动联动或长序列动画，优先考虑 CSS @keyframes 配合 animation-play-state
• 引入 web-animations-js polyfill 后，Element.animate() 可用，但 document.timeline 等高级特性仍不支持
• 避免在 polyfill 环境下依赖 Animation.effect.getComputedTiming()，返回值可能不准，尤其涉及嵌套变换时

最后需要注意，动画时间轴并非完全独立。对同一元素叠加多个 animate() 调用时，浏览器会按插入顺序合并效果，但缓动函数和持续时间不会自动对齐，需自行计算各段动画的 delay 和 duration，否则视觉节奏可能断裂，导致卡顿感。