Web动画模块 第二级

1. 差异规范

这是一个差异规范，这意味着目前仅包含与 Web Animations Level 1 [WEB-ANIMATIONS-1] 的不同之处。当第一级规范接近完成时，将会把这里的新增内容与其合并，形成完整的第二级规范。

2. 时间模型

本节描述并定义了 Web Animations 时间模型的行为。

2.1. 时间模型概述

本节为非规范性内容

2.1.1. 分层结构

本级规范包含了更新后的时间层级结构示意图。

以及以下更新描述：

这种分层结构带来的结果是，复杂的动画可以作为一个整体被反转、调度、加速等，因为对父节点的操作会层叠到其后代上。此外，由于时间有共同的来源，动画的同步也变得很容易。

2.2. 时间线

新增：

时间线时长 指的是时间线可以为其当前时间生成的最大值。此值用于计算与该时间线关联的动画目标效果的固有迭代时长，当该效果的迭代时长为 "auto" 时。该值的计算方式是让效果填满可用时间。对于单调递增的时间线，当前时间没有上限，时间线时长为未定。对于非单调的（例如滚动）时间线，时长有固定的上限。在这种情况下，该时间线是基于进度的时间线，其 时间线时长 为 100%。

2.3. 动画帧

为算法第一步的说明更新，添加如下内容：

• 通过执行更新动画触发器状态过程，更新动画触发器的状态。

2.4. 动画

附加：

与基于进度的时间线关联的动画效果需要将其时间属性转换为比例。将的过程如下：

1. 如果迭代时长为 auto，执行以下步骤。

   • 将起始延迟和结束延迟设置为 0，因为不能混合时间与比例。

     注意: 未来版本可能允许这些属性赋值为百分比；届时，仅当其值用时间表示时才应忽略延迟，百分比则不受影响。

   否则：

   1. 令 总时长 等于结束时间

   2. 将起始延迟设为 指定起始延迟 / 总时长 * 时间线时长 的结果。

   3. 将迭代时长设为 指定迭代时长 / 总时长 * 时间线时长 的结果。

   4. 将结束延迟设为 指定结束延迟 / 总时长 * 时间线时长 的结果。

将规格化指定的计时的过程如下：

如果时间线时长已确定：

• 遵循将基于时间的动画转换为比例动画的过程。

否则：

1. 将起始延迟 = 指定起始延迟

2. 将结束延迟 = 指定结束延迟

3. 如果迭代时长为 auto：

   • 将迭代时长 = 固有迭代时长

   否则：

   • 将迭代时长 = 指定迭代时长

2.4.1. 设置动画的时间线

将设定动画的时间线 animation 为 new timeline，可能为 null 的过程如下：

1. 令 old timeline 为 animation 当前的时间线（如果有）。

2. 如果 new timeline 与 old timeline 为同一对象，则终止此过程。

3. 令 previous play state 为 animation 的播放状态。

4. 令 previous current time 为 animation 的当前时间。

5. 根据以下条件设置 previous progress：

   如果 previous current time 未定：

   将 previous progress 设为未定。

   如果结束时间为0：

   将previous progress设为0。

   否则

   将previous progress = previous current time / 结束时间

6. 当old timeline 非 null 且非单调递增时，from finite timeline 为 true。

7. 当 timeline 非 null 且非单调递增时，to finite timeline 为 true。

8. 将 animation 的时间线设为 new timeline。

9. 按下列首个匹配条件执行步骤：

   如果 to finite timeline

   1. 对 animation应用所有待处理播放速率

   2. 令 auto align start time 为 true。

   3. 将起始时间设为未定。

   4. 将保持时间设为未定。

   5. 如果previous play state为"finished"或"running"

      1. 安排一个待播放任务

   6. 如果previous play state为"paused"且previous progress已定：

      1. 将保持时间设为 previous progress × 结束时间。

   此步骤确保即使是处于待暂停状态且起始时间已定的动画，previous progress也能被保留。

   如果from finite timeline且previous progress已定，

   运行设置当前时间的过程，参数为previous progress × 结束时间。

10. 如果animation的起始时间为未定，将animation的保持时间设为未定。

    此步骤确保animation的完成播放状态不会“粘住”，而是会根据其更新后的当前时间重新评估。

11. 以 did seek 标记为 false，synchronously notify 标记为 false，运行更新动画完成状态过程。

2.4.2. 设置动画的目标效果

在重新安排待播放任务的步骤后，添加以下步骤：

1. 如果new effect不为null且new effect拥有父组，则将new effect从其父组移除。

2.4.3. 等待关联效果

替换：

动画在以下两个条件均成立的最早时刻准备就绪：

• 用户代理已完成开始播放该动画关联效果所需的任何准备，包括渲染第一帧关键帧效果。

• 动画已关联到非不活动的时间线。

修改为：

动画在以下所有条件均成立的最早时刻准备就绪：

• 用户代理已完成开始播放动画的每个包含后代所需的准备，包括渲染任一关键帧效果，或执行与自定义效果关联的动画效果。

• 动画关联到非不活动的时间线。

• 动画的保持时间或起始时间已定。

注意: 没有起始时间或保持时间时动画并不准备就绪。对于滚动驱动动画，如果 auto align start time 为 true，则会在更新时间线时确定起始时间。

2.4.4. 校验 CSSNumberish 时间值

用于输入值 time 的校验 CSSNumberish 时间值的过程，基于首个匹配条件如下：

如果全部如下条件为真：

• 动画关联于基于进度的时间线，并且

• time不是带百分比单位的 CSSNumeric 值：

抛出 TypeError。

返回 false；

如果全部如下条件为真：

• 动画未关联于基于进度的时间线，并且

• time是 CSSNumericValue，并且

