addEventListener 的第三个参数

1. 先明确 addEventListener 的完整参数规范

addEventListener 是浏览器原生用于绑定事件监听的核心 API，其语法严格规定了三个参数的作用，其中第三个参数的形式直接决定了事件监听的高级配置能力：

// 标准语法结构
target.addEventListener(
  type,        // 第1个参数：事件类型（字符串，如 'click' 'scroll' 'resize'）
  listener,    // 第2个参数：事件回调函数（事件触发时执行的逻辑）
  options      // 第3个参数：配置项（布尔值 或 对象，核心讨论对象）
);

第三个参数 options 是灵活配置事件监听的关键，它有且仅有两种合法形式，后续所有特性均围绕这两种形式展开。

2. 第三个参数的两种合法形式

2.1 形式1：布尔值（简单场景，无需大括号）

当仅需控制“事件触发的传播阶段”时，第三个参数可直接传递布尔值，这是最基础的用法：

• true：事件在「捕获阶段」触发（事件从顶层元素向下传递到目标元素的过程中触发）；
• false：事件在「冒泡阶段」触发（事件从目标元素向上传递到顶层元素的过程中触发，默认值）。

示例：控制事件传播阶段

// 第三个参数为布尔值 false，监听 scroll 事件在冒泡阶段触发
window.addEventListener(
  'scroll', 
  () => console.log('滚动事件（冒泡阶段触发）'), 
  false // 无需大括号，直接传布尔值
);

// 第三个参数为布尔值 true，监听 click 事件在捕获阶段触发
document.addEventListener(
  'click', 
  (e) => console.log('点击事件（捕获阶段触发，目标：', e.target, '）'), 
  true
);

适用场景：

仅需简单控制事件传播方向（捕获/冒泡），无“取消监听”“单次触发”等复杂需求。

2.2 形式2：配置对象（复杂场景，必须用大括号）

当需要配置多个事件特性（如取消监听、单次触发、性能优化）时，第三个参数必须是「对象」——而 JavaScript 中定义对象必须用大括号 {} 包裹键值对，这是语法层面的强制要求。

该配置对象支持以下核心属性（ES2015 及以后新增）：

属性名	类型	作用描述
capture	布尔值	同“形式1”的布尔值参数，控制事件触发阶段（捕获/冒泡），优先级高于默认规则
once	布尔值	true 表示事件仅触发一次，触发后自动移除监听（无需手动调用 removeEventListener）
passive	布尔值	true 表示禁止在回调中调用 e.preventDefault()（优化滚动/触摸事件性能，避免卡顿）
signal	AbortSignal	接收来自 AbortController 的信号，用于通过外部指令主动取消事件监听

示例1：通过 signal 实现“可取消的监听”

（与 AbortController 配合，是高频实战场景，必须用大括号）

// 1. 创建取消控制器
const controller = new AbortController();
const { signal } = controller; // 获取信号对象

// 2. 绑定 scroll 监听，第三个参数是配置对象（必须用大括号）
window.addEventListener(
  'scroll', 
  () => console.log('可取消的滚动监听'), 
  { signal: signal } // 大括号包裹：将信号绑定到监听
);

// 3. 3秒后主动取消监听（如用户离开页面、组件卸载时）
setTimeout(() => {
  controller.abort(); // 触发信号，自动移除 scroll 监听
  console.log('scroll 监听已取消');
}, 3000);

示例2：同时配置多个特性

（单次触发 + 捕获阶段 + 性能优化，多属性需用大括号分隔）

// 绑定 click 监听：仅触发一次 + 捕获阶段 + 禁止 preventDefault
document.getElementById('submit-btn').addEventListener(
  'click', 
  (e) => {
    console.log('按钮仅点击一次');
    // 若 passive: true，调用 e.preventDefault() 会报错（禁止默认行为）
  }, 
  {
    once: true,        // 单次触发后自动移除
    capture: true,     // 捕获阶段触发
    passive: true,     // 性能优化：禁止 preventDefault
    signal: controller.signal // 同时支持取消
  } // 大括号：承载多个键值对配置
);

