Web Animations
撰写时间：2026-03-02
修订时间：2026-03-04
概述
Web Animations是 Web 平台呈现变化的时序同步规范。其他相关规范应基于本规范、通过声明的方式来展现这些特性。它同时定义了一组APIs，可通过脚本对动画进行精细的控制。
本文一些地方在需要呈现位置的动画效果时，将使用SVG来呈现动画，因为相对于CSS，SVG有更好的绝对定位及内在的坐标系转换机制。
CSS Animations 的本质
CSS Animations 与 Web Animations 的关系
本站的CSS Animations详细介绍了CSS Animations，而其本质就是Web Animations。下面代码说明了此点。
使用CSS Animations为一个div元素设置了一个背景颜色变化的动画，然后调用该元素的getAnimations方法，返回只有一个元素的数组，该元素类型为CSSAnimation，继承于Animation。而Animation正是Web Animations的核心对象。
因此，CSS Animations的本质就是Web Animations。
深入动画细节
上面代码声明了一段动画，动画时长为9秒，设置了3个关键帧（故每帧动画时长3秒），背景颜色依序从红、绿、蓝变化。
我们在第0秒时将背景设置为红色，在第3秒开始时将背景颜色为绿色，在第6秒开始时将背景颜色为绿色。这些手工设置的帧，称为关键帧 (keyframe)。而从动画效果来看，除了我们显式地设置的3个关键帧之外，系统还帮我们设置了在其他帧时的背景颜色，以实现平滑的动画过滤效果。这些由系统自动设置的帧，称为关键帧插值 (keyframe interpolation)。
因此，div元素在9秒之内，被自动设置了较多的背景颜色。
我们能否获知，在特定的时间点，div元素的背景颜色是什么？
仅通过CSS Animations技术肯定不行，因为它只是通过声明的方式定义了一组关键帧，系统据此渲染为动画，然后任务就完成了。我们无从得知具体内幕细节。
当我们声明了一组动画关键帧后，在各个不同的时间点，div背景颜色虽总是处于不断变化的状态，但在特定时间点，其背景颜色的状态是确定的，这些状态必定存储于某个地方。Web Animations中的Animation对象正好充当这个存储池。它记录了元素在时间轴 (timeline) 上的各个时间点时的不同状态。
明白上述这些基本的动画术语，有助于我们了解、掌握Web Animations的相关技术。
初识Animation对象
Animation对象的属性及方法
下面分类打印出CSSAnimation的属性及其方法。
可以看出，CSSAnimation继承于Animation。与原型相比，CSSAnimation只多出了一个animationName的属性，因此上面分类打印的效果可视为打印Animation的属性及方法。
动画就绪与结束时的回调
在动画准备就绪时，我们可以调用Animation的ready方法，返回一个注入了Animation实例的Promise对象。
所注入的animObj与animation是同一对象。上面代码，在动画就绪时，我们调用animObj的pause方法以暂停动画播放，并打印其playState以查看其当前播放状态。
pause方法可以不必放在ready的回调函数中进行调用。默认情况下，通过CSS Animations所声明的动画，在准备就绪时会调用其play方法以自动播放。如果希望取消这种自动播放的功能，可直接调用其pause方法以暂停播放。
同理，在动画播放完毕时，我们可以调用Animation的finished方法，返回一个注入了同一Animation实例的Promise对象。
与时间戳相关的属性
timeline
Animation的timeline属性，其类型为DocumentTimeline，原型为AnimationTimeline，用于同步时间值。
默认值被设置为：
因此，这两个timeline属性值都指向同一对象。
当页面加载时，document的timeline属性值所向的DocumentTimeline对象将被自动创建，其currentTime属性为自页面加载以来所流逝的毫秒值。
startTime
Animation的startTime属性表示动画开始的时间戳。
startTime属性值受ready属性值的影响。即使显式地调用play方法（默认行为），startTime的值仍为null。只当动画准备就绪时，startTime的值才被设置为时间轴线上当前时间值。
startTime属性值同时受动画是否已经开始播放的影响。
当一开始时，立即调用pause方法以暂停播放，此时，即使动画已经准备就绪，startTime的值仍为null值。只有当开始播放时，startTime才被赋值。
有时会不小心掉入陷阱：
我们已经依序
设置了ready就绪的代码，以及开始播放，但为何开始播放后，startTime的值仍为null？
因为ready所返回的Promise中的代码在主线程中将延后执行。最简便的解决方案是：
在主线程中等待动画就绪，再使用startTime属性值。
currentTime
Animation的currentTime属性表示自动画开始以来的时间偏移值。
一开始，currentTime的初始值为0，即使动画还未就绪、还未开始播放。
由于动画默认一开始就自动运行，因此若将上面的animation.pause();语句屏蔽掉，则该值不为0。
动画开始播放后，存在以下的等量关系：
可通过设置currentTime的值，将动画时间戳的偏移值调节到指定的位置，然后，直接读取元素在该时间戳的动画样式值。
动画时长为3秒，先暂停动画播放，然后来到动画总时长的一半的位置，查看元素在该时间点位置上的CSS样式值。
这种向currentTime直接赋值的方式，将导致系统自动同步所有的内部状态后，再返回结果。
若将上面的animation.pause();语句屏蔽，则将从当前位置开始播放动画。