• time 的单位不是持续时间单位：

抛出 TypeError。

返回 false。

否则

返回 true。

2.4.5. 设置 Animation 的当前时间

动画的当前时间可以被设置为新值，从而定位（seek）动画。设置当前时间的流程分为两部分。

静默设置当前时间的过程如下，将动画 animation 的当前时间设为 seek time：

1. 如果 seek time 是未定时间值，则执行以下步骤。

   1. 如果当前时间为已定，则抛出 TypeError。

   2. 终止这些步骤。

2. 令 valid seek time 为以 seek time 作为输入，执行校验 CSSNumberish 时间值过程的结果。

3. 如果 valid seek time 为 false，则终止此过程。

4. 设置 auto align start time 为 false。

5. 如下所示，更新 animation 的保持时间或起始时间：

   如有任一条件为真：

   • animation 的保持时间为已定，或

   • animation 的起始时间为未定，或

   • animation 没有关联的时间线，或关联的 时间线为不活动，或

   • animation 的播放速率为 0，

   1. 将animation的保持时间设为seek time。

   否则，

   将animation的起始时间设为以下计算结果：timeline time - (seek time / 播放速率)，其中timeline time为animation关联时间线的当前时间值。

6. 如果animation 没有关联的时间线，或关联的时间线为不活动，将animation的起始时间设为未定。

   此举用于保证：当没有活动时间线时，只能设置起始时间或动画的当前时间其中之一。

7. 将animation的previous current time设为未定。

设置当前时间的过程如下，将动画 animation 的当前时间设为 seek time：

1. 执行静默设置当前时间过程，将 animation 的当前时间设置为 seek time。

2. 如果 animation 存在待暂停任务，则同步完成暂停操作，执行下列步骤：

   1. 将animation的保持时间设为seek time。

   2. 对animation应用所有待处理播放速率。

   3. 将animation的起始时间设为未定。

   4. 取消待暂停任务。

   5. 解决 animation 的当前 ready promise，传入 animation。

3. 以 did seek 标志为 true，synchronously notify 标志为 false，执行更新动画完成状态过程。

2.4.6. 设置 Animation 的起始时间

将animation的起始时间设置为 new start time 的设置起始时间过程如下：

1. 令 valid start time 为以 new start time 为输入，执行校验 CSSNumberish 时间值过程的结果。

2. 如果 valid start time 为 false，则终止此过程。

3. 设置 auto align start time 为 false。

4. 令 timeline time 为 animation 关联时间线的当前时间值。如果animation 没有关联的 时间线 或时间线不活动（inactive），则设timeline time为未定。

5. 如果 timeline time 为未定 并且 new start time 为 已定，将 animation 的保持时间设为 未定。

   此举用于保证：当没有活动时间线时，只能设置起始时间或动画的当前时间其一。

6. 令 previous current time 为 animation 的当前时间。

   注意: 这是上一过程变更后的当前时间，可能会导致当前时间变为未定。

7. 对animation应用所有待处理播放速率。

8. 将animation的起始时间设为new start time。

9. 根据如下首个匹配条件，更新 animation 的 保持时间：

   如果new start time为已定，

   如果animation的播放速率不为零，则将animation的保持时间设为未定。

   否则（new start time为未定），

   1. 将animation的保持时间设为previous current time，即使previous current time为未定。

10. 如果animation有待播放任务或待暂停任务，则取消该任务并解决 animation 的当前 ready promise，传入 animation。

11. 以 did seek 标志为 true，synchronously notify 标志为 false，执行更新动画完成状态过程。

2.4.7. 播放动画

播放动画 animation 的过程，以及传入的 auto-rewind 标志如下：

注意：auto-rewind 标志用于基于该模型但不要求回退行为的其他规范，如 CSS Animations [CSS-ANIMATIONS-1]。

1. 令 aborted pause 为布尔 flag，当 animation 有待暂停任务为 true，否则为 false。

2. 令 has pending ready promise 为布尔标志，初始为 false。

3. 如果 animation 关联的时间线非单调递增，则 has finite timeline 为 true。

4. 令 previous current time 为 animation 的当前时间。

5. 如果 auto-rewind 为 true 且 has finite timeline 为 false，则 enable seek 为 true，否则初始为 false。

6. 执行下列首次匹配的条件：

   如果 animation 的有效播放速率 > 0，且 enable seek 为 true，且满足下列任一：

   • previous current time 是未定，或

   • previous current time < 0，或

   • previous current time ≥ 关联效果结束，

   将 animation 的保持时间设为 0。

   如果 animation 的有效播放速率 < 0，enable seek 为 true，且满足下列任一：

   • previous current time 是未定，或

   • previous current time ≤ 0，或

   • previous current time > 关联效果结束，

   关联效果结束为正无穷

   抛出 "InvalidStateError" DOMException 并终止本步骤。

   否则，

   将 animation 的保持时间设为 animation 的关联效果结束。

   如果 animation 的有效播放速率 = 0 且 animation 的当前时间为未定，

   将 animation 的保持时间设为 0。

7. 如果 has finite timeline，并且 previous current time 是未定：

   • 将 auto align start time 标志设为 true。

   注意： 如果在样式更新期间调用 play（如 CSS 动画），则动画 起始时间在布局后才能可靠计算，因为起始时间需与动画区间的开始或结束对齐（依据播放速率）。此时动画称为具有自动对齐起始时间，即动画起始时间会自动调整，使动画进度对齐到动画区间。

8. 如果 animation 的保持时间为已定，则将其 起始时间设为未定。

9. 如果 animation 存在待播放任务或 待暂停任务：

   1. 取消该任务。

   2. 将 has pending ready promise 设为 true。

10. 如果下列三条件均成立：

    • animation 的保持时间为未定，

    • aborted pause 为 false，

    • animation 没有待设置播放速率，

    终止本过程。

