动画触发器

W3C 首份公开工作草案,

本文档的更多详细信息
此版本:
https://www.w3.org/TR/2026/WD-animation-triggers-1-20261020/
最新发布版本:
https://www.w3.org/TR/animation-triggers-1/
编辑草案:
https://drafts.csswg.org/animation-triggers-1/
历史:
https://www.w3.org/standards/history/animation-triggers-1/
反馈:
CSSWG 议题仓库
规范中的行内议题
编辑者:
(Google)
(Google)
(Wix.com)
建议编辑本规范:
GitHub 编辑器
测试套件:
https://wpt.fyi/results/web-animations/

本页是非官方中文译文。W3C 英文原文是权威版本;本译文未经 W3C 认可。原版权和许可声明保留;W3C 软件与文档许可全文。

W3C Software and Document License (2023) — NOTICE
W3C Software and Document License (2023)
https://www.w3.org/copyright/software-license-2023/

This work is being provided by the copyright holders under the following license.

License

By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission to copy, modify, and distribute this work, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the work or portions thereof, including modifications:

The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.

Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C software and document short notice should be included.

Notice of any changes or modifications, through a copyright statement on the new code or document such as "This software or document includes material copied from or derived from [title and URI of the W3C document]. Copyright © [$year-of-document] World Wide Web Consortium. https://www.w3.org/copyright/software-license-2023/"

Disclaimers

THIS WORK IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENT WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENT.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the work without specific, written prior permission. Title to copyright in this work will at all times remain with copyright holders.

摘要

定义 CSS 属性和 API,用于创建影响动画播放的机制, 其依据为用户交互产生的 DOM 事件,或动画时间轴上 范围的进入/退出。

CSS 是一种用于描述结构化文档 (如 HTML 和 XML)在屏幕、纸张等媒介上 如何渲染的语言。

本文档的状态

本节描述本文档发布时的状态。 当前 W3C 出版物列表 及本技术报告的最新修订版 可在W3C 标准与草案索引中找到。

本文档 由CSS 工作组 作为首份公开工作草案,采用推荐标准 流程发布。 以首份公开工作草案形式发布 不意味着获得 W3C 及其成员的认可。

本文档是一份草案, 随时可能被其他文档更新、替换 或废弃。 引用时,不能将本文档视为进行中的工作以外的内容。

请通过 在 GitHub 提交议题的方式(首选)发送反馈, 并在标题中包含规范代码“animation-triggers”,例如: “[animation-triggers] …评论摘要…”。 所有议题和评论均会归档。 也可将反馈发送至已归档的公开邮件列表 www-style@w3.org。

本文档受以下文件约束: 2025 年 8 月 18 日 W3C 流程文档。

本文档由遵循以下政策运作的工作组编制: W3C 专利政策。 W3C 维护着一份 专利披露公开列表, 其中列出了与工作组交付物相关的披露; 该页面还包含专利披露说明。 个人若实际知晓某项专利,并认为其中 包含必要权利要求, 则必须依据 W3C 专利政策第 6 节披露相关信息。

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. 触发器

触发器允许将一个元素上的用户交互 与在另一个(或同一个)元素上应用指定动作关联起来。

目前定义了两类触发器:

触发器定义在某个特定的触发元素上。 所有触发器都有一个触发器名称, 具体的触发器类型决定其激活方式和时机。

触发器定义后,将创建该特定类型的触发器实例, 其作用域由 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>? )
在发生以下事件时激活或停用触发器: keypress KeyboardEvent。 可选的 <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 对象:

  1. 创建新的 AnimationTrigger 对象 trigger。

  2. 将 trigger.已触发设为 false。

  3. 将 trigger.状态设为待定。

  4. 设置激活范围(属于 trigger),使用 options.activationRangeStart 和 options.activationRangeEnd, 分别遵循与 KeyframeAnimationOptions 的 rangeStart 和 rangeEnd 成员相同的规则。

  5. 设置活动范围(属于 trigger),使用 options.activeRangeStart 和 options.activeRangeEnd, 遵循上述激活范围的相同规则,除非其值为 "auto";在这种情况下,将它们设为 激活范围的对应边界。

  6. 将 trigger.timeline 设为 options.timeline。

options

新创建的触发器的配置参数。

timeline, 类型为 AnimationTimeline

返回此触发器的时间轴, 或返回 null(如果时间轴处于非活动状态)。

activationRangeStart, 类型为 any

返回此触发器的激活范围的起点。

activationRangeEnd, 类型为 any

返回此触发器的激活范围的终点。

activeRangeStart, 类型为 any

