JS addEventListener的once和passive选项有什么用
深入解析JavaScript中addEventListener的once和passive选项的作用、运行机制、适用场景与性能收益,结合完整代码示例与多线程滚屏原理图解,助你写出更优雅、高流畅度的前端交互代码。
在编写 JavaScript 事件监听代码时,很多开发者习惯只传前两个参数:事件类型和回调函数。然而 addEventListener 的第三个参数可以传入一个配置对象,其中最常用也最具实用价值的便是 once 和 passive。简而言之,once 负责事件的生命周期管理,让回调函数仅执行一次便自动彻底卸载,避免手动解绑的繁琐与内存泄漏;passive 负责页面的滚动性能优化,向浏览器提前承诺“回调中绝不阻止默认滚动”,让浏览器合成器线程实现零延迟的顺滑滚动,消除高频滑动手势下的卡顿掉帧。掌握这两个选项,能够从代码健壮性与页面运行性能两个维度直接提升前端应用质量。
一、语法沿革:从布尔值到配置对象
在早期的 DOM 规范中,addEventListener 的第三个参数是一个布尔值 useCapture,用于控制事件是在捕获阶段还是冒泡阶段触发:
// 传统写法:第三个参数只能是布尔值 useCapture
element.addEventListener('click', handler, false);
随着现代 Web 应用对交互复杂度与渲染性能要求的提高,W3C 与 WHATWG 在 DOM 规范中将第三个参数扩展为 options 对象。这个对象不仅完全兼容以往的 capture 属性,还引入了 once、passive 以及用于强行中断监听的 signal 属性:
// 现代写法:传入精细化 options 配置对象
element.addEventListener(type, listener, {
capture: false, // 是否在捕获阶段执行,默认为 false
once: true, // 是否单次执行后自动销毁,默认为 false
passive: true, // 是否为被动监听(不阻止默认行为),提升滚动性能
signal: controller.signal // 可选的 AbortSignal 控制器
});
二、once 选项:精准管理单次触发与避免内存泄漏
很多交互逻辑在组件生命周期内只需要执行一次。例如:展示引导气泡并等待用户首次点击、监听某个首屏资源的就绪状态、捕捉一次 CSS 过渡动画结束(transitionend),或者表单首次提交时的初始化防重逻辑。
1. 传统手动解绑的痛点
在没有 once 选项之前,开发者要实现“单次监听”,必须在回调函数内部主动调用 removeEventListener。这种方式存在明显的弊端:
// 传统做法:必须定义命名函数,无法直接使用匿名箭头函数
const submitBtn = document.querySelector('#submitBtn');
function handleSubmit(event) {
console.log('表单首次点击提交');
// 必须显式解除绑定
submitBtn.removeEventListener('click', handleSubmit);
}
submitBtn.addEventListener('click', handleSubmit);
这种写法必须依赖外部具名函数或在内部使用具名函数表达式,无法直接写清晰内联的匿名箭头函数;更严重的是,一旦逻辑分支较多或因代码改动漏掉了 removeEventListener,该回调函数将长期驻留在内存中持续响应,极易引发内存泄漏或重复执行逻辑的 Bug。
2. 使用 once: true 的自动化解绑
使用 once: true 后,无论回调函数如何编写,浏览器底层会在首次事件触发并执行完毕后,自动且立即将该监听器从 DOM 节点的监听列表中剔除:
// 现代写法:优雅直观,安全且无内存悬挂
submitBtn.addEventListener('click', (event) => {
console.log('仅触发一次,执行后浏览器自动注销');
}, { once: true });
3. 常见实战场景
- CSS 动画与过渡监听:例如给卡片添加淡出类名后,监听
transitionend或animationend执行 DOM 移除,使用{ once: true }能确保只执行一次,即使内部触发了子元素的过渡也不会造成混乱。 - 媒体资源首次就绪:监听音频或视频元素的
canplaythrough或play进行首播初始化。 - 单次引导浮层与快捷键监听:网页加载后按任意键关闭蒙版,监听
keydown并配置{ once: true }。
三、passive 选项:消除滚屏卡顿的性能利器
如果说 once 是为了代码优雅和内存安全,那么 passive: true 则是直接决定页面滚动帧率与流畅度的关键属性。
1. 为什么移动端滚动容易顿挫?
现代浏览器的渲染架构通常分为主线程(Main Thread)和合成器线程(Compositor Thread)。页面的平滑滚动、缩放等视口位移渲染通常由合成器线程直接在 GPU 协作下高效完成,能轻易达到 60FPS 甚至 120FPS。
然而,当开发者在页面上监听了 touchstart、touchmove 或鼠标 wheel 事件时,浏览器遇到了一个两难问题:浏览器无法预知你的 JS 回调里是否会执行 event.preventDefault() 来阻止默认滚动。
在没有被动标记(即默认 passive: false)的情况下,合成器线程每当检测到用户手指滑动屏幕,都必须被迫暂停页面滚动,向主线程发起同步询问;主线程随后将事件放入事件循环、调用你的 JS 回调;直到回调执行完毕、确认没有调用 preventDefault() 后,合成器线程才能开始滚动。如果主线程此时正在解析大型数据、执行繁重的组件渲染,合成器线程就要等待几十毫秒甚至上百毫秒,用户手指下就会出现肉眼可见的迟滞、掉帧与卡顿。
2. passive: true 如何实现性能飞跃?
给监听器添加 passive: true,相当于提前向浏览器内核立下一份契约:“我的回调逻辑只做数据统计或界面联动,绝对不会调用 event.preventDefault() 阻止滚动”。
收到这个明确承诺后,合成器线程在用户滑动屏幕的瞬间,无需等待主线程分毫,直接以最高优先级在 GPU 上实时渲染页面滚动,同时以异步形式把事件通知给主线程去执行你的 JS 回调。滚动与 JS 逻辑双线程并行运转,页面从此告别手势粘滞与顿挫。
// 标记 passive: true,保障万无一失的丝滑触控
window.addEventListener('touchmove', (e) => {
// 进行滚动进度计算、埋点统计或吸顶样式计算
const currentY = e.touches[0].clientY;
updateScrollIndicator(currentY);
}, { passive: true });
如果你将监听器标记为
passive: true,却依然在回调内部调用了 e.preventDefault(),浏览器会直接忽略该调用,页面滚动依然会正常发生,同时浏览器控制台会打印醒目的警告:[Intervention] Unable to preventDefault inside passive event listener invocation.
3. 现代浏览器的默认机制
为了拯救移动端糟糕的滚屏体验,Chrome 51+、Firefox、Safari 等现代浏览器已经做出了一项激进的优化介入(Intervention):在 window、document 和 document.body 上监听的 touchstart 与 touchmove 事件,默认情况下 passive 就已经是 true。
但这并不意味着我们可以高枕无忧:
- 在局部可滚动容器(如
<div class="scroll-box">)或者自定义滚动条上监听触摸与滚轮时,默认值依然可能是false,需要开发者主动显式声明{ passive: true }才能获得极速性能; - 如果你的确需要制作画板手绘、自制滑动手势拦截器,需要主动拦截默认滚动,你必须显式传入
{ passive: false }覆盖浏览器在全局节点上的默认行为。
四、进阶组合与兼容性方案
1. 选项的强力组合
options 对象的各个属性是彼此正交、互不冲突的,可以自由搭配使用:
// 场景:监听用户首次在屏幕上滑动的手势引导(单次且要求丝滑无阻)
container.addEventListener('touchmove', (e) => {
dismissSwipeHint();
}, {
once: true,
passive: true
});
2. 老旧环境兼容性检测(Feature Detection)
现代所有主流浏览器均已原生支持 options 参数。如果在极老旧的环境(如 IE 11)下运行,浏览器只会将第三个参数强制转为布尔值判断(Boolean({ passive: true }) === true),从而错误地当成 useCapture = true。如果需要兼容极度严苛的老系统,可以通过定义对象属性 getter 的方式检测当前环境是否支持 options:
let supportsPassive = false;
try {
const opts = Object.defineProperty({}, 'passive', {
get() { supportsPassive = true; return true; }
});
window.addEventListener('testPassive', null, opts);
window.removeEventListener('testPassive', null, opts);
} catch (e) {}
// 安全调用
elem.addEventListener(
'touchstart',
handler,
supportsPassive ? { passive: true } : false
);
五、决策流程与场景总结
| 选项名称 | 取值类型 | 默认行为 | 核心解决问题 | 推荐使用场景 |
|---|---|---|---|---|
once |
Boolean | false(持续监听) |
免去手动 removeEventListener,自动清理内存 | 动画结束回调、首屏资源就绪、单次弹窗确认、防重点击 |
passive |
Boolean | 通常为 false(全局 touch 为 true) |
解除合成器线程对主线程的等待,彻底消除滚屏掉帧 | touchmove、wheel、页面位移跟踪、滚动指示器 |
once + passive |
Boolean 组合 | 均为 false |
既要单次触控响应,又要确保触控期间页面毫无迟滞 | 首帧滑动手势检测、单次手势引导动画、开屏滑动揭层 |
• 只用一次,选
once: true:省代码、免引用、防泄漏。• 滚屏触控,选
passive: true:不等待、零卡顿、极速滑。
JS轮播插件移动端触摸滑动失效或卡顿怎么解决
2026-11-22 16:10:37
JS定时循环怎么正确清除以防止内存泄漏
2026-11-21 23:25:30
前端JS加密中密钥安全管理与防泄露策略
2026-11-21 15:33:43
读完JavaScript高级程序设计后该怎么规划前端进阶路线
2026-11-20 23:46:03
JS调用reload()无效或导致无限循环刷新的原因排查
2026-11-20 21:13:33