11. 如果 has pending ready promise 为 false，将 animation 的当前 ready promise 设为新的 promise，位于 animation 的相关 Realm。

12. 调度一个任务，当 animation 准备就绪 时执行。该任务将执行以下步骤：

    1. 断言 animation 的起始时间或保持时间中至少一个为已定。

    2. 令 ready time 为 animation 在变为 准备就绪时，关联时间线的时间值。

    3. 执行下列首个匹配条件：

       如果 animation 的保持时间为已定，

       1. 对 animation应用所有待处理播放速率。

       2. 令 new start time 为 ready time - 保持时间 / 播放速率。如果播放速率为 0，则new start time 直接为 ready time。

       3. 将 animation 的起始时间设为 new start time。

       4. 如果 animation 的播放速率不为 0，则将保持时间设为未定。

       如果 animation 的起始时间为已定，且 animation 有待设置播放速率，

       1. 令 current time to match = (ready time - 起始时间) × 播放速率。

       2. 对 animation应用所有待处理播放速率。

       3. 如果 animation 的播放速率为 0，则将保持时间设为 current time to match。

       4. 令 new start time = ready time - current time to match / 播放速率。如果播放速率为 0，则new start time为ready time。

       5. 将 animation 的起始时间设为 new start time。

    4. 解决 animation 的当前 ready promise，传入 animation。

    5. 对 animation 以 did seek 标志为 false，synchronously notify 标志为 false，运行更新动画完成状态过程。

       注意以上两个步骤的顺序很重要，因为对于长度为零的关联效果的动画，其当前 ready promise会早于当前 finished promise被解决。

    只要上述任务被调度但尚未执行时，animation被描述为有待播放任务。而当该任务正在运行时，animation则没有待播放任务。

    如果用户代理确定 animation 立即准备就绪，则可以将上述任务调度为微任务，使其在下一个微任务检查点执行，但不得同步执行该任务。

    上述要求异步处理待播放任务，确保如下代码在各实现中行为一致：

    animation.play();
    animation.ready.then(
      () => { console.log('Playback commenced'); },
      () => { console.log('Playback was canceled'); }
    );
    // Suppose some condition requires playback to be canceled...
    animation.cancel();
    // "Playback was canceled" will be printed to the console.
    

    如上所示，如果待播放任务是同步执行，则当前 ready promise将不会被拒绝。

13. 以 did seek 标志为 false，synchronously notify 标志为 false，运行更新动画完成状态过程。

播放动画的过程需要包含调度用于更新自定义效果的任务。

2.4.7.1. 自动对齐起始时间

当附加到非单调时间线时，动画的起始时间可能依赖于布局。在这种情况下，我们会推迟起始时间的计算直到时间线在布局后更新。当更新时间线当前时间时，任意附加动画的起始时间会被有条件地更新。计算自动对齐起始时间的过程如下：

1. 如果 auto-align start time 标志为 false，则终止本过程。

2. 如果时间线不活动，则终止本过程。

3. 如果播放状态为 idle，则终止本过程。

4. 如果播放状态为 paused 且保持时间为已定，则终止本过程。

5. 令 start offset 为动画附加区间开始所对应的已定时间线时间。对于视图时间线（view timeline），需要基于覆盖区间比例进行计算。

6. 令 end offset 为动画附加区间结束所对应的已定时间线时间。对于视图时间线，需要基于覆盖区间比例进行计算。

7. 如果有效播放速率 ≥ 0，则将起始时间设为 start offset，否则为 end offset。

8. 清除保持时间。

2.4.8. 暂停动画

暂停动画的过程不仅需要涉及关联效果，还需要涉及关联效果的所有后代。

更新设置 seek time 的约束，使其只在使用单调时间线时适用。滚动驱动动画需要等到动画区间计算完毕后再设置保持时间。

替换：

1. 令 seek time 为时间值，初始为未定。

2. 令 has finite timeline 为 true， 如果 animation 关联的时间线不是单调递增。

3. 如果 animation 的当前时间为未定，则按下列首个匹配条件执行：

   如果 animation 的播放速率 ≥ 0,

   将 seek time 设为 0。

   否则，

   如果 关联效果结束为正无穷，

   抛出 "InvalidStateError" DOMException 并终止。

   否则，

   将 seek time 设为 animation 的关联效果结束。

4. 如果 seek time 是已定，

   如果 has finite timeline 为 true,

   将 animation 的起始时间设为 seek time。

   否则,

   将 animation 的保持时间设为 seek time。

改为：

1. 令 has finite timeline 为 true， 如果 animation 关联的时间线不是单调递增。

2. 如果 animation 的当前时间为未定且 has finite timeline 为 false，则按下列首个匹配条件执行：

   如果 animation 的播放速率 ≥ 0,

   将保持时间设为0。

   否则，

   如果 关联效果结束为正无穷,

   抛出 "InvalidStateError" DOMException 并终止。

   否则，

   将保持时间设为 animation 的关联效果结束。

3. 如果 has finite timeline 为 true，且 animation 的当前时间为未定

   • 将 auto align start time 标志设为 true。

替换：

调度一个任务，在同时满足以下两个条件的第一个时刻执行：

• 用户代理已完成暂停动画关联效果播放所需的任何处理（如有）。

• 动画已关联到非不活动时间线。

改为：

调度一个任务，在同时满足以下所有条件的第一个时刻执行：

• 用户代理已完成暂停动画关联效果播放所需的任何处理（如有）。

• 动画已关联到非不活动时间线。

• 动画有已定的保持时间或起始时间。

注意：如果auto-align start time标志为 true，为了正确对齐动画区间，暂停待决动画仍然需要起始时间。起始时间需按自动对齐起始时间的过程设置。

