Web Animations API 深度实践：从关键帧到时序控制的浏览器原生动画引擎

Web Animations API 深度实践：从关键帧到时序控制的浏览器原生动画引擎

一、CSS 动画与 JS 动画的断层：为什么需要 Web Animations API

CSS@keyframes和transition适合声明式的简单动画，但缺乏动态控制能力——无法在运行时修改关键帧、无法精确控制播放进度、无法基于滚动位置驱动动画。JavaScript 动画（requestAnimationFrame）提供了完全控制力，但需要手动计算插值、管理帧率和处理性能优化，代码复杂度高。

Web Animations API（WAAPI）是浏览器的原生动画引擎，将 CSS 动画的声明式语法与 JavaScript 的命令式控制力统一。它允许开发者用 JavaScript 创建和管理动画，同时享受浏览器硬件加速和合成器线程的优势。

二、WAAPI 核心机制：从关键帧定义到时序控制

flowchart TD A[Animation 构造] --> B[Keyframe 定义<br/>属性值 + 偏移量] A --> C[Timing 参数<br/>时长/缓动/延迟/迭代] B --> D[Animation 对象] C --> D D --> E[播放控制<br/>play/pause/reverse/cancel] D --> F[进度控制<br/>currentTime/playbackRate] D --> G[事件监听<br/>finish/cancel/remove] E --> H[合成器线程渲染<br/>硬件加速]

WAAPI 的核心优势在于动画运行在合成器线程——不阻塞主线程的 JavaScript 执行。这意味着即使主线程繁忙（如处理大量数据），动画仍然流畅。CSS 动画也运行在合成器线程，但 WAAPI 提供了运行时修改的能力。

三、工程实现：关键帧动画、时序控制与滚动驱动

3.1 关键帧动画

// 基础关键帧动画 const fadeInUp: Keyframe[] = [ { opacity: 0, transform: 'translateY(20px)', offset: 0, // 0% }, { opacity: 1, transform: 'translateY(0)', offset: 1, // 100% }, ]; const timing: KeyframeAnimationOptions = { duration: 600, easing: 'cubic-bezier(0.16, 1, 0.3, 1)', // easeOutExpo fill: 'forwards', }; const animation = element.animate(fadeInUp, timing); // 交错动画：列表项依次出现 function staggerAnimation( elements: Element[], keyframes: Keyframe[], options: KeyframeAnimationOptions, staggerDelay: number = 100 ): Animation[] { return elements.map((el, index) => { return el.animate(keyframes, { ...options, delay: (options.delay || 0) + index * staggerDelay, }); }); } // 使用 const items = document.querySelectorAll('.list-item'); staggerAnimation(Array.from(items), fadeInUp, timing, 80);

3.2 时序控制与组合

// 动画组合：多个动画协同播放 class AnimationTimeline { private animations: Map<string, Animation> = new Map(); add(name: string, element: Element, keyframes: Keyframe[], options: KeyframeAnimationOptions): void { const animation = element.animate(keyframes, { ...options, // 关键：使用 fill: 'both' 保持动画首尾状态 fill: 'both', }); this.animations.set(name, animation); } // 顺序播放：A 完成后播放 B async sequence(names: string[]): Promise<void> { for (const name of names) { const animation = this.animations.get(name); if (animation) { animation.play(); await animation.finished; } } } // 并行播放：A 和 B 同时播放 parallel(names: string[]): void { for (const name of names) { const animation = this.animations.get(name); if (animation) { animation.play(); } } } // 交错组：组内交错，组间顺序 async staggeredGroups( groups: string[][], groupDelay: number = 200 ): Promise<void> { for (const group of groups) { const promises = group.map((name, index) => { const animation = this.animations.get(name); if (animation) { animation.currentTime = 0; animation.playbackRate = 1; // 组内交错延迟 return new Promise<void>(resolve => { setTimeout(() => { animation.play(); animation.finished.then(() => resolve()); }, index * 80); }); } return Promise.resolve(); }); await Promise.all(promises); // 组间延迟 await new Promise(r => setTimeout(r, groupDelay)); } } }

3.3 滚动驱动动画

