CSS 动画 Worklet API

[Exposed=Window]
partial namespace CSS {
    [SameObject] readonly attribute Worklet animationWorklet;
};

[Exposed=AnimationWorklet, Global=AnimationWorklet, Constructor (optional any options)]
interface StatelessAnimator {
};

class FooAnimator extends StatelessAnimator {
    constructor(options) {
        // 当一个新的动画师被实例化时调用。
    }
    animate(currentTime, effect) {
        // 动画帧逻辑在此。
    }
}

[Exposed=AnimationWorklet, Global=AnimationWorklet,
Constructor (optional any options, optional any state)]
interface StatefulAnimator {
  any state();
};

class BarAnimator extends StatefulAnimator {
    constructor(options, state) {
      // 当一个新的动画师被实例化时（无论是首次还是重新生成后）。
      this.currentVelocity  = state ? state.velocity : 0;
    }
    animate(currentTime, effect) {
        // 动画帧逻辑在此，可以依赖 this.currentVelocity。
        this.currentVelocity += 0.1;
    }
    state() {
      // 返回的对象应使用结构化克隆算法进行序列化。
      return {
        velocity: this.currentVelocity;
      }
    }
}

[ Exposed=AnimationWorklet, Global=AnimationWorklet ]
interface AnimationWorkletGlobalScope : WorkletGlobalScope {
    void registerAnimator(DOMString name, AnimatorInstanceConstructor animatorCtor);
};

callback AnimatorInstanceConstructor = any (any options, optional any state);

当在AnimationWorkletGlobalScope 中调用 registerAnimator(name, animatorCtor) 方法时，用户代理必须运行以下步骤：

1. 如果 name 不是有效的 <标识符>，抛出 TypeError 并中止这些步骤。

2. 如果 name 作为键存在于动画师名称到动画师定义的映射中，抛出 NotSupportedError 并中止所有这些步骤。

3. 如果 IsConstructor(animatorCtor) 的结果为 false， 抛出 TypeError 并中止所有这些步骤。

4. 令 prototype 为调用 Get(animatorCtor, "prototype") 的结果。

5. 如果 SameValue(prototype, 无状态动画师) 为 true，则将 stateful 设置为 false，否则如果 SameValue(prototype, 有状态动画师) 为 true，则将 stateful 设置为 true，否则抛出 TypeError 并中止所有这些步骤。

6. 令 animateValue 为调用 Get(prototype, "animate") 的结果。

7. 令 animate 为 转换 animateValue 为 函数 回调函数 类型的结果。如果抛出异常，请重新抛出异常并中止这些步骤。

8. 令 definition 为新的 动画师定义，其中包括：

   • 动画师名称 为 name

   • 类构造函数 为 animatorCtor

   • 动画函数 为 animate

   • 有状态标志 为 stateful

9. 将键值对 (name - definition) 添加到 动画师名称到动画师定义的映射 中。

给定 name、timeline、effect、 serializedOptions、serializedState 和 workletGlobalScope，要创建 一个新的动画器实例，用户 代理必须运行以下步骤：

1. 令 definition 为在 workletGlobalScope 的动画器名称到动画器定义 映射中查找 name 的结果。

   如果 definition 不存在，则中止以下步骤。

2. 令 animatorCtor 为 definition 的类构造函数。

3. 令 options 为 StructuredDeserialize(serializedOptions)。

4. 令 state 为 StructuredDeserialize(serializedState)。

5. 令 animatorInstance 为以 «options, state» 作为参数构造 animatorCtor 的结果。如果抛出异常，则重新抛出该 异常并 中止所有这些步骤。

6. 在 animatorInstance 上设置以下内容：

   • 动画器 名称为 name

   • 动画请求标志为当前帧

   • 动画器当前时间为未解析

   • 动画器 效果为 effect

   • 动画器 时间线为 timeline

   • 动画器序列化选项为 options

7. 将 animatorInstance 添加到 workletGlobalScope 的动画器实例集合中。

当用户代理想要在给定的workletGlobalScope中运行动画器时，它必须遍历workletGlobalScope中的所有动画器实例，并迭代workletGlobalScope的动画器实例集。对于每个这样的实例，用户代理必须执行以下步骤：

1. 令animatorName为instance的动画师名称

2. 令definition为在workletGlobalScope的动画师名称到动画师定义映射中查找animatorName的结果。

   如果definition不存在，则中止以下步骤。

3. 如果instance的动画请求标志为当前帧， 或者instance所属的效果不会在当前帧的可视视口内可见，用户代理可以中止所有后续步骤。

   可以考虑允许用户代理跳过运行动画师实例，以限制缓慢的动画师。