2.4.9. 取消动画

2.4.10. 速度控制

2.4.11. 计算动画整体进度

动画的overallProgress为其当前时间与关联效果结束的比值。

2.5. 动画效果

加入如下内容：

动画的关联效果称为直接关联到该动画。

动画效果可以通过分组效果组合为层级结构（见§ 2.10 分组与同步）。只有这种层级结构中的根动画效果可以直接关联到动画。如果一个具有父组的动画效果被指定为动画的关联效果，该动画效果会先从其父组移除，再与动画关联。

若一个动画效果关联于动画，则其为直接关联，或其拥有祖先分组效果，且该分组效果直接关联于动画。

2.5.1. 动画效果的类型

本规范定义了两种动画效果：

• 关键帧效果，

• 分组效果。

2.5.2. 活动区间

在本级规范中，活动区间下界定义为：

活动区间的下界由动画效果起始时间决定，但可被动画效果上的起始延迟所偏移。

下图也应提及动画效果起始时间而非动画起始时间。

最后，结束延迟的描述更新为：

结束延迟也可以指定，但主要在使用序列效果等实现动画串联时有用。

规范性描述更新如下：

活动区间的下界由动画效果的起始时间与起始延迟共同决定。

动画效果的起始时间是父组（如有）调度动画效果开始的时刻，以继承时间表示。

大多数情况下，包括动画效果没有父组时，起始时间为0。唯一例外是序列效果会如§ 2.10.4.1 序列效果子项的起始时间描述为其子项设定起始时间。

除起始时间外，动画效果还拥有起始延迟，即相对于起始时间的偏移。

与由父组确定的起始时间不同，起始延迟是动画效果本身的属性。

某动画效果的活动区间下界（以继承时间空间表示）为其起始时间与起始延迟之和。

这些定义被用于本地时间（参见§ 2.5.3 本地时间和继承时间）与活动时间的计算。

最后，结束时间定义如下：

某动画效果的结束时间为如下表达式的结果：max(起始时间 + 起始延迟 + 活动时长 + 结束延迟, 0)。

2.5.3. 本地时间与继承时间

本节为新增内容。

在 Web Animations 中，所有时间都是相对于某个参考点的。这些不同的参考点构成了不同的时间空间。

这可以类比于计算机图形学中的坐标空间。时间空间的零点类似于坐标空间的原点。

同坐标空间一样，时间空间也可以嵌套。分组效果通常会对其从父节点或动画接收到的时间值做一定的变换，再将变换后的时间值传递给子元素。子动画效果随后在这种变换后的时间空间内工作。

子对象会从父对象那里获取变换后的时间值，也就是继承时间，并加上自身的起始时间，来建立自己的本地时间空间，如下图所示。

对于动画效果，某一时刻的继承时间，根据以下条件首个匹配项确定：

如果动画效果有父组，

继承时间为父组的当前变换后时间。

如果动画效果直接关联于动画，

继承时间为动画的当前时间。

否则，

继承时间为未定。

本地时间指动画效果的继承时间减去其起始时间。如果继承时间为未定，则本地时间也为未定。

2.5.4. 动画效果阶段与状态

播放中的规范定义增添如下条件：

2. 动画效果有父组，且父组播放中，或该动画效果直接关联于未完成（not finished）的动画。

替换：

2. 动画效果关联于动画且动画未完成。

Current 状态规范定义增加如下条件：

• 动画效果有父组且父组为Current。

补充以下定义于动画效果阶段判断条件列表：

处于进度时间线边界

判断流程如下：

1. 如任一条件为真：

   • 关联动画的时间线不是基于进度时间线，

   • 关联动画的时间线时长未定或为零，

   • 动画的播放速率为零

   返回 false

2. 令 effective start time 为动画的起始时间，若未定则为零。

3. 按下列首个匹配条件设 unlimited current time：

   起始时间已定：

   (timeline time - 起始时间) × 播放速率

   否则，

   animation 的当前时间

4. 令 effective timeline time 为 unlimited current time / 动画的播放速率 + effective start time

5. 令 effective timeline progress 为 effective timeline time / 时间线时长

6. 若 effective timeline progress 为 0 或 1，返回 true，否则 false。

若暂停动画期间明确设定动画的当前时间，上述流程不完全正确，可能导致动画当前时间与时间线当前时间出现偏差。

此流程还可简化，判断滚动边界时可忽略播放速率和起始时间。其目的是避免动画在滚动极限处变为非活动状态，无需对 ScrollTimeline 设置填充模式。直接检查时间线当前时间是否为0或时间线时长可能更合适。

替换：

若动画效果的本地时间不是未定，且满足以下任一条件，则处于前置阶段（before phase）：

1. 本地时间小于before-active 边界时间，或

2. 动画方向为 "backwards" 且本地时间等于before-active 边界时间。

改为：

若动画效果的本地时间不是未定，且满足以下任一条件，则处于前置阶段：

1. 本地时间小于before-active 边界时间，或

2. 动画方向为 "backwards" 且本地时间等于before-active 边界时间，且不 处于进度时间线边界。

替换：

若动画效果的本地时间不是未定，且满足以下任一条件，则处于后置阶段（after phase）：

1. 本地时间大于active-after 边界时间，或

2. 动画方向为 "forwards" 且本地时间等于active-after 边界时间。

改为：

若动画效果的本地时间不是未定，且满足以下任一条件，则处于后置阶段：

1. 本地时间大于active-after 边界时间，或

2. 动画方向为 "forwards" 且本地时间等于active-after 边界时间且不 处于进度时间线边界。

2.5.5. 填充模式

2.6. 重复

2.6.1. 迭代区间

补充：

单次迭代的长度称为迭代时长（iteration duration）。