适用场景：

需要“取消监听”“单次触发”“性能优化”等复杂需求，或同时配置多个事件特性时。

3. 为什么配置对象必须用大括号 {}？

第三个参数用大括号，本质是符合 JavaScript 语言的语法规则和满足多配置项的功能需求，具体分两点：

3.1 语法层面：对象必须用 {} 定义

在 JavaScript 中，「对象字面量」（直接创建对象的语法）必须用大括号 {} 包裹键值对（key: value）。如果省略大括号，直接写 signal: controller.signal，JS 会将其解析为语法错误——因为它不符合“参数必须是布尔值或对象”的规则。

错误示例（无大括号）：

// 错误：直接写 signal: xxx 不是合法参数，JS 无法识别为对象
window.addEventListener(
  'scroll', 
  handleScroll, 
  signal: controller.signal // 语法错误！缺少大括号包裹
);

正确示例（有大括号）：

// 正确：用大括号包裹键值对，定义为合法对象
window.addEventListener(
  'scroll', 
  handleScroll, 
  { signal: controller.signal } // 合法的对象参数
);

3.2 功能层面：大括号承载多配置项

当需要同时传递多个配置（如 signal + once + passive）时，只有对象能通过“键值对”的形式组织这些配置——布尔值参数无法满足多特性需求，因此必须用大括号定义对象，将多个配置打包传递。

对比：布尔值 vs 配置对象（功能覆盖）

需求	布尔值参数（无大括号）	配置对象（有大括号）
控制事件阶段（捕获/冒泡）	✅ 支持	✅ 支持（通过 capture）
主动取消监听（signal）	❌ 不支持	✅ 支持
单次触发（once）	❌ 不支持	✅ 支持
滚动性能优化（passive）	❌ 不支持	✅ 支持

4. 关于第三个参数的常见误区

4.1 误区1：认为“大括号是可选的”

只有当第三个参数是纯布尔值时，才可以省略大括号；若使用 signal、once 等任何对象属性，大括号必须存在，否则会触发语法错误。

4.2 误区2：用逗号分隔多个配置（不用大括号）

错误地认为多个配置项可以用逗号直接分隔，忽略对象的语法要求：

// 错误：用逗号分隔配置，不是合法对象
window.addEventListener(
  'click', 
  handleClick, 
  signal: controller.signal, once: true // 语法错误！
);

// 正确：用大括号包裹所有配置
window.addEventListener(
  'click', 
  handleClick, 
  { signal: controller.signal, once: true } // 合法对象
);

4.3 误区3：混淆 signal 与其他参数

signal 是配置对象的属性，不能单独作为第三个参数传递——必须放在大括号内，作为 key: value 对的一部分：

// 错误：直接传递 signal 对象，不符合参数格式
window.addEventListener(
  'scroll', 
  handleScroll, 
  controller.signal // 错误！第三个参数应为布尔值或包含 signal 的对象
);

// 正确：将 signal 作为对象属性传递
window.addEventListener(
  'scroll', 
  handleScroll, 
  { signal: controller.signal } // 正确
);

5. 总结：如何正确使用第三个参数？

需求场景	第三个参数形式	是否需要大括号	示例代码片段
仅控制事件阶段（捕获/冒泡）	布尔值	❌ 不需要	false、true
需取消监听（signal）	配置对象	✅ 必须需要	{ signal: controller.signal }
需单次触发（once）	配置对象	✅ 必须需要	{ once: true }
需性能优化（passive）	配置对象	✅ 必须需要	{ passive: true }
多配置组合（如 signal + once）	配置对象	✅ 必须需要	{ signal: s, once: true, capture: true }

核心结论：
addEventListener 的第三个参数，本质是“事件监听的配置入口”——简单需求用布尔值（无大括号），复杂需求用对象（必须用大括号）。大括号的存在，既是 JavaScript 对象语法的要求，也是承载多配置项的功能需要。