Web Animations API 实战:用原生 JS 写出可暂停、可编排、高性能的动画

举报
yd_246800664 发表于 2026/11/19 02:52:43 2026/11/19
【摘要】 从零掌握浏览器原生动画引擎:用 Element.animate 写关键帧动画,理解 Animation 对象与播放控制、fill 模式与复合动画,实现可暂停/回放/变速的交互动画、时间轴编排与组合动画,并对比 CSS 动画与 requestAnimationFrame 的取舍。

为什么需要 Web Animations API

做前端动画有两条老路:CSS 动画/transition 声明简单、由浏览器优化,但一旦要「暂停、倒放、跳到某一帧、动画结束再执行下一步」,就变得别扭;requestAnimationFrame 控制力最强,但关键帧、缓动、合成这些都要自己写,成本高。Web Animations API(WAAPI)正好补上中间的空白——它把 CSS 动画的能力暴露成 JavaScript 对象:既能用熟悉的关键帧语法声明动画,又能像操作对象一样 pause/play/reverse、读 currentTime、用 Promise 编排。对 transform 和 opacity 这类属性,浏览器还能放到合成线程执行,不卡主线程。

本文按「基础用法 → 关键帧与选项 → 播放控制 → 时间轴编排 → 复合动画 → 滚动驱动 → 方案对比 → 封装」的顺序,把 WAAPI 在工程里的实际用法讲清楚,代码可直接参考。

一、三行代码跑通

element.animate(关键帧, 选项) 返回一个 Animation 对象,这是整个 API 的核心。有了它,动画就不再是"写完就不管"的 CSS,而是一个可以被程序精确操控的对象。

// 最简动画:element.animate(关键帧, 选项) -> Animation 对象
const box = document.querySelector('#box');

const anim = box.animate(
  [
    { opacity: 0, transform: 'translateY(20px)' }, // 0%
    { opacity: 1, transform: 'translateY(0)' }     // 100%
  ],
  { duration: 500, easing: 'ease-out', fill: 'both' }
);

// 拿到 Animation 对象就能精确控制
anim.pause();       // 暂停
anim.play();        // 播放
anim.reverse();     // 倒放
anim.cancel();      // 取消并回到初始状态
anim.finish();      // 直接跳到结束状态

await anim.finished; // Promise:动画结束后 resolve
console.log('done');

几个关键点:animate() 调用后默认自动播放;fill: 'both' 让动画开始前和结束后都保留关键帧状态(否则结束后元素会"跳回"原样);anim.finished 是一个 Promise,动画自然结束时 resolve,被 cancel() 时 reject,用 await 编排后续逻辑非常顺手。

注意 cancel() 和 finish() 的区别:cancel 会移除动画效果、元素回到未应用动画的状态,且 finished Promise 会 reject;finish 是直接跳到终态并保持(配合 fill)。用错这两个,常出现"动画取消后元素闪回"的问题。

二、关键帧的两种写法与选项细节

关键帧支持数组和对象两种写法。数组形式可以为每一帧指定 offset(0~1 的时间位置),适合表达非均匀中间帧;对象形式把每个属性映射成值数组,浏览器自动均分时间,写起来更简洁。

// 关键帧两种写法
// 写法一:数组形式(推荐,能表达 offset 中间帧)
el.animate([
  { opacity: 0, offset: 0 },
  { opacity: 0.5, offset: 0.3 },
  { opacity: 1, offset: 1 }
], { duration: 1000 });

// 写法二:对象形式(属性 -> 值数组,浏览器自动均分)
el.animate({
  opacity: [0, 1],
  transform: ['scale(0.8)', 'scale(1)']
}, { duration: 1000, iterations: Infinity, direction: 'alternate' });

// 常用选项
{
  duration: 600,          // 时长 ms
  delay: 100,             // 延迟
  easing: 'cubic-bezier(.4,0,.2,1)', // 缓动
  iterations: 3,          // 次数,Infinity 无限
  direction: 'alternate', // 交替
  fill: 'forwards',       // 结束后保留终态:none/forwards/backwards/both
  composite: 'add'        // 与底层样式叠加方式:replace/add/accumulate
}

选项里最容易混淆的是 fill 模式:none(默认,结束后不保留)、forwards(保留终态)、backwards(延迟期间应用首帧)、both(前后都保留)。做"入场后停留在终点"的动画要用 forwards 或 both,否则结束瞬间元素会弹回原位。

composite 决定这个动画和元素底层样式(及其它动画)如何合成,默认是 replace(替换),add 是叠加。这个选项在后面讲复合动画时还会用到,是做多动画叠加的关键。

三、播放控制:暂停、拖动进度、变速