新增：

动画效果的初始迭代时长即为它的固有迭代时长。固有迭代时长的计算按以下首个匹配条件：

如果动画效果为分组效果，

参见§ 2.10.3 分组效果的固有迭代时长。

如果动画效果为序列效果，

参见§ 2.10.4.2 序列效果的固有迭代时长。

如果时间线时长未定，或迭代次数为 0，

返回 0

否则

返回 (100% - 起始延迟 - 结束延迟) / 迭代次数

注意： 目前起始和结束延迟均为零，直到支持百分比延迟。

动画效果的迭代时长可由作者设置为除固有迭代时长以外的值。

2.6.2. 迭代时间空间

2.6.3. 区间计时

本节为非规范性内容

描述更新如下：

下方示例中，对于重复的效果，在本地时间为 1s 时，迭代时间为 0。对于序列效果，在继承时间为 1s 时，只有效果 B 处于播放中；两者区间边界都没有重叠。

下方图示同样更新：

2.7. 动画效果速度控制

（本节为新增）

与动画类似，动画效果也有一个播放速率参数。动画效果的播放速率是一个有限实数，在根据本地时间计算动画效果的变换后时间时作为乘数。

为动画效果设置播放速率，与为动画设置播放速率的效果不同。详细行为见§ 2.8 动画效果核心计算。

2.8. 动画效果核心计算

2.8.1. 概述

本节为非规范性内容

描述由：

在 Web Animations 时间模型的核心，是把本地时间值转换为迭代进度的过程。

改为：

在 Web Animations 时间模型的核心，是把继承时间值转换为迭代进度的过程。

更新图示，展示动画效果播放速率：

更新如下：

确定活动时长后，将本地时间转换为变换后进度（迭代进度）的过程如下图所示。

改为：

确定活动时长后，将继承时间转换为变换后进度（迭代进度）的过程如下图所示。

更新时间计算图：

更新：

第一步，本地时间的计算见 Local time。

改为：

第一步，本地时间的计算见§ 2.5.3 本地时间与继承时间。

2.8.2. 计算活动时长

更新为：

为计算活动时长，首先定义重复时长如下：

重复时长 = 迭代时长 × 迭代次数

如果迭代时长或迭代次数为零，则重复时长为零。

此澄清是因为根据 IEEE 754-2008，无穷大与零相乘结果未定义。

活动时长按以下步骤计算：

1. 如果播放速率为零，返回Infinity。

2. 否则，返回重复时长 / abs(播放速率)。

2.8.3. 本地时间的变换

2.8.3.1. 计算活动时间

将活动时间定义的说明中，加入父组：

不过，只有当动画效果应产生输出时该值才有定义，因此取决于其填充模式和阶段，以及（如有）其父组的阶段：

在每个阶段的定义中补充如下步骤：

如果动画效果处于前置阶段，

结果依下列首个匹配条件：

如其有父组且父组处于后置阶段，

返回未定时间值。

……

如果动画效果处于活动阶段，

结果依下列首个匹配条件：

如其有父组且父组处于前置阶段，且当前效果的填充模式为 none 或 forwards，

返回未定时间值。

如其有父组且父组处于后置阶段，且当前效果的填充模式为 none 或 backwards，

返回未定时间值。

否则，

返回本地时间 - 起始延迟 的结果。

如果动画效果处于后置阶段，

结果依下列首个匹配条件：

如其有父组且父组处于前置阶段，

返回未定时间值。

……

否则（本地时间为未定），

返回未定时间值。

2.8.3.2. 计算整体进度

在整体进度定义中，更新initial progress的“否则”分支如下：

否则，

按下列首个匹配条件计算overall progress：

如果播放速率小于零，

令overall progress为(活动时间 - 活动时长) × 播放速率 / 迭代时长。

如果播放速率为零，

overall progress为零。

否则，

令overall progress为(活动时间 × 播放速率) / 迭代时长。

2.9. 时间变换

2.9.1. 计算变换后进度

将第二步替换为针对before flag的计算（以适应效果播放速率）：

1. 如果任一下列条件为真：current direction为forwards，或播放速率 ≥ 0（但不是两者都为真时）， 那么令going forwards为 true，否则为 false。

2.9.2. 计算变换后时间

（本节为新增。）

动画效果的变换后时间很简单，就是 变换后进度乘以 迭代时长。

如果变换后进度为未定，则变换后时间也为未定。

如果变换后进度为0，且迭代时长为无穷大，则变换后时间为0。

2.10. 分组与同步

本节为非规范性内容

虽然可以分别设置动画效果的计时属性，但通常将多个动画效果同步，使它们共享公共计时属性并保持它们的时序关系会更有用。这通过分组效果实现。

下面是一个简单示例：

当分组效果直接关联到动画时，相关联的动画效果可以作为一个整体 seek、暂停和停止。

分组效果是一种动画效果，包含若干个（零个或多个）有序的动画效果，称为子效果。

某一时刻，一个动画效果至多只能是一个分组效果的子效果，该分组效果称为父组。 父组不能与动画效果自身相同。

通过嵌套分组效果可以构建树状结构。用于描述此类结构组成与属性的术语如下，并见 [DOM] 的定义：

• tree order

• root

• ancestor

• descendant

• inclusive ancestor

• inclusive descendant

• next sibling

• previous sibling

• first child

• last child

注意： 在应用这些定义到动画效果时，父节点专指父组，不包括动画，即使后者实际上是动画效果的时间源。

子效果与其父组之间的时序关系体现在继承时间的定义中（参见§ 2.5.3 本地时间与继承时间）。

2.10.1. 分组时间与子项时间的关系

本节为非规范性内容