4. 令animateFunction为definition的动画函数。

5. 令currentTime为instance的动画师当前时间。

6. 令effect为instance的动画师效果。

7. 调用animateFunction，参数为«currentTime，effect»， 并以instance作为回调的 this 值。

为给定的instance和workletGlobalScope移除一个动画师实例，用户代理必须执行以下步骤：

1. 将instance从workletGlobalScope的动画师实例集中移除。

要将一个动画师实例迁移从一个WorkletGlobalScope 迁移到另一个，给定instance、sourceWorkletGlobalScope和 destinationWorkletGlobalScope，用户代理必须执行以下步骤：

1. 令serializedState未定义。

2. 在sourceWorkletGlobalScope上排队一个任务，执行以下步骤：

   1. 令animatorName为instance的动画师名称

   2. 令definition为在sourceWorkletGlobalScope的动画师名称到动画师定义映射中查找animatorName的结果。

      如果definition不存在，则中止以下步骤。

   3. 令stateful为definition的有状态标志。

   4. 如果stateful为false，则中止以下步骤。

   5. 令stateFunction为instance的状态函数。

   6. 令state为调用stateFunction的结果，调用时，instance作为回调的 this 值。如果抛出任何异常，请重新抛出异常并中止 以下步骤。

   7. 将serializedState设置为结构化序列化(state)的结果。 如果抛出任何异常，则中止以下步骤。

   8. 执行移除动画师实例的过程，给定 instance和sourceWorkletGlobalScope。

3. 等待上述任务完成。如果任务中止，停止以下步骤。

4. 在destinationWorkletGlobalScope上排队一个任务，执行以下步骤：

   1. 执行创建新的动画师实例的过程， 给定以下参数：

      • instance的动画师名称作为名称。

      • instance的动画师时间线作为时间线。

      • instance的动画师效果作为效果。

      • instance的动画师序列化选项作为选项。

      • serializedState作为状态。

      • destinationWorkletGlobalScope作为 workletGlobalScope。

[Exposed=Window,
 Constructor (DOMString animatorName,
              optional (AnimationEffect or sequence<AnimationEffect>)? effects = null,
              optional AnimationTimeline? timeline,
              optional any options)]
interface WorkletAnimation : Animation {
        readonly attribute DOMString animatorName;
};

WorkletAnimation(animatorName, effects, timeline, options)

使用以下过程创建一个新的 WorkletAnimation 对象。

1. 令 workletAnimation 为一个新的 WorkletAnimation 对象。

2. 在 workletAnimation 上运行设置动画的时间线过程， 将 timeline 作为新的时间线传入；如果未提供 timeline 参数， 则传入与作为当前全局对象的 Window 关联的 Document 的默认文档时间线。

3. 令 effect 为与下面第一个匹配条件相对应的结果。

   如果 effects 是一个 AnimationEffect 对象，

   令 effect 为 effects。

   如果 effects 是一个由 AnimationEffect 对象组成的列表，

   令 effect 为一个新的 WorkletGroupEffect， 并将其子项设置为 effects。

   否则，

   令 effect 为 undefined。

4. 在 workletAnimation 上运行设置动画的目标效果过程， 将 effect 作为新的效果传入。

5. 令 serializedOptions 为 StructuredSerialize(options) 的结果。 重新抛出任何异常。

6. 将 workletAnimation 的序列化选项设置为 serializedOptions。

7. 将 workletAnimation 的动画的动画器名称设置为 animatorName。

给定 workletAnimation，要关联 worklet 动画的动画器实例， 用户代理必须运行以下步骤：

1. 如果 workletAnimation 有对应的动画器实例，则中止 以下步骤。

2. 令 workletGlobalScope 为与 workletAnimation 关联的 AnimationWorkletGlobalScope。

3. 在 workletGlobalScope 上排入一个任务，以运行 创建新的动画器 实例的过程，并传入：

   • 将 workletAnimation 的动画的动画器名称作为 name。

   • 将 workletAnimation 的时间线作为 timeline。

   • 将 workletAnimation 的动画效果作为 effect。

   • 将 workletAnimation 的序列化选项作为 options。

   • 将 workletGlobalScope 作为 workletGlobalScope。

4. 如果该过程成功，则将所得的动画器实例设置为 与 workletAnimation 对应。

给定 workletAnimation，要解除 worklet 动画的动画器实例关联，用户代理必须运行以下 步骤：

1. 如果 workletAnimation 没有对应的动画器实例，则中止 以下步骤。

2. 令 workletGlobalScope 为与 workletAnimation 关联的 AnimationWorkletGlobalScope。