返回此触发器的活动范围的起点。

activeRangeEnd, 类型为 any

返回此触发器的活动范围的终点。

6.2. AnimationTriggerOptions 字典

dictionary AnimationTriggerOptions {
  AnimationTimeline? timeline;
  AnimationTriggerBehavior? behavior = "once";
  (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. 安全注意事项

本规范的特性没有已知的安全影响。

符合性

文档约定

符合性要求通过描述性断言 和 RFC 2119 术语共同表达。本文档规范性部分中的关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、 “RECOMMENDED”、“MAY” 和 “OPTIONAL” 应按 RFC 2119 中的说明解释。 不过,为便于阅读,这些词在本规范中 不以全大写字母形式出现。

除明确标为非规范性的章节、示例和注释外, 本规范的所有文本均为规范性的。[RFC2119]

本规范的示例以“例如”引出, 或者用 class="example" 与规范性文本区分, 如下所示:

这是一个资料性示例的示例。

资料性注释以“注意”开头, 并用 class="note" 与规范性文本区分,如下所示:

注意,这是资料性注释。

提示属于规范性内容,其样式用于引起特别注意, 并通过 <strong class="advisement"> 与其他规范性文本区分, 如下所示: 用户代理必须提供可访问的替代方案。

符合性类别

本规范的符合性 针对三个符合性类别定义:

样式表
一个 CSS 样式表.
渲染器
一个 UA ,解释样式表的语义,并渲染 使用这些样式表的文档。
创作工具
一个 UA ,编写样式表。

样式表在以下情况下符合本规范: 其中使用本模块所定义语法的所有语句, 依据 CSS 通用语法和本模块所定义各项特性的 独立语法,均为有效。

渲染器在以下情况下符合本规范: 它除了按照相应规范解释样式表外, 还通过正确解析本规范定义的所有特性 并据此渲染文档, 来支持这些特性。不过,用户代理 因设备限制而无法正确渲染文档, 并不会使其不符合规范。(例如,不要求用户代理 在单色显示器上渲染彩色。)

创作工具在以下情况下符合本规范: 它生成的样式表依据 CSS 通用语法 和本模块各项特性的独立语法,在语法上正确, 并满足本模块所述样式表的 所有其他符合性要求。

部分实现

为了让作者能够利用向前兼容的解析规则 指定回退值,CSS 渲染器必须 将其没有可用支持程度的构造视为无效,并在适当情况下 忽略,包括 at 规则、属性、属性值、关键词 以及其他语法构造。 特别是,用户代理不得在同一条多值属性声明中 选择性地忽略不支持的分量值,而接受支持的值: 如果任何值被认为无效 (不支持的值必须如此处理),CSS 要求 忽略整条声明。

不稳定特性和专有特性的实现

为避免与未来稳定的 CSS 特性冲突, CSSWG 建议遵循最佳实践来实现不稳定特性和 CSS 的专有扩展。

非实验性实现

规范达到候选推荐标准阶段后, 即可进行非实验性实现;实现者应当 发布任何候选推荐标准级别特性的无前缀实现, 前提是能够证明其按照规范正确实现。

为建立并保持不同实现之间 CSS 的互操作性,CSS 工作组要求非实验性的 CSS 渲染器在发布任何 CSS 特性的无前缀实现之前, 向 W3C 提交实现报告 (如有必要,还应提交报告中使用的测试用例)。 提交给 W3C 的测试用例须接受 CSS 工作组的审查和修正。

有关提交测试用例和实现报告的更多信息, 可在 CSS 工作组网站查阅: https://www.w3.org/Style/CSS/Test/。 如有疑问,请发送至 public-css-testsuite@w3.org 邮件列表。

索引

本规范定义的术语

通过引用定义的术语

参考文献

规范性参考文献

[CSS-ANIMATIONS-1]
David Baron; et al. CSS Animations Level 1. 2 March 2023. WD. URL: https://www.w3.org/TR/css-animations-1/
[CSS-ANIMATIONS-2]
David Baron; Brian Birtles. CSS Animations Level 2. 2 June 2023. WD. URL: https://www.w3.org/TR/css-animations-2/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 13 January 2022. CR. URL: https://www.w3.org/TR/css-cascade-5/
[CSS-SCOPING-1]
Tab Atkins Jr.; Elika Etemad. CSS Scoping Module Level 1. 3 April 2014. FPWD. URL: https://www.w3.org/TR/css-scoping-1/
[CSS-SHADOW-1]
CSS Shadow Module Level 1. Editor's Draft. URL: https://drafts.csswg.org/css-shadow-1/
[CSS-TYPED-OM-1]
Tab Atkins Jr.; François Remy. CSS Typed OM Level 1. 21 March 2024. WD. URL: https://www.w3.org/TR/css-typed-om-1/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 22 March 2024. CRD. URL: https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 12 March 2024. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS2]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS2/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SCROLL-ANIMATIONS-1]
Brian Birtles; et al. Scroll-driven Animations. 6 June 2023. WD. URL: https://www.w3.org/TR/scroll-animations-1/
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 22 January 2026. WD. URL: https://www.w3.org/TR/selectors-4/
[UIEVENTS]
Xiaoqian Wu. UI Events. 21 February 2026. WD. URL: https://www.w3.org/TR/uievents/
[WEB-ANIMATIONS-1]
Brian Birtles; et al. Web Animations. 5 June 2023. WD. URL: https://www.w3.org/TR/web-animations-1/
[WEB-ANIMATIONS-2]
Brian Birtles; Robert Flack. Web Animations Module Level 2. 20 November 2025. WD. URL: https://www.w3.org/TR/web-animations-2/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

属性索引

名称 值 初始值 适用于 是否继承 百分比 动画类型 规范顺序 计算值
animation-trigger [ none | [ <dashed-ident> <animation-action>+ ]+ ]# none 所有元素 否 不适用 不可动画 按语法 与指定值相同
event-trigger none | [ <'event-trigger-name'> <'event-trigger-source'> ]# none 所有元素 否 不适用 不可动画 按语法 与指定值相同
event-trigger-name none | <dashed-ident># none 所有元素 否 不适用 不可动画 按语法 与指定值相同
event-trigger-source [ none | <event-function>+ [ / <event-function>+ ]? ]# none 所有元素 否 不适用 不可动画 按语法 与指定值相同
timeline-trigger none | [ <'timeline-trigger-name'> <'timeline-trigger-source'> [ <'timeline-trigger-range'> ]? ]# 参见各个属性 参见各个属性 参见各个属性 参见各个属性 参见各个属性 按语法 参见各个属性
timeline-trigger-activation-range [ <'timeline-trigger-activation-range-start'> <'timeline-trigger-activation-range-end'>? ]# 参见各个属性 参见各个属性 参见各个属性 参见各个属性 参见各个属性 按语法 参见各个属性
timeline-trigger-activation-range-end [ normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# normal 所有元素 否 相对于指定的具名时间轴范围(若已指定),否则相对于整个时间轴 不可动画 按语法 列表,各项为关键词 normal 或时间轴范围与进度百分比
timeline-trigger-activation-range-start [ normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# normal 所有元素 否 相对于指定的具名时间轴范围(若已指定),否则相对于整个时间轴 不可动画 按语法 列表,各项为关键词 normal 或时间轴范围与进度百分比
timeline-trigger-active-range [ <'timeline-trigger-active-range-start'> <'timeline-trigger-active-range-end'>? ]# 参见各个属性 参见各个属性 参见各个属性 参见各个属性 参见各个属性 按语法 参见各个属性
timeline-trigger-active-range-end [ auto | normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# auto 所有元素 否 相对于指定的具名时间轴范围(若已指定),否则相对于整个时间轴 不可动画 按语法 列表,各项为关键词 normal 或时间轴范围与进度百分比
timeline-trigger-active-range-start [ auto | normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]# auto 所有元素 否 相对于指定的具名时间轴范围(若已指定),否则相对于整个时间轴 不可动画 按语法 列表,各项为关键词 normal 或时间轴范围与进度百分比
timeline-trigger-name none | <dashed-ident># none 所有元素 否 不适用 不可动画 按语法 与指定值相同
timeline-trigger-range [ <'timeline-trigger-activation-range'> [ / <'timeline-trigger-active-range'> ]? ]# 参见各个属性 参见各个属性 参见各个属性 参见各个属性 参见各个属性 按语法 参见各个属性
timeline-trigger-source [ none | auto | [ <dashed-ident> | <scroll()> | <view()> ]+ ]# auto 所有元素 否 不适用 不可动画 按语法 与指定值相同
trigger-scope none | all | <dashed-ident># none 所有元素 否 不适用 不可动画 按语法 与指定值相同

IDL 索引

[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;
};

dictionary AnimationTriggerOptions {
  AnimationTimeline? timeline;
  AnimationTriggerBehavior? behavior = "once";
  (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";
};

议题索引

本段所依据的提案 规定仅在元素是以下对象时才予以考虑: 目标 (该事件的目标)。 我们可能希望允许冒泡和/或捕获, 或许可通过选择加入/退出来控制。 ↵