// 基于 ScrollTimeline 的滚动驱动动画 // 注意：ScrollTimeline 是较新的 API，需要特性检测 class ScrollDrivenAnimation { private observer: IntersectionObserver | null = null; attach(element: Element, keyframes: Keyframe[], options: { threshold?: number } = {}): void { // 检测 ScrollTimeline 支持 if ('ScrollTimeline' in window) { this.attachNative(element, keyframes); } else { // 降级：使用 IntersectionObserver this.attachFallback(element, keyframes, options.threshold || 0.2); } } private attachNative(element: Element, keyframes: Keyframe[]): void { const scrollTimeline = new ScrollTimeline({ source: document.scrollingElement!, orientation: 'vertical', }); element.animate(keyframes, { timeline: scrollTimeline, fill: 'both', }); } private attachFallback( element: Element, keyframes: Keyframe[], threshold: number ): void { this.observer = new IntersectionObserver( (entries) => { for (const entry of entries) { if (entry.isIntersecting) { element.animate(keyframes, { duration: 600, easing: 'cubic-bezier(0.16, 1, 0.3, 1)', fill: 'forwards', }); this.observer?.unobserve(element); } } }, { threshold } ); this.observer.observe(element); } // 视差效果：基于滚动位置的位移 attachParallax( element: Element, speed: number = 0.5 ): void { let ticking = false; window.addEventListener('scroll', () => { if (!ticking) { requestAnimationFrame(() => { const scrollY = window.scrollY; const offset = scrollY * speed; element.animate( [{ transform: `translateY(${offset}px)` }], { duration: 0, fill: 'forwards' } ); ticking = false; }); ticking = true; } }, { passive: true }); } }

3.4 动画性能监控

class AnimationPerformanceMonitor { private frameTimes: number[] = []; startMonitoring(animation: Animation): void { const measureFrame = () => { const start = performance.now(); requestAnimationFrame(() => { const frameTime = performance.now() - start; this.frameTimes.push(frameTime); if (animation.playState === 'running') { measureFrame(); } }); }; measureFrame(); } getReport(): { avgFrameTime: number; p95FrameTime: number; droppedFrames: number; } { const sorted = [...this.frameTimes].sort((a, b) => a - b); const avg = sorted.reduce((a, b) => a + b, 0) / sorted.length; const p95 = sorted[Math.floor(sorted.length * 0.95)]; const dropped = sorted.filter(t => t > 16.67).length; return { avgFrameTime: avg, p95FrameTime: p95, droppedFrames: dropped, }; } }

四、WAAPI 的兼容性与性能边界

浏览器支持的渐进性：WAAPI 的核心 API（animate、play、pause）在所有现代浏览器中支持，但高级特性（ScrollTimeline、ViewTimeline、GroupEffect）仅在 Chrome 115+ 中支持。Safari 和 Firefox 的支持进度较慢。生产环境需要特性检测和降级方案。

合成器线程的限制：只有transform和opacity属性的动画可以在合成器线程运行。其他属性（如width、height、box-shadow）的动画会触发布局重计算，阻塞主线程。使用 WAAPI 时仍需遵循"仅动画 transform 和 opacity"的性能原则。

动画取消的资源泄漏：Animation 对象在取消后仍持有对 DOM 元素的引用。如果频繁创建和取消动画（如列表滚动时），可能导致内存泄漏。建议使用动画池复用 Animation 对象，或在动画完成后调用animation.cancel()释放引用。

fill: 'forwards'的层叠问题：fill: 'forwards'使动画保持最终状态，但这个状态通过"动画层"覆盖在原始样式之上。如果后续通过 JavaScript 修改同一属性，修改可能被动画层覆盖。解决方案是动画完成后移除动画（animation.commitStyles()+animation.cancel()），将最终状态写入行内样式。

五、总结

Web Animations API 的核心价值在于"声明式定义 + 命令式控制"——用 CSS 风格的关键帧定义动画，用 JavaScript 精确控制播放、进度和时序。本文方案的核心模式为：关键帧定义 → 时序参数配置 → 播放控制与组合 → 滚动驱动 → 性能监控。落地时需重点关注三个原则：仅动画 transform 和 opacity（确保合成器线程运行）、使用 fill: 'both' 保持状态、动画完成后 commitStyles 并 cancel。建议从简单的入场动画开始使用 WAAPI，逐步替代 requestAnimationFrame 手写动画，并建立动画组件库统一管理关键帧和时序参数。