3. 令 animatorInstance 为 workletAnimation 对应的动画器 实例。

4. 在 workletGlobalScope 上排入一个任务，以运行 移除动画器 实例的过程，将 animatorInstance 作为 instance，并将 workletGlobalScope 作为 workletGlobalScope 传入。

5. 将 workletAnimation 设置为没有对应的动画器实例。

给定 workletAnimation，要设置 worklet 动画的动画器实例， 用户代理必须运行以下步骤：

1. 给定 workletAnimation，解除 worklet 动画的动画器 实例关联。

2. 给定 workletAnimation，关联 worklet 动画的动画器实例。

[Exposed=AnimationWorklet]
interface WorkletGroupEffect {
  sequence<AnimationEffect> getChildren();
};

[Exposed=AnimationWorklet]
partial interface AnimationEffect {
    // 用于Animation Worklet范围内驱动效果。
    attribute double localTime;
};

为了将t值设置为effect的localTime属性， 用户代理应执行以下第一个匹配条件对应的操作：

如果effect没有父组，

将effect的本地时间设置为t。

如果effect有父组，且父组类型为WorkletGroupEffect，

将效果开始时间设置为（父级的变换时间- t）。注意这实际上设置了effect的本地时间为t。

否则

抛出一个异常，指出子效果时间只能由其父组控制。

// 在文档范围内。
<div id='scrollingContainer'>
  <div id='header' style='height: 150px'></div>
  <div id='avatar'><img></div>
</div>

<script>
await CSS.animationWorklet.addModule('twitter-header-animator.js');
const animation = new WorkletAnimation(
    'twitter-header',
    [new KeyframeEffect($avatar,  /* 向上滚动时缩放 */
                    [{transform: 'scale(1)'}, {transform: 'scale(0.5)'}],
                    {duration: 1000, iterations: 1}),
    new KeyframeEffect($header, /* 向上滚动时透明度降低 */
                    [{opacity: 0}, {opacity: 0.8}],
                    {duration: 1000, iterations: 1})],
    new ScrollTimeline({
      scrollSource: $scrollingContainer,
      orientation: 'block',
      timeRange: 1000,
      startScrollOffset: 0,
      endScrollOffset: $header.clientHeight}));
animation.play();

// 由于此动画使用的是组效果，同一动画实例可以通过不同的句柄访问：$avatarEl.getAnimations()[0], $headerEl.getAnimations()[0]

</script>

// 在AnimationWorkletGlobalScope内。
registerAnimator('twitter-header', class HeaderAnimator extends StatelessAnimator {
  constructor(options) {
    this.timing_ = new CubicBezier('ease-out');
  }

  animate(currentTime, effect) {
    const scroll = currentTime;  // 滚动值在[0, 1000]范围内

    // 通过单独设置其子效果的本地时间来驱动输出组效果。
    effect.children[0].localTime = scroll;
    effect.children[1].localTime = this.timing_(clamp(scroll, 0, 500));
  }
});

function clamp(value, min, max) {
  return Math.min(Math.max(value, min), max);
}

<style>
.parallax {
    position: fixed;
    top: 0;
    left: 0;
    opacity: 0.5;
}
</style>
<div id='scrollingContainer'>
  <div id="slow" class="parallax"></div>
  <div id="fast" class="parallax"></div>
</div>

<script>
await CSS.animationWorklet.addModule('parallax-animator.js');
const scrollTimeline = new ScrollTimeline({
  scrollSource: $scrollingContainer,
  orientation: 'block',
  timeRange: 1000
});
const scrollRange = $scrollingContainer.scrollHeight - $scrollingContainer.clientHeight;

const slowParallax = new WorkletAnimation(
    'parallax',
    new KeyframeEffect($parallax_slow, [{'transform': 'translateY(0)'}, {'transform': 'translateY(' + -scrollRange + 'px)'}], {duration: 1000}),
    scrollTimeline,
    {rate : 0.4}
);
slowParallax.play();

const fastParallax = new WorkletAnimation(
    'parallax',
    new KeyframeEffect($parallax_fast, [{'transform': 'translateY(0)'}, {'transform': 'translateY(' + -scrollRange + 'px)'}], {duration: 1000}),
    scrollTimeline,
    {rate : 0.8}
);
fastParallax.play();
</script>

// 在 AnimationWorkletGlobalScope 内。
registerAnimator('parallax', class ParallaxAnimator extends StatelessAnimator {
  constructor(options) {
    this.rate_ = options.rate;
  }

  animate(currentTime, effect) {
    effect.localTime = currentTime * this.rate_;
  }
});