1. 引言
本规范定义了一些机制,
用于影响动画的播放,
其依据是调用指定触发器的各种用户交互。
为动画指定触发器后,该动画
就成为触发式动画,其
播放的开始将推迟到该触发器触发之时。
这些触发器可以附着于 特定 Event(定义见 [DOM]),
也可以基于时间轴,例如视图进度时间轴。[SCROLL-ANIMATIONS-1]
本模块既提供基于 Web Animations API 的 命令式 API,也提供基于 CSS Animations 的 声明式 API。[CSS-ANIMATIONS-2] [WEB-ANIMATIONS-1]
1.1. 与其他规范的关系
Web Animations [WEB-ANIMATIONS-1] 定义了 Web 平台动画的抽象概念模型, 其中模型元素包括动画和时间轴, 以及相关的编程接口。 本规范扩展了 Web Animations 模型, 定义了触发式动画, 并允许通过触发器对这些动画执行播放控制 功能。
本规范既引入了 用于与这些概念交互的编程接口, 也引入了将这些概念应用于 CSS Animations [CSS-ANIMATIONS-2] 的 CSS 属性。 当这些 CSS 属性的行为 通过编程接口描述时, 不支持脚本的用户代理 仍可符合本规范, 只需将 CSS 特性实现为 表现得如同底层编程接口已经存在。
本规范采用 Scroll-Driven Animations 模块 [SCROLL-ANIMATIONS-1] 引入的时间轴和范围概念, 以规定基于进度的时间轴和动画。
与 CSS 中除选择器匹配之外的大多数操作一样, 本规范的特性在 扁平化元素树上运作。
1.2. 值定义
本规范遵循 CSS 属性定义约定, 其出处为 [CSS2], 并使用值定义语法, 其出处为 [CSS-VALUES-3]。 本规范未定义的值类型 在 CSS Values & Units [CSS-VALUES-3] 中定义。 与其他 CSS 模块结合时,可能扩展这些值类型的定义。
除了各属性定义中列出的特定值之外, 本规范定义的所有属性 也接受CSS 全局关键词作为属性值。 为便于阅读,此处不再逐一明确列出。
2. 触发器
触发器允许将一个元素上的用户交互 与在另一个(或同一个)元素上应用指定动作关联起来。
目前定义了两类触发器:
-
时间轴触发器,由 timeline-trigger 属性管理, 允许通过进入或离开特定时间轴范围来触发动作。 (通常使用视图进度时间轴, 因此,例如可在元素进入屏幕时开始动画。)
-
事件触发器,由 event-trigger 属性管理, 允许通过特定的用户交互事件触发动作, 例如点击元素或按下特定按键。
触发器定义在某个特定的触发元素上。 所有触发器都有一个触发器名称, 具体的触发器类型决定其激活方式和时机。
触发器定义后,将创建该特定类型的触发器实例, 其作用域由 trigger-scope 属性管理。 对于每个指定的触发元素,将创建一个触发器附着, 放在匹配的实例上;其名称 和 trigger-scope 均匹配。
触发器附着的具体“类型”决定关联 实例的“分组”。也就是说,事件触发器附着 在名称和作用域相同时,会归入同一个 实例;相应地,时间轴触发器 会独立分组。 但是,在同一作用域内定义的不同类型的触发器名称, 会覆盖先前定义的触发器名称。
触发器可以在任意元素上使用, 从而在该元素上建立与触发器实例的关联, 该实例具有相同的名称。 (例如,animation-trigger 将触发器实例 与元素上的特定动画关联起来。) 使用触发器的元素指定: 当关联的触发器激活或停用时,应采取哪些动作。
注意: 触发器和触发器实例的这种设计, 及其与触发式动画和 <animation-action> 的关联方式, 有意保留了一定的通用性, 旨在支持未来将触发器用于其他用途。 不过,目前只有触发式动画使用此特性。
2.1. 触发器动作
触发器在元素上用作触发器时, 可以关联一个或两个动作 (例如通过 animation-trigger)。 如果指定两个,第一个是触发器的进入动作, 即触发器激活时应用的动作。 第二个是触发器的退出动作, 即触发器停用时应用的动作。
2.2. 触发器内部状态
触发器实例 trigger 具有内部布尔标志已触发, 其初始值为 false,并具有一个内部状态, 其可能取值如下:
- 待定
- 初始 状态 ,此时 触发器 的 已触发 标志为 false。
- 活动
- 切换为此值时, 触发器 会应用为其指定的 进入动作.
- 非活动
- 切换为此值时, 触发器 会应用为其指定的 退出动作.
2.3. 触发器名称的作用域: trigger-scope 属性
触发器名称默认是全局的, 其他元素无论位于何处均可使用。 (不过,它们是树作用域名称, 因此会与影子根发生交互。) 若多个元素声明触发器且其触发器名称相同, 它们将作为独立的附着组合在一起, 对应同一个触发器实例,具有相同的触发器名称和类型。
trigger-scope 属性可将名称的作用域 限制在文档的某个子树中, 使外部元素看不到选定的触发器名称, 而内部元素只能看到触发器名称的 作用域内部定义版本。
| 名称: | trigger-scope |
|---|---|
| 值: | none | all | <dashed-ident># |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
此属性将触发器名称的作用域限定为匹配元素的子树。 其取值如下:
- none
- 不改变 触发器名称 的作用域。
- all
-
指定所有 触发器名称 (由此元素或其后代定义,且作用域尚未被使用 trigger-scope的后代限制)仅在此元素的 扁平树 后代中处于作用域内;
并限制后代只能将 触发器名称
匹配到 触发器 (在此子树内)。
此值仅影响同一树作用域中的触发器名称, 就如同它是一个严格匹配的树作用域名称。 (即 trigger-scope: all 的作用等同于 trigger-scope: --foo, --bar, ..., 列出所有相关的触发器名称。)
- <dashed-ident>
-
指定匹配的 触发器名称 (由此元素或其后代定义,且作用域尚未被使用 trigger-scope的后代限制)仅在此元素的 扁平树 后代中处于作用域内;
并限制后代只能将这些 触发器名称
匹配到 触发器 (在此子树内)。
<dashed-ident> 表示严格匹配的树作用域名称, 即只能匹配同一影子树中的触发器名称。[CSS-SCOPING-1]
3. 时间轴触发器
时间轴触发器是一种触发器, 当某个时间轴 进入触发器的激活范围时激活, 离开触发器的活动范围时停用。 它通过 timeline-trigger 简写属性 或其长写属性在元素上定义。定义在元素上时, 它形成一个附着,连接到触发器实例, 该实例具有指定的名称和作用域。
元素可以定义多个时间轴触发器, 使用同一个时间轴(范围可能不同) 或不同的时间轴。 timeline-trigger 长写属性集 构成一个协调列表属性组, 以 timeline-trigger-name 为协调列表基准属性, 协调值列表中的每一项 定义一个时间轴触发器的属性。
3.1. 时间轴触发器的范围
时间轴触发器附着可以关联一个或多个时间轴。 当所有与该附着关联的 激活范围都被进入时, 它激活关联的触发器实例, 将其状态设为活动。 当任一与该附着关联的 活动范围被退出时, 它停用关联的触发器实例,将其状态 设为非活动。 因此,实质上形成了所有关联时间轴状态的逻辑或。 例如,当元素进入 垂直且水平滚动区域的交叉区域时。
注意: 默认情况下,活动范围与激活范围相同; 即使手动指定, 活动范围也始终是超集,包含激活范围。 例如,借助这两个范围, animation-trigger 可以在元素 滚动到接近屏幕中央时开始动画 (使用视图进度时间轴,并以相对较小的窗口作为激活范围), 但直到元素完全离开屏幕才停止动画 (使用 cover 作为活动范围)。
3.2. 命名触发器: timeline-trigger-name 属性
| 名称: | timeline-trigger-name |
|---|---|
| 值: | none | <dashed-ident># |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
若指定 none, 元素就不定义任何时间轴触发器。
若相同的 <dashed-ident> 在列表中多次出现, 仅最后一项定义时间轴触发器; 之前的项均无效。
3.3. 关联时间轴: timeline-trigger-source 属性
| 名称: | timeline-trigger-source |
|---|---|
| 值: | [ none | auto | [ <dashed-ident> | <scroll()> | <view()> ]+ ]# |
| 初始值: | auto |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
timeline-trigger-source 属性 指定时间轴触发器关联的时间轴。 各值的含义与 animation-timeline 相同。
注意: 使用 none 时, 触发器不关联任何时间轴。 时间轴触发器若没有时间轴,无法执行任何 <animation-action>, 因为它无法监测或改变状态。
3.4. 激活范围: timeline-trigger-activation-range 属性
| 名称: | timeline-trigger-activation-range |
|---|---|
| 值: | [ <'timeline-trigger-activation-range-start'> <'timeline-trigger-activation-range-end'>? ]# |
| 初始值: | 参见各个属性 |
| 适用于: | 参见各个属性 |
| 是否继承: | 参见各个属性 |
| 百分比: | 参见各个属性 |
| 计算值: | 参见各个属性 |
| 动画类型: | 参见各个属性 |
| 规范顺序: | 按语法 |
timeline-trigger-activation-range 属性是一个简写属性, 在一条声明中同时设置 timeline-trigger-activation-range-start 和 timeline-trigger-activation-range-end 这两个属性。 其语法与 animation-range 属性相同。
timeline-trigger-activation-range 的行为定义于§ 3.1 时间轴触发器范围。
| 名称: | timeline-trigger-activation-range-start, timeline-trigger-activation-range-end |
|---|---|
| 值: | [ normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# |
| 初始值: | normal |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 相对于指定的 具名时间轴范围 (若已指定),否则相对于整个时间轴 |
| 计算值: | 列表,各项为关键词 normal 或时间轴范围与进度百分比 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
timeline-trigger-activation-range-start 和 timeline-trigger-activation-range-end 属性 指定时间轴触发器关联的激活范围。 各值的含义与 animation-range-start 和 animation-range-end 相同。
3.5. 活动范围: timeline-trigger-active-range 属性
| 名称: | timeline-trigger-active-range |
|---|---|
| 值: | [ <'timeline-trigger-active-range-start'> <'timeline-trigger-active-range-end'>? ]# |
| 初始值: | 参见各个属性 |
| 适用于: | 参见各个属性 |
| 是否继承: | 参见各个属性 |
| 百分比: | 参见各个属性 |
| 计算值: | 参见各个属性 |
| 动画类型: | 参见各个属性 |
| 规范顺序: | 按语法 |
timeline-trigger-active-range 属性是一个简写属性, 在一条声明中同时设置 timeline-trigger-active-range-start 和 timeline-trigger-active-range-end 这两个属性。 其语法与 animation-range 属性相同。
timeline-trigger-active-range 的行为定义于§ 3.1 时间轴触发器范围。
| 名称: | timeline-trigger-active-range-start, timeline-trigger-active-range-end |
|---|---|
| 值: | [ auto | normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# |
| 初始值: | auto |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 相对于指定的 具名时间轴范围 (若已指定),否则相对于整个时间轴 |
| 计算值: | 列表,各项为关键词 normal 或时间轴范围与进度百分比 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
timeline-trigger-active-range-start 和 timeline-trigger-active-range-end 属性 指定时间轴触发器关联的活动范围。 各值的含义与 animation-range-start 和 animation-range-end 相同。 另增加以下值:
- auto
-
起点(对于 timeline-trigger-active-range-start) 或终点(对于 timeline-trigger-active-range-end) 等于时间轴触发器的激活范围的起点/终点。
3.6. timeline-trigger-range 简写属性
| 名称: | timeline-trigger-range |
|---|---|
| 值: | [ <'timeline-trigger-activation-range'> [ / <'timeline-trigger-active-range'> ]? ]# |
| 初始值: | 参见各个属性 |
| 适用于: | 参见各个属性 |
| 是否继承: | 参见各个属性 |
| 百分比: | 参见各个属性 |
| 计算值: | 参见各个属性 |
| 动画类型: | 参见各个属性 |
| 规范顺序: | 按语法 |
timeline-trigger-range 属性是一个简写属性, 在一条声明中同时设置 timeline-trigger-activation-range 和 timeline-trigger-active-range 这两个属性。
3.7. timeline-trigger 简写属性
| 名称: | timeline-trigger |
|---|---|
| 值: | none | [ <'timeline-trigger-name'> <'timeline-trigger-source'> [ <'timeline-trigger-range'> ]? ]# |
| 初始值: | 参见各个属性 |
| 适用于: | 参见各个属性 |
| 是否继承: | 参见各个属性 |
| 百分比: | 参见各个属性 |
| 计算值: | 参见各个属性 |
| 动画类型: | 参见各个属性 |
| 规范顺序: | 按语法 |
timeline-trigger 简写属性 一次性设置 timeline-trigger-name、 timeline-trigger-source, 以及可选的 timeline-trigger-range 简写属性 (后者又设置 timeline-trigger-activation-range 和 timeline-trigger-active-range)。
值 none 等价于 none none normal。
注意: 由于语法中存在显著的潜在歧义 (timeline-trigger-name 与 时间轴名称所在的 timeline-trigger-source; 激活范围与活动范围), 此简写属性的值必须按规定顺序给出, 不能像更常见的情况那样以任意顺序设置。
4. 事件触发器
事件触发器是一种触发器,
当特定的 Event 在元素上触发时激活。
它通过 event-trigger 简写属性
或其长写属性在元素上定义。
事件触发器可定义为无状态或有状态:
-
若为无状态,则只有一组进入事件 用于激活它。
-
若为有状态,则有两组事件:进入事件 以及另一组退出事件。
事件触发器在其关联的任一 Event 于页面中触发时激活,
事件的 target 为定义触发器的元素。
若它是有状态的,
则关联一个二值触发器状态,
初始为 "inactive":
处于 "inactive" 时,仅在定义元素收到一个进入事件时激活,
执行关联的进入动作,
并将触发器状态切换为 "active";
处于 "active" 时,仅在收到一个退出事件时停用,
执行关联的退出动作,
并将触发器状态切回 "inactive"。
无状态事件触发器必须为其触发器实例指定恰好一个动作。 有状态触发器可以指定一个或两个动作: 第一个是进入动作, 第二个(若提供)是退出动作; 若未提供第二个, 退出动作就是什么也不做。
注意: 即使只指定一个动作,有状态和无状态的事件触发器 也会有不同的行为。 单动作的有状态事件触发器实际上会“关闭”, 直到收到一个退出事件, 忽略第一个之后的所有进入事件; 无状态触发器则会在每次进入事件发生时反复触发。
元素可以定义多个事件触发器,
使用相同或不同的 Event。
event-trigger 长写属性集
构成一个协调列表属性组,
以 event-trigger-name 为协调列表基准属性,
协调值列表中的每一项
定义一个事件触发器的属性。
我摘取这段文字所依据的提案 规定它只关心元素是否是事件的目标。 我们可能希望允许冒泡和/或捕获, 也许作为可选择启用/禁用的选项。
4.1. 命名触发器: event-trigger-name 属性
| 名称: | event-trigger-name |
|---|---|
| 值: | none | <dashed-ident># |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
若指定 none, 元素就不定义任何事件触发器。
若相同的 <dashed-ident> 在列表中多次出现, 仅最后一项定义事件触发器; 之前的项均无效。
4.2. 关联事件: event-trigger-source 属性
| 名称: | event-trigger-source |
|---|---|
| 值: | [ none | <event-function>+ [ / <event-function>+ ]? ]# |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
event-trigger-source 属性 指定哪些事件会激活事件触发器。 其取值如下:
- none
-
协调值列表中的对应项不定义触发器。
- <event-function>+ [ / <event-function>+ ]?
-
定义事件触发器响应哪些事件。
若值中使用了 /, 则事件触发器是有状态的; / 之前的事件集是事件触发器的进入事件, / 之后的事件集则是退出事件。 (同一事件可同时出现在两个集合中。)
4.2.1. 事件函数
<event-function> = <click()> | <dblclick()> | <pointerenter()> | <pointerleave()> | <pointerup()> | <pointerdown()> | <keypress()> | <focusin()> | <focusout()> | <input()> | <change()> click() = click() dblclick() = dblclick() pointerenter() = pointerenter() pointerleave() = pointerleave() pointerup() = pointerup() pointerdown() = pointerdown() focusin() = focusin() focusout() = focusout() input() = input() change() = change()
click()、dblclick()、pointerenter()、pointerleave()、
pointerup()、pointerdown()、focusin()、focusout()、
input() 和 change() 分别在元素
收到对应的 Event 类型时激活或停用触发器。
-
keypress() = keypress( <string>? )
-
在发生以下事件时激活或停用触发器:
keypressKeyboardEvent。 可选的 <string> 参数 指定触发器响应的KeyboardEvent.key值, 以空格分隔的列表表示。 如果该值为单个空格(" "), 则将其解释为“Space”键。 如果该值为空字符串(""), 则将其解释为未提供。
4.3. event-trigger 简写属性
| 名称: | event-trigger |
|---|---|
| 值: | none | [ <'event-trigger-name'> <'event-trigger-source'> ]# |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 动画类型: | 不可动画 |
| 规范顺序: | 按语法 |
event-trigger 简写属性 同时设置 event-trigger-name 和 event-trigger-source。
值 none 等价于 none none。
5. 触发式动画
默认情况下,只要在元素上 设置了适当的 animation 值,CSS 动画就会自动运行; animation-trigger 属性则允许将动画的开始推迟, 直到适当的触发器触发, 甚至允许触发器暂停、重新开始或重置动画 (使其成为触发式动画)。
5.1. animation-trigger 属性
| 名称: | animation-trigger |
|---|---|
| 值: | [ none | [ <dashed-ident> <animation-action>+ ]+ ]# |
| 初始值: | none |
| 适用于: | 所有元素 |
| 是否继承: | 否 |
| 百分比: | 不适用 |
| 计算值: | 与指定值相同 |
| 规范顺序: | 按语法 |
| 动画类型: | 不可动画 |
animation-trigger 属性 指定动画是否为触发式动画, 若是, 还指定它响应哪个触发器, 以及响应时采取哪些动作。 animation-trigger 是仅重置子属性,属于 animation 简写属性。 其取值如下:
- none
-
对应的动画不是触发式动画。
- [ <dashed-ident> <animation-action>+ ]+
-
对应的动画是触发式动画, 响应各个 <dashed-ident> 命名的触发器, 并以执行对应 <animation-action> 指定的动作来响应。 (§ 2.3 触发器名称作用域:trigger-scope 属性说明如何将 <dashed-ident> 解析为触发器。)
触发器接受多少个 <animation-action>, 以及究竟由什么激活这些动作, 由触发器的类型决定。 (事件触发器接受一个动作,并视其无状态或有状态而可能接受可选的第二个动作; 时间轴触发器接受一个动作及可选的第二个动作。) 指定错误数量的动作 (过多或过少) 在语法上有效, 但会使触发器不起作用。
若多个触发器同时触发, 它们按指定顺序生效。
若相同的 <dashed-ident> 被指定多次, 除最后一个之外均无效。
<animation-action> 的可能取值, 以及它们在各动画状态下的效果如下:
| 关键词 | 额外效果 | 初始 | 播放中 | 已暂停 | 已结束 |
|---|---|---|---|---|---|
| none | — | — | — | — | — |
| play | — | play()
| — | play()
| play()
|
| play-once | — | play()
| — | play()
| — |
| play-forwards | 将播放速率设为正值 | play()
| — | play()
| play()
|
| play-backwards | 将播放速率设为负值 | play()
| — | play()
| play()
|
| pause | — | — | pause()
| — | — |
| reset | 将进度设为 0 | — | pause()
| pause()
| pause()
|
| replay | 将进度设为 0 | play()
| — | play()
| play()
|
6. 编程接口
6.1. AnimationTrigger 接口<
[Exposed =Window ]interface {AnimationTrigger constructor (optional AnimationTriggerOptions options = {});attribute AnimationTimeline timeline ;attribute AnimationTriggerBehavior ;behavior attribute any activationRangeStart ;attribute any activationRangeEnd ;attribute any activeRangeStart ;attribute any activeRangeEnd ; };
AnimationTrigger(options)-
使用以下过程创建新的
AnimationTrigger对象:-
创建新的
AnimationTrigger对象 trigger。 -
将 trigger.已触发设为 false。
-
设置激活范围(属于 trigger),使用 options.
activationRangeStart和 options.activationRangeEnd, 分别遵循与KeyframeAnimationOptions的rangeStart和rangeEnd成员相同的规则。 -
设置活动范围(属于 trigger),使用 options.
activeRangeStart和 options.activeRangeEnd, 遵循上述激活范围的相同规则,除非其值为 "auto";在这种情况下,将它们设为 激活范围的对应边界。
options-
新创建的触发器的配置参数。
-
6.2. AnimationTriggerOptions 字典
dictionary {AnimationTriggerOptions AnimationTimeline ?timeline ;AnimationTriggerBehavior ?= "once"; (behavior TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString )activationRangeStart = "normal"; (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString )activationRangeEnd = "normal"; (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString )activeRangeStart = "auto"; (TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString )activeRangeEnd = "auto"; };
timeline, 类型为 AnimationTimeline,可为 null-
触发器关联的时间轴。 若未指定,则关联默认文档时间轴。
activationRangeStart, 类型为(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString),默认值为"normal"-
触发器的激活范围的起点。 若未指定,激活范围的起点设为 "normal"。
activationRangeEnd, 类型为(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString),默认值为"normal"-
触发器的激活范围的终点。 若未指定,激活范围的终点设为 "normal"。
activeRangeStart, 类型为(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString),默认值为"auto"-
触发器的活动范围的起点。 若未指定,活动范围的起点设为 "auto"。
activeRangeEnd, 类型为(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString),默认值为"auto"-
触发器的活动范围的终点。 若未指定,活动范围的终点设为 "auto"。
7. 隐私注意事项
本规范的特性没有已知的隐私影响。
8. 安全注意事项
本规范的特性没有已知的安全影响。