分组效果的子项的计时基于分组的计时。具体来说，子项的时间基于父分组的变换后时间。对于重复来说，这意味着子项在父分组的每一次迭代内执行。

例如，若分组效果的迭代次数为2，则该组的所有子项会播放两次，因为它们有效地在分组的每轮迭代内被播放。

注意，即便如此，每个子动画效果只有一个活动区间，但是由于父分组的计时安排，该活动区间会被播放两次。

如果对子项和分组本身同时设置迭代次数，等同于将分组的迭代次数与子项的迭代次数相乘。

由于分组效果的子项的计时基于分组的变换后时间，所以它们无法超出分组的活动区间进行动画。 这是因为分组的变换后时间在其活动区间之外不会变化，因此分组合可以裁剪其子项的播放。

此外，由于分组效果的子项计时基于父组的变换后时间，带来了进一步影响：

• 设置分组效果的播放速率，将影响所有子项。

• 更改分组效果的播放方向，所有子项的播放方向也会改变。

• 在分组效果上应用时间函数，会影响所有子项的进度。

2.10.2. 分组效果子项的起始时间

分组效果的子效果的起始时间为0。

注意，某些特定类型的分组效果可以重写此定义，实现其它类型的同步行为。

2.10.3. 分组效果的固有迭代时长

分组效果的固有迭代时长等于该分组内最后一个子效果完成其活动区间的时间，具体取决于子项数量，规则如下：

如果分组没有子效果，

固有迭代时长为0。

否则，

1. 令maximum end time为分组内各子效果的结束时间最大值。结束时间可以是时间类型或百分比（针对基于进度时间线）。如类型混用，则以最大时间型为100%用于缩放。

2. 固有迭代时长为max(0, maximum end time)。

某些特定类型的分组效果可以重写上述固有迭代时长的定义。

2.10.4. 序列效果

本节为非规范性内容

某些特定类型的分组效果可用于对子项实现不同的同步行为。本规范定义了一种额外类型的分组效果：序列效果。序列效果将其子项的起始时间顺序排列，使其逐一依次执行。

对比如下两种安排：

由于分组效果还可以嵌套其他分组效果，下图展示了组合不同类型分组以实现复杂同步的可能性：

序列效果是分组效果的一个类型，它会安排其子效果按顺序依次执行。这种序列方式是通过调整组内每个子项的起始时间实现的。

2.10.4.1. 序列特效子项的开始时间

子特效的开始时间（属于序列特效）是该子项前一个兄弟节点的结束时间。 如果子项没有前一个兄弟节点，那么开始时间为零。

本节为非规范性内容

因为活跃区间的起点是基于动画特效的开始时间 加上 启动延迟， 所以序列特效子项的活跃区间未必严格按顺序顺次运行，可以通过启动延迟前后移动，如下图所示。

可以通过负的启动延迟 让两个子项的活跃区间发生重叠。 注意，启动延迟会影响分组中后续子项的开始时间。

2.10.4.2. 序列特效的固有迭代时长

序列特效的固有迭代时长等价于假定 在组的子项末尾追加一个子特效后，按§ 2.10.4.1 序列特效子项的开始时间的定义计算得到的开始时间，如果该值为负，则固有迭代时长为零。

因此，如果序列特效没有任何子特效，其固有迭代时长为零。

3. 动画模型

3.1. 动画类型

3.1.1. 不可动画化

将针对不可动画属性的特效的描述更新为：

针对不可动画属性的 动画特效，依然会表现出 动画特效的常规行为，例如在序列特效中占用时间， 以及延后动画的 current finished promise的实现时机。

3.2. 关键帧特效

3.2.1. 关键帧特效的效果值

针对由关键帧特效作为 目标属性之一引用的某个属性， 在指定iteration progress、current iteration和underlying value下， 用于计算效果值的过程， 需在应用关键帧特效合成模式步骤后插入以下步骤。

12. 对interval endpoints中的每个keyframe：

    1. （同 web-animations-1）

    2. 如果此关键帧特效的迭代合成操作为累加， 则按以下步骤执行current iteration次：

       • 用property-specific keyframes中最终关键帧上的属性值（V_a）和当前keyframe上的属性值（V_b）， 按目标属性的累加过程， 将keyframe上的属性值替换为二者累加的结果。

       注：这里参数顺序很重要。当目标属性的动画类型没有定义累加或相加过程时，这些过程的默认定义会返回V_b。 在对不支持累加的属性进行迭代合成时，结果应为keyframe上目标属性的初始值， 因此上述步骤中将其设置为V_b。

3.3. 效果合成

3.3.1. 效果栈

为效果排序过程追加以下步骤：

1. 按照树顺序对A和B排序。 （此时，A和B必须拥有相同的动画，否则顺序会在上一步中被解决。）

排序动画特效时所用的 “动画特效的关联动画” 定义需要根据本级规范引入的与动画关联的定义进行修订，以正确处理群组特效。

3.4. 效果累加

类似于效果值之间的合成 （参见 Web Animations § 5.4.4 效果合成）， 迭代合成操作 决定了同一个关键帧特效连续多次迭代时如何合成属性值。

本规范定义了如下两种迭代合成操作：

replace

每次迭代独立计算，不依赖于前次迭代的结果。

accumulate

动画的连续多次迭代，将与上一次迭代的最终值累加。

对迭代合成操作的应用已被整合进效果值的计算中， 可参见§ 3.2.1 关键帧特效的效果值。

3.6. 动画触发器

3.6.1. 概述

动画触发器用于控制其关联的 动画在基于时间的动画中的播放。 与动画类似，动画触发器会与时间轴相关联，并附加到一个附着区间上。

触发器是否应该对滚动驱动动画产生影响？

3.6.2. 动画触发器内部状态

