定义
transitionend 是一种由浏览器在 CSS 过渡动画完成时派发的 DOM 事件, 属于 CSS 过渡规范中的过渡事件之一。[1][2]它的监听对象可以是具体元素, 也可以是文档对象或窗口对象。[3]开发者既可以用 addEventListener 方法按事件名注册监听, 也可以给目标对象设置 ontransitionend 事件处理属性, 两种写法效果一致。[1][4]
事件对象为 TransitionEvent, 继承自 Event, 除了父接口的属性外, 还提供 propertyName、elapsedTime、pseudoElement 3 个只读属性。[1]该事件不可取消, 原因是它没有默认动作, 取消操作没有实际意义, 这一点也与动画事件保持一致。[5]
原理
当可动画属性的计算值发生变化, 且满足过渡开启条件时, 浏览器会创建一条过渡, 其持续时间由 transition-duration 决定, 起始时间还要加上 transition-delay。[2]当时间到达该过渡的结束时刻, 浏览器就会派发 transitionend 事件。[1]规范把过渡的持续时间与延迟之和视作组合时长, 只有组合时长为正值时才可能产生过渡和相应事件; 如果延迟和时长都为 0 或都未声明, 则不会发生过渡, 也就不会派发任何过渡事件。[1][2]
过渡事件的处理与派发遵循 Web 动画的统一模型, 事件先进入文档的待处理动画事件队列, 在更新渲染阶段统一排序并派发, 因此同一轮渲染中产生的多个过渡结束事件会被批量处理。[6][7]事件对象携带的 elapsedTime 表示事件触发时过渡已经运行的时间, 单位为秒, 且不受 transition-delay 影响; propertyName 给出与该过渡对应的 CSS 属性名, pseudoElement 则以 :: 开头给出过渡所在伪元素的名称, 若发生在元素本身上则为空字符串。[1]
发展历程
CSS 过渡的完成会生成对应的 DOM 事件, 这一机制在 CSS 过渡规范早期文本中已有规定, 并被列为向开发者同步动画完成状态的手段。[2]2011 年 2 月, 规范邮件列表曾讨论过渡在中途被改变取值时该如何处理, 有参与者指出当时各实现并不会在过渡被提前终止时立即派发 transitionend, 甚至完全不派发。[8]2014 年 1 月, CSS 工作组对规范作出修改, 明确 transitionend 事件不再可取消, 理由是该事件没有默认动作。[5]
在浏览器实现方面, 早期各引擎使用带厂商前缀的事件名, 常见写法包括 webkitTransitionEnd 等, 不少库通过特性检测在前缀名与标准名之间选择。[9]2012 年底到 2013 年初, 无前缀的 transitionend 在 WebKit 中开始出现但仍不完整, 为此相关缺陷被记录并修复, 修复后 WebKit 的处理方式为: 若元素上存在标准名监听器就只派发标准事件, 只有在仅存在前缀名监听器时才派发对应前缀事件; 若两者同时存在, 则只派发标准事件。[9][10]其后该特性在各主流浏览器中逐步稳定, 相关文档将其标注为可用范围广泛的能力。[1]
应用
transitionend 最常见的用途是在一段 CSS 过渡播放完毕后执行后续动作, 例如在元素完成旋转或透明度变化后更新界面文字或触发下一个效果。[1]由于一个元素上可能同时存在多个属性的过渡, 每个发生过渡的属性都会各自产生一个结束事件, 开发者可通过 propertyName 区分具体是哪个属性完成了过渡。[2][1]
在实际工程中, 该事件常与 transitionrun、transitionstart、transitioncancel 配合使用, 用于跟踪过渡从创建、开始到结束或取消的完整生命周期。[1]有开发者提出以 transitionrun 作为判定起点, 一旦收到该事件, 后续必然收到 transitionend 或 transitioncancel 之一, 据此可以封装等待元素过渡完成的逻辑。[11]在测试场景中, 也存在主动派发 transitionend 事件以验证组件行为的做法。[12]
局限
transitionend 最突出的局限是它并不保证一定触发。若过渡在完成前被移除, 例如删去 transition-property 或把 display 设为 none, 该事件就不会生成; 若过渡被取消而触发了 transitioncancel 事件, transitionend 也不会再派发。[1]此外, 若过渡的延迟与时长都为 0 或均未声明, 则不产生过渡, 也就不会有任何过渡事件。[1]
在规范讨论中, 各方也指出无法仅凭事件判断元素上是否存在正在运行的过渡, 需要借助 transitionrun 等事件进行跟踪; 通过 getAnimations 获取并等待动画的机制在当时尚未在各浏览器中落地。[11]不同实现在事件派发时序上也曾存在差异, 工作组提出应统一由渲染阶段批量派发过渡事件, 以消除浏览器之间的行为不一致。[7]
参见
-
TransitionEvent —— transitionend 事件所采用的事件接口, 定义了属性名、已运行时间与伪元素等只读属性。
-
transitioncancel —— 过渡被取消时派发的过渡事件, 与 transitionend 互斥。
-
transitionrun —— 过渡首次被创建时派发的事件, 早于延迟阶段。
-
CSS 过渡 —— transitionend 所属的规范体系, 描述属性值在指定时长内平滑变化。
-
Web 动画 —— 浏览器中统一管理 CSS 过渡、CSS 动画与脚本动画的底层模型。
参考资料
- Element：transitionend 事件 [引用日期2026-10-14]
- w3.org 上的网页 [引用日期2026-10-14]
- Element: transitionend event - Web APIs | MDN [引用日期2026-10-14]
- Overview [引用日期2026-10-14]
- Mercurial > drafts / file revision [引用日期2026-10-14]
- w3.org 上的网页 [引用日期2026-10-14]
- w3.org 上的网页 [引用日期2026-10-14]
- w3.org 上的网页 [引用日期2026-10-14]
- show_bug [引用日期2026-10-14]
- github.com 上的网页 [引用日期2026-10-14]
- github.com 上的网页 [引用日期2026-10-14]
- triggerTransitionEnd function [引用日期2026-10-14]