这是 WAAPI 相比 CSS 动画最大的优势。拿到 Animation 对象后,可以随时暂停、播放、倒放,直接改 currentTime 就能把动画"拖"到任意时间点,改 playbackRate 就能变速。这些在纯 CSS 动画里几乎做不到。

// 可暂停、可拖动进度的交互动画
const anim = el.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(300px)' }],
  { duration: 2000, fill: 'both', autoplay: false }
);

// 播放/暂停切换
toggleBtn.onclick = () => anim.playState === 'running' ? anim.pause() : anim.play();

// 进度条拖动:直接改 currentTime(毫秒)
seeker.oninput = (e) => { anim.currentTime = e.target.value * 20; };

// 变速:playbackRate
speedBtn.onclick = () => { anim.playbackRate = anim.playbackRate === 1 ? 2 : 1; };

// 监听状态
anim.onfinish = () => console.log('finished');
anim.oncancel = () => console.log('cancelled');

做交互型动画(比如可以拖动的进度动画、可暂停的演示)时,currentTime 是核心——它表示当前在动画时间轴上的毫秒位置,读写都可以。拖动进度条时把它的值映射过去,就能实现精准 seek。

playState 有 running / paused / finished / idle 四种状态,切换播放按钮图标时判断它即可。另外还有 pending 任务和 ready Promise,处理"播放指令已发出但还没真正开始"的时序,做精密编排时会用到。

四、时间轴编排:让多个动画按顺序入场

用 delay 配合 Promise.all 可以轻松实现错峰入场:给第 i 个元素设置 delay: i * 80,它们就会依次出现。所有动画的 finished Promise 用 Promise.all 等待,就能在全部入场后执行下一步。

// 时间轴编排:多个元素按顺序入场
async function staggerIn(elements) {
  const animations = elements.map((el, i) => el.animate(
    [{ opacity: 0, transform: 'translateY(10px)' }, { opacity: 1, transform: 'none' }],
    { duration: 300, delay: i * 80, fill: 'both', easing: 'ease-out' }
  ));
  await Promise.all(animations.map(a => a.finished));
  console.log('全部入场完成');
}

// 用 delay Negative 实现「错峰同步」:让后启动的动画对齐到同一时间轴
const a = el1.animate(kf, { duration: 1000 });
const b = el2.animate(kf, { duration: 1000, delay: -300 });
// b 立即从时间轴 300ms 处开始,视觉上已「播到三分之一」

代码里还介绍了一个进阶技巧:负 delay。给后启动的动画设置 delay: -300,它会"从这个动画时间轴的 300ms 处开始",视觉上相当于已经播到三分之一。这在需要让一个动画加入时与另一个已有动画"对齐进度"时特别有用,比如替换元素时保持连续感。

五、复合动画:多个 transform 互不覆盖

一个常见痛点是:想让元素同时水平移动和垂直移动,写两个动画分别控制 translateX 和 translateY,结果后一个动画把前一个的 transform 覆盖了。原因是 transform 是单个属性,默认 composite: 'replace' 会整体替换。

// 复合动画:多个动画叠加,互不覆盖 transform
const el = document.querySelector('#card');

// 一个动画负责水平移动
const move = el.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(200px)' }],
  { duration: 1000, fill: 'forwards' }
);

// 另一个用 composite:'add' 叠加垂直移动,而不是覆盖前一个 transform
const lift = el.animate(
  [{ transform: 'translateY(0)' }, { transform: 'translateY(-50px)' }],
  { duration: 1000, fill: 'forwards', composite: 'add' }
);

// 结果是 X + Y 同时生效;若用默认的 replace,后一个会覆盖前一个

解决办法是给第二个动画设置 composite: 'add',让它的 transform 叠加到第一个动画的结果上,而不是替换。这样 X 和 Y 位移就能同时生效。这个能力在做复杂交互动画(比如拖拽时既有位移又有缩放反馈)时非常关键。

六、滚动驱动动画:ScrollTimeline 与 ViewTimeline

WAAPI 的前沿能力是把动画进度绑定到滚动位置,而不是时间。ScrollTimeline 让动画随页面滚动推进(如滚动到某段时元素淡入),ViewTimeline 则在元素进入/离开视口时驱动动画。这是实现"滚动叙事"和视差效果的原生方案,无需监听 scroll 事件自己算进度。

// ScrollTimeline:把动画进度绑定到滚动位置(Chrome 115+)
const anim = el.animate(
  [{ opacity: 0, transform: 'translateX(-50px)' },
   { opacity: 1, transform: 'translateX(0)' }],
  {
    duration: 1, // 用滚动时间轴时 duration 会被忽略
    fill: 'both',
    timeline: new ScrollTimeline({
      scrollSource: document.scrollingElement,
      orientation: 'block',
      timeRange: 100,
      startScrollOffset: 0,
      endScrollOffset: 300
    })
  }
);

