JS addEventListener的once和passive选项有什么用

作者:寒星

时间:2026-11-22

浏览:270

深入解析JavaScript中addEventListener的once和passive选项的作用、运行机制、适用场景与性能收益,结合完整代码示例与多线程滚屏原理图解,助你写出更优雅、高流畅度的前端交互代码。

文章目录

在编写 JavaScript 事件监听代码时,很多开发者习惯只传前两个参数:事件类型和回调函数。然而 addEventListener 的第三个参数可以传入一个配置对象,其中最常用也最具实用价值的便是 once 和 passive。简而言之,once 负责事件的生命周期管理,让回调函数仅执行一次便自动彻底卸载,避免手动解绑的繁琐与内存泄漏;passive 负责页面的滚动性能优化,向浏览器提前承诺“回调中绝不阻止默认滚动”,让浏览器合成器线程实现零延迟的顺滑滚动,消除高频滑动手势下的卡顿掉帧。掌握这两个选项,能够从代码健壮性与页面运行性能两个维度直接提升前端应用质量。

JS addEventListener的once和passive选项有什么用
图 1:addEventListener 的 options 配置模型与核心选项定位

一、语法沿革:从布尔值到配置对象

在早期的 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 });
JS addEventListener的once和passive选项有什么用
图 2: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() 后,合成器线程才能开始滚动。如果主线程此时正在解析大型数据、执行繁重的组件渲染,合成器线程就要等待几十毫秒甚至上百毫秒,用户手指下就会出现肉眼可见的迟滞、掉帧与卡顿。

JS addEventListener的once和passive选项有什么用
图 3:passive: true 在浏览器主线程与合成器线程间的并发机制对比

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 中调用 preventDefault()
如果你将监听器标记为 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
);

五、决策流程与场景总结

JS addEventListener的once和passive选项有什么用
图 4:addEventListener 选项选型决策树与高频场景匹配指南
选项名称 取值类型 默认行为 核心解决问题 推荐使用场景
once Boolean false(持续监听) 免去手动 removeEventListener,自动清理内存 动画结束回调、首屏资源就绪、单次弹窗确认、防重点击
passive Boolean 通常为 false(全局 touch 为 true) 解除合成器线程对主线程的等待,彻底消除滚屏掉帧 touchmove、wheel、页面位移跟踪、滚动指示器
once + passive Boolean 组合 均为 false 既要单次触控响应,又要确保触控期间页面毫无迟滞 首帧滑动手势检测、单次手势引导动画、开屏滑动揭层
核心记忆口诀:
• 只用一次,选 once: true:省代码、免引用、防泄漏。
• 滚屏触控,选 passive: true:不等待、零卡顿、极速滑。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章