动画触发器 trigger 具有一个内部布尔型did trigger标志，初始为false， 以及一个内部state，可取如下值：

idle

与animation关联的动画特效保持在其开始前阶段，并将当前时间固定为零。

primary

切换到此值时，由type指定的primary行为类型会应用到animation。

inverse

切换到此值时，由type指定的inverse行为类型会应用到animation。

state和did trigger的值会在下面描述的更新动画触发器状态步骤中被更新。

idle 状态是否需要在规范中作出正式决议？

3.6.3. 动画触发器行为

动画触发器 具有一个关联的动画触发器行为， 该行为结合did trigger和 state， 决定该触发器对其关联动画播放的影响。

与动画触发器关联的动画特效在idle状态下， 会始终处于其开始前阶段，并且当前时间保持为零， 无论触发器的did trigger标志或state为何。 其他情况下，不同行为behavior的播放效果如下：

once

如果state是primary，

则其效果是触发关联动画。

否则，

触发器不产生任何效果。

repeat

如果state是primary，

则其效果是触发关联动画。

如果state是inverse，

其效果是将关联的动画特效重置为开始前阶段，并将动画的开始时间置零。

alternate

如果state是primary 且did trigger为false，

则其效果是触发关联动画。

如果state是primary 且did trigger为true，

则其效果是反转关联动画。

如果state是inverse，

则其效果是反转关联动画。

state

如果state是primary，

则其效果是触发或恢复关联动画。

如果state是inverse，

则其效果是暂停关联动画。

“primary/inverse” 行为类型是否需要详细定义？

3.6.4. 动画触发器激活区间

每个动画触发器都定义了一个激活区间 ，且仅有一个。该区间为时间轴进度上state设置为primary期间的片段。

3.6.5. 动画触发器区间

一个动画触发器包含两个区间， 即默认区间和 退出区间。 退出区间用于替换默认区间并扩展激活区间。

是否应规定退出区间的边界只能大于等于默认区间边界？

根据其最新state state的值， 激活区间定义如下：

如果state为primary，

则interval被设为退出区间。

否则，

interval为默认区间。

3.6.6. 设置动画的触发器

3.6.7. 设置动画触发器的时间轴

3.6.8. 更新动画触发器状态

当时间轴再次变为闲置时，"did trigger" 标志是否应重置为false才是正确/期望的行为？

4. 编程接口

4.1. AnimationTimeline 接口

[Exposed=Window]
partial interface AnimationTimeline {
    readonly attribute CSSNumberish? currentTime;
    readonly attribute CSSNumberish? duration;
    Animation play (optional AnimationEffect? effect = null);
};

4.2. Animation 接口

更新 Animation 接口的 startTime 和 currentTime，增加 rangeStart、rangeEnd 和 overallProgress，如下所示：

[Exposed=Window]
partial interface Animation {
    attribute CSSNumberish?       startTime;
    attribute CSSNumberish?       currentTime;
    attribute AnimationTrigger?   trigger;
    attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart;
    attribute (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd;
    readonly attribute double? overallProgress;
};

增加或更新如下属性描述：

4.3. AnimationEffect 接口

[Exposed=Window]
partial interface AnimationEffect {
    // Timing hierarchy
    readonly attribute GroupEffect?     parent;
    readonly attribute AnimationEffect? previousSibling;
    readonly attribute AnimationEffect? nextSibling;

    undefined before (AnimationEffect... effects);
    undefined after (AnimationEffect... effects);
    undefined replace (AnimationEffect... effects);
    undefined remove ();
};

remove() 方法既可将特效从父组移除，也可从动画移除。我们是否应在第1级中保留该方法，并只定义为从动画对象移除？

4.4. EffectTiming 和 OptionalEffectTiming 字典

partial dictionary EffectTiming {
    double delay;
    double endDelay;
    double playbackRate = 1.0;
    (unrestricted double or CSSNumericValue or DOMString) duration = "auto";
};

partial dictionary OptionalEffectTiming {
    double playbackRate;
};

注意： 本规范当前版本中，duration 暂不支持设置为 CSSNumericValue；但通过 getComputedTiming() 解析 duration 时，返回值可能为 CSSNumericValue。 未来版本有望允许将 duration 设置为 CSSNumeric 类型，需为有效时间单位或百分比。

4.5. 更新 AnimationEffect 的计时

替换：

将 input 中存在的每个成员赋值给 effect 的对应计时属性如下：

• delay → 启动延迟

• endDelay → 结束延迟

• fill → 填充模式

• iterationStart → 迭代起始

• iterations → 迭代次数

• duration → 迭代时长

• direction → 播放方向

• easing → 缓动函数

为：

将 input 中存在的每个成员赋值给 effect 的对应计时属性如下：

• delay → 指定启动延迟

• endDelay → 指定结束延迟

• fill → 填充模式

• iterationStart → 迭代起始

• iterations → 迭代次数

• duration → 指定迭代时长

• direction → 播放方向

• easing → 缓动函数

增加：

按规范化指定计时流程操作。

样式变更也可能导致计时属性被更新。任何影响动画计时的 CSS 动画属性变化，都需要重新执行规范化指定计时流程。

4.6. ComputedEffectTiming 字典

partial dictionary ComputedEffectTiming {
    CSSNumberish         startTime;
    CSSNumberish         endTime;
    CSSNumberish         activeDuration;
    CSSNumberish?        localTime;
};

4.6.1. FillMode 枚举

enum FillMode { "none", "forwards", "backwards", "both", "auto" };

auto

将描述更新为：

应用于 GroupEffect 时前后都填充，应用于 KeyframeEffect 时不填充。

4.7. GroupEffect 接口

（本节新增。）

组特效由 GroupEffect 接口表示。

[Exposed=Window]
interface GroupEffect {
  constructor(sequence<AnimationEffect>? children,
              optional (unrestricted double or EffectTiming) timing = {});