// ViewTimeline:元素进入视口时播放
const viewAnim = el.animate(kf, {
  timeline: new ViewTimeline({ subject: el, axis: 'block' })
});

使用滚动时间轴时,duration 会被忽略,动画进度由 startScrollOffset 到 endScrollOffset 的滚动区间决定。这类 API 比较新(Chrome 115+),生产环境要做好特性检测和降级——不支持时回退到普通的定时动画或 IntersectionObserver 触发。

七、和 CSS 动画 / rAF 的取舍

三种方案各有主场,不是互相替代:

  • CSS 动画/transition:声明式、简单、浏览器优化好,适合 hover 效果、简单的状态切换;缺点是不够动态、难编排。
  • requestAnimationFrame:完全手动控制每一帧,适合画布绘制、物理模拟、复杂游戏;缺点是样板代码多,缓动/关键帧要自己实现。
  • Web Animations API:介于两者之间,既有声明式关键帧和合成线程优化,又有 JS 的播放控制与 Promise 编排;适合需要交互控制的中等复杂度动画。
// CSS 动画 / transition —— 简单声明式场景,性能由浏览器优化
// .box { transition: transform .3s; }  box.classList.add('active')

// requestAnimationFrame —— 需要自己管理每一帧、做物理模拟/画布绘制
function loop(t) { render(t); requestAnimationFrame(loop); }

// Web Animations API —— 介于两者之间:
//   - 像 CSS 一样声明关键帧、由合成线程执行(transform/opacity 不卡主线程)
//   - 又像 JS 一样能 pause/play/reverse、读 currentTime、Promise 编排
const anim = el.animate([{opacity:0},{opacity:1}], {duration:300});

// 特性检测
if ('animate' in Element.prototype) {
  // 用 WAAPI
} else {
  // 降级到 CSS class 切换
}

选型建议:简单状态切换用 CSS,需要程序控制用 WAAPI,逐帧绘制用 rAF。三者可以混用——比如用 CSS 做基础过渡,用 WAAPI 做需要暂停/回放的复杂段落。

八、一个可复用的封装

实际项目里建议把常用动画封装成类或预设函数:统一默认选项(如 fill、easing)、用 Promise 暴露完成时机、组件卸载时提供 cancel 清理,避免动画持有 DOM 引用造成泄漏。

// 一个极简的动画封装:自动清理 + 结束回调 + 可复用预设
class Anim {
  constructor(el, frames, opts = {}) {
    this.anim = el.animate(frames, { fill: 'both', ...opts });
  }
  async run() { await this.anim.finished; return this; }
  pause() { this.anim.pause(); return this; }
  play() { this.anim.play(); return this; }
  seek(ms) { this.anim.currentTime = ms; return this; }
  cancel() { this.anim.cancel(); return this; }
}

// 预设:淡入上移
const fadeUp = (el, delay = 0) => new Anim(el,
  [{ opacity: 0, transform: 'translateY(12px)' }, { opacity: 1, transform: 'none' }],
  { duration: 400, delay, easing: 'cubic-bezier(.22,1,.36,1)' });

// 组件卸载时记得取消,避免动画引用 DOM 造成泄漏
await fadeUp(card).run();
// onUnmounted: anim.cancel();

这个封装把「预设 + 完成回调 + 清理」收进类里,业务代码一行就能触发一个淡入上移动画。真实项目里还可以加入中断处理(新动画打断旧动画时先 cancel)、以及 and reduced-motion 偏好检测——对开启了"减少动画"的用户,直接跳到终态而不是播放,这是无障碍的重要一环。

性能与注意事项

WAAPI 对 transform 和 opacity 的动画能交给合成线程执行,不触发布局和重绘,性能最好;对 width、height、top 等触发 layout 的属性,仍会走主线程,要谨慎使用。动画结束后如不再需要,调用 cancel() 释放资源。另外要留意 finished Promise 在被 cancel 时会 reject,用 await 时要 catch,避免未处理的 Promise rejection。

小结

Web Animations API 把 CSS 动画的声明式能力带到了 JavaScript 世界:用 animate() 定义关键帧,用 Animation 对象做暂停、倒放、seek、变速,用 finished Promise 编排时序,用 composite 叠加复合动画。掌握四个要点就能用好它——fill 模式决定终态是否保留、currentTime 是进度控制的核心、composite 解决 transform 覆盖、finished Promise 用于编排。下次遇到"动画要能暂停/回放/衔接"的需求,别再纠结 CSS 还是 rAF 了,WAAPI 是更合适的中间选择。

本文为原创实践记录,所有示例均为原生 JavaScript、零依赖,可直接在现代浏览器运行验证,欢迎交流更优雅的动画编排方案。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。