Web Animation API

October 31, 2023

Web Animation API

这里主要写一下在 Javascript 中操纵 Web Animation API，CSS 的部分有所省略。

Useful links to learn CSS animation itself:
https://www.joshwcomeau.com/animation/keyframe-animations/
https://www.cnblogs.com/coco1s/p/15796478.html

Animation() 构造函数用于创建 Animation 实例，该实例是一个 EventTarget，可用于监听动画事件和控制动画。
正如构造函数定义的，一个 Animation 由 AnimationEffect 和 AnimationTimeline 构成。
effect 声明动画效果，timeline 声明动画进行到哪一步。

KeyframeEffect 实现了 AnimationEffect 接口，是目前唯一的动画效果。它可以给指定元素（或伪元素）声明关键帧动画。
Element.animate() 方法是一个快捷函数，可以直接在某个元素上创建 KeyframeEffect 动画并开始运行动画。

const element = document.querySelector(".target");

const keyframes = [{ rotate: "0deg" }, { rotate: "360deg" }];
// or:  const keyframes = { rotate: ["0deg", "360deg"] };
const options = { duration: 3000, fill: "forwards" as const };
// or: const options = 3000;
const effect = new KeyframeEffect(element, keyframes, options);

const timeline = document.timeline; // 默认时间轴

const animation = new Animation(effect, timeline);

animation.play();

// or:
element.animate(keyframes, options);

Typescript 定义

AnimationEffect 动画效果

AnimationEffect <|-- KeyframeEffect

KeyframeEffect

目前只有 KeyframeEffect，即关键帧效果

AnimationTimeline 动画时间轴

AnimationTimeline <|-- DocumentTimeline
AnimationTimeline <|-- ScrollTimeline
ScrollTimeline <|-- ViewTimeline

DocumentTimeline

时间驱动的时间轴

默认情况下，附加在一个元素上的动画在文档时间轴 (DocumentTimeline) 上运行。
当网页加载时，它的起源时间从 0 开始，并随时间顺序增加。

ScrollTimeline

连接到某个滚动容器沿着特定轴（如：水平方向或竖直方向）的滚动位置（即滚动了多少距离）的时间轴。
它将滚动范围内的位置转换为进度的百分比。开始滚动位置表示 0% 进度，结束滚动位置表示 100% 进度。

参考： https://developer.chrome.com/articles/scroll-driven-animations/#scroll-progress-timeline

const timeline = new ScrollTimeline({
    source: document.documentElement,
    axis: "block",
});

CSS 属性 scroll-timeline-name 声明一个以双横线开头的名称，应用在滚动容器上。
scroll-timeline-axis 属性声明监听滚动的方向。
scroll-timeline 属性是以上两个属性的简写。

CSS 属性 animation-timeline 则可以引用此名称，这就将当前元素动画的时间轴设置为该滚动容器的 ScrollTimeline

animation-timeline 也可以指定为 scroll()

ViewTimeline

连接到特定元素在其滚动容器中的相对位置的时间轴

参考：https://developer.chrome.com/articles/scroll-driven-animations/#getting-practical-with-view-progress-timeline

const timeline = new ViewTimeline({
    subject: document.querySelector(".subject"),
    axis: "block",
    inset: [CSS.px("200"), CSS.px("300")],
});

$el.animate(
    {
        opacity: [0, 1],
    },
    {
        timeline,
        rangeStart: "entry 25%",
        rangeEnd: "cover 50%",
    },
);

与上面的 scroll-timeline 类似的是：

CSS 属性 view-timeline-name 声明一个自定义名称，定义在监听可见性的元素上。
view-timeline-axis 属性声明监听可见性的方向。
view-timeline 属性是以上两个属性的简写。

同理，CSS 属性 animation-timeline 可以引用此名称，这就将当前元素动画的时间轴设置为该元素的 ViewTimeline （在同一个元素上设置 view-timeline-name 然后用 animation-timeline 引用自身是很常见的用法，这也相当于直接将 animation-timeline 设置为 view() ，参见下面的演示）

此外还可以使用 view-timeline-inset 属性可指定一个或两个值，用于指定偏移时间线位置的开始和/或结束插入（或结束）值。

animation-timeline 也可以指定为 view()