前端 addEventListener 怎样用 once 自动移除一次性监听

我在给按钮补“只处理一次”的交互时，最容易先想到的是在回调里手动计数，或者执行完再调用 removeEventListener()。更直接的写法是给 addEventListener() 的第三个参数传入 { once: true }：监听器最多被调用一次，调用后由事件目标自动移除。once 默认是 false，所以普通监听仍会持续响应后续事件。

只要需求是“这个监听器成功响应一次后就不再保留”，优先使用 once: true；如果动作可能在触发前被取消，或者需要统一取消一组监听器，再使用命名函数配合 removeEventListener() 或 AbortSignal。

• 一次性回调：addEventListener(type, listener, { once: true })。
• 提前取消：保存同一个函数引用，或让多个监听器共享一个 AbortSignal。
• 关键边界：once 只在监听器被调用后自动移除，事件一直不发生时它不会凭空消失。

一次性动作为什么容易变成重复监听

普通的 addEventListener() 适合持续监听，例如让输入框每次变化都刷新提示。但“首次点击后打开一次弹窗”“第一次提交后禁用引导”属于一次性动作。如果组件重新渲染或初始化函数被重复调用，而代码每次都注册一个新函数，目标对象上就可能同时存在多个回调。

这里有一个容易忽略的区别：即使两个匿名函数的代码看起来完全相同，它们也是不同的函数对象。后续想用 removeEventListener() 清理时，没有保存原始引用就找不到对应的监听器。一次性需求不必先设计一套计数变量，先从监听生命周期判断，往往更简单。

once 让一次性动作自己完成清理

once 是监听器选项，不是事件类型。它与 capture、passive 等选项放在同一个对象中，默认值为 false。下面这个例子把“首次点击后显示提示”交给事件系统管理：

const button = document.querySelector('#save-button');

// once 让这个回调最多响应一次，适合一次性确认动作。
button.addEventListener('click', (event) => {
  // 通过事件对象找到当前目标，避免把处理逻辑写死到全局节点。
  event.currentTarget.textContent = '已处理';
}, { once: true });

首次点击后，回调执行，监听器随后不再保留。第二次点击不会再次进入这个回调。注意，“最多一次”不等于“必定执行一次”：如果用户从未点击，监听器仍处于等待状态；如果业务需要在页面卸载或流程取消时提前结束，应该显式取消它。

如果希望复用同一个处理函数，也可以把函数单独命名：

function handleFirstSubmit(event) {
  // 这里只处理第一次提交，后续提交不会再次调用该监听器。
  event.preventDefault();
  console.log('首次提交已接收');
}

const form = document.querySelector('#profile-form');
// 注册时启用 once，避免成功响应后还要手动移除。
form.addEventListener('submit', handleFirstSubmit, { once: true });

提前取消时不要只依赖 once

我更愿意把三种需求分开：回调成功触发一次后自动结束，用 once；触发前决定不再等待，用 removeEventListener()；多个监听器要一起终止，用 AbortController 的信号。

const panel = document.querySelector('#panel');

function handlePanelClick(event) {
  // 保留函数引用，后面才能按同一个监听器移除。
  console.log('面板点击', event.target);
}

// 先注册一个可持续监听的处理函数。
panel.addEventListener('click', handlePanelClick);

// 业务状态结束时，使用同一个函数引用主动取消监听。
function stopPanelListening() {
  panel.removeEventListener('click', handlePanelClick);
}

removeEventListener() 至少要匹配同一个目标、事件类型、函数引用以及注册时的 capture 值。其他选项不会被它用来判断是否匹配，因此不要把“换一个匿名函数再移除”当作清理方案。

const controller = new AbortController();
const signal = controller.signal;
const button = document.querySelector('#refresh-button');

// 同一信号可以绑定到需要一起结束的监听器。
button.addEventListener('click', handleRefresh, { signal });
window.addEventListener('online', handleNetwork, { signal });

// 页面离开或任务取消时，统一让关联监听器停止等待。
function cancelRefreshTask() {
  controller.abort();
}

function handleRefresh() {
  // 这里只演示监听关系，真实刷新逻辑应自行处理异常。
  console.log('刷新请求已触发');
}

function handleNetwork() {
  // 网络状态变化只在任务尚未取消时有意义。
  console.log('网络状态已变化');
}

兼容和边界：先选清理时机，再选写法

现代浏览器普遍支持 addEventListener() 的 once 与 signal 选项，但项目仍应以自身支持矩阵为准。对一次性点击、一次性提交、首次完成回调这类“触发后就结束”的任务，once 语义最清楚；对可能提前关闭的弹窗、路由切换或异步任务，保存函数引用或共享 AbortSignal 更合适。

还有两个常见误区：

• 不要在初始化函数中无条件重复注册匿名函数；如果初始化可能多次执行，先决定是复用引用、先移除，还是直接使用 once。
• 不要把 passive 当成清理选项。它表示监听器不会调用 preventDefault()，与“触发后是否保留”是两件事。

我的采用顺序是：先问“监听器什么时候结束”，再问“谁负责结束”。结束时机是首次触发，就用 once；结束时机由业务状态决定，就用 removeEventListener()；结束动作需要一组监听器共同响应，就用 AbortController。这样代码的生命周期和业务意图能保持一致。

常见问题

once 为 true 后，事件没发生会自动移除吗？

不会。once 表示监听器被调用后最多保留一次；如果事件从未发生，它仍在等待事件。需要提前终止时，请用函数引用移除或调用关联控制器的 abort()。

removeEventListener 为什么没有移除匿名函数？

因为重新写出的匿名函数是新的函数对象，不等于注册时的那个引用。将处理函数保存到变量或命名函数中，再用同一个引用移除。