  readonly attribute AnimationNodeList  children;
  readonly attribute AnimationEffect?   firstChild;
  readonly attribute AnimationEffect?   lastChild;
  GroupEffect clone ();

  undefined prepend (AnimationEffect... effects);
  undefined append (AnimationEffect... effects);
};

4.7.1. 处理 timing 参数

传递给 GroupEffect() 或 SequenceEffect() 构造函数的 timing 参数可以是一个 EffectTiming 对象、表示 动画特效时长（毫秒）的 double 或 undefined。

以下流程处理 timing 参数 ，用于将上述输入归一化为 EffectTiming 对象。

如果 timing 是 EffectTiming 对象，

直接返回 timing。

如果 timing 是 double，

返回新建的 EffectTiming ，其所有成员为默认值，duration 为 timing。

否则（timing 未定义），

返回新建的 EffectTiming ，其所有成员为默认值。

4.7.2. 层级操作定义

用于确定动画特效 effect 在一组动画特效 effects 中的 下一个未包含在该组内的兄弟节点 的步骤如下：

1. 令 context effect 为 effect。

2. 当 context effect 的下一个兄弟节点 非 null 时，执行下列步骤：

   1. 令 context effect 变为其下一个兄弟节点。

   2. 如果 context effect 不在 effects 中，返回 context effect 并中止。

3. 返回 null。

要移除一个 effect 从其父组或 动画 ，按照首先匹配到的条件执行如下操作（如有）：

如果 effect 有父组，

将 effect 从该父组的子特效列表中移除。

如果 effect 直接关联到动画，

将 effect 从 动画中解除关联。

要插入一系列 effects 到 parent 的子特效列表的 reference child 之前，对 effects 里每一个 effect 依次按以下步骤操作：

1. 移除 effect 的父节点。

2. 将 effect 插入到 parent 的子特效列表的 reference child 之前。

4.8. AnimationNodeList 接口

一组动画特效可以用 AnimationNodeList 表示。

AnimationNodeList 接口支持索引属性，索引范围为 0 ≤ index < length。

此接口存在的唯一原因，是为了让熟悉 DOM 接口（通过 children 成员访问子节点）的作者获得熟悉的体验。

[Exposed=Window]
interface AnimationNodeList {
    readonly attribute unsigned long length;
    getter AnimationEffect? item (unsigned long index);
};

4.9. SequenceEffect 接口

序列特效由 SequenceEffect 接口表示。

[Exposed=Window]
interface SequenceEffect : GroupEffect {
  constructor(sequence<AnimationEffect>? children,
              optional (unrestricted double or EffectTiming) timing = {});

  SequenceEffect clone ();
};

4.10. KeyframeEffect 接口

KeyframeEffect 接口修改如下：

partial interface KeyframeEffect {
    attribute IterationCompositeOperation    iterationComposite;
};

4.10.1. 创建新的 KeyframeEffect 对象

new SequenceEffect(
  [
    new KeyframeEffect(elem, { opacity: 0 }, 1000),
    new KeyframeEffect(elem, { visibility: 'hidden' }, { fill: 'forwards' })
  ]
);

4.10.2. 对 *Keyframe 字典的修改

ComputedKeyframe、BaseComputedKeyframe、BaseKeyframe、BasePropertyIndexedKeyframe 等 字典中 offset 键的 double? 类型被替换为 (CSSNumberish? or TimelineRangeOffset or DOMString)， 其中 double 依然表示百分比，DOMString 将按照 <keyframe-selector> 语法解析为 TimelineRangeOffset， 得到的 TimelineRangeOffset或者 CSSNumericValue 按 @keyframes 语义解释。

如果 DOMString 不能正确解析为合法<keyframe-selector>， 则该关键帧无效，在 [[web-animations-1#processing-a-keyframes-argument|处理]] 时会抛出 TypeError （行为同 double 超出 [0,1] 时）。

4.10.3. KeyframeEffectOptions 字典

KeyframeEffectOptions 字典接口新增如下成员：

partial dictionary KeyframeEffectOptions {
    IterationCompositeOperation iterationComposite = "replace";
};

enum IterationCompositeOperation { "replace", "accumulate" };

callback EffectCallback = undefined (double? progress,
                                (Element or CSSPseudoElement) currentTarget,
                                Animation animation);

dictionary TimelineRangeOffset {
  CSSOMString? rangeName;
  CSSNumericValue offset;
};

partial dictionary KeyframeAnimationOptions {
    (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart = "normal";
    (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd = "normal";
    AnimationTrigger? trigger;
};

[Exposed=Window]
interface AnimationPlaybackEvent : Event {
    constructor(DOMString type, optional AnimationPlaybackEventInit
    eventInitDict = {});
    readonly attribute CSSNumberish? currentTime;
    readonly attribute CSSNumberish? timelineTime;
};
dictionary AnimationPlaybackEventInit : EventInit {
    CSSNumberish? currentTime = null;
    CSSNumberish? timelineTime = null;
};

[Exposed=Window]
interface AnimationTrigger {
  constructor(optional AnimationTriggerOptions options = {});
  attribute AnimationTimeline timeline;
  attribute AnimationTriggerBehavior behavior;
  attribute any rangeStart;
  attribute any rangeEnd;
  attribute any exitRangeStart;
  attribute any exitRangeEnd;
};

dictionary AnimationTriggerOptions {
  AnimationTimeline? timeline;
  AnimationTriggerBehavior? behavior = "once";
  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart = "normal";
  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd = "normal";
  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeStart = "auto";
  (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeEnd = "auto";
};

enum AnimationTriggerBehavior { "once", "repeat", "alternate", "state" };