从 `@wheel.prevent.stop` 到事件捕获：一次讲清浏览器事件流与 Vue 事件修饰符

原文链接

从 @wheel.prevent.stop 到事件捕获：一次讲清浏览器事件流与 Vue 事件修饰符

很多人第一次看到下面的代码时，会把它们统称为"浏览器原生事件写法"：

<div @wheel.prevent.stop="onWheel"></div>
<div @wheel.stop="onWheel"></div>

但这里需要先校正一个关键概念：

• wheel 是浏览器原生 DOM 事件；
• preventDefault()、stopPropagation() 是原生 Event 对象的方法；
• @wheel 与 .prevent、.stop 则是 Vue 的模板语法和事件修饰符。

本文的角度是：先建立浏览器事件传播模型，再把 Vue 修饰符逐一映射回原生行为。理解这层映射后，面对 @click.stop、@submit.prevent、@keyup.enter 或 @wheel.capture.passive 等写法，就不必靠记忆猜含义。

1. 一个 DOM 事件经历了什么

假设页面结构如下：

<div id="outer">
  <div id="middle">
    <button id="inner">点击</button>
  </div>
</div>

用户点击 button#inner 时，事件并不是只在按钮上执行。通常可以把事件流理解为三个阶段：

1. 捕获阶段（capturing phase）：事件从外层向目标元素下行。
2. 目标阶段（target phase）：事件到达真正被触发的元素。
3. 冒泡阶段（bubbling phase）：事件再从目标元素向外层上行。

用路径表示就是：

window → document → html → body → #outer → #middle → #inner
                                         捕获 ↓
                                         目标
                                         冒泡 ↑

默认情况下，使用 addEventListener() 注册的监听器属于非捕获监听器，因此常常在目标阶段和冒泡阶段被调用。只有显式传入 { capture: true }，监听器才会在捕获阶段参与处理。

outer.addEventListener('click', () => {
  console.log('outer：捕获阶段')
}, { capture: true })

inner.addEventListener('click', () => {
  console.log('inner：目标阶段')
})

outer.addEventListener('click', () => {
  console.log('outer：冒泡阶段')
})

点击 inner 时，输出顺序大致为：

outer：捕获阶段
inner：目标阶段
outer：冒泡阶段

事件是否会冒泡并不是所有事件都一样。开发中常见的 click、wheel、keydown 等会参与传播；而 focus、blur 本身不冒泡，若要在父元素统一处理焦点变化，通常使用会冒泡的 focusin、focusout。

2. target 与 currentTarget：谁触发，谁在处理

在事件回调里，最容易混淆的是这两个属性：

parent.addEventListener('click', (event) => {
  console.log(event.target)
  console.log(event.currentTarget)
})

• event.target：最初触发事件的元素，例如用户实际点到的按钮或图标。
• event.currentTarget：当前正在执行监听器的元素，例如上例中的 parent。

这正是事件委托能够成立的原因：只在父元素注册一次监听器，也可以根据 event.target 判断具体操作了哪个子元素。

list.addEventListener('click', (event) => {
  const button = event.target.closest('[data-action]')
  if (!button) return

  console.log(button.dataset.action)
})

3. 三个最重要的控制动作

理解事件时，必须严格区分两件事：

1. 事件是否继续传播到其他元素；
2. 浏览器是否继续执行默认行为。

它们不是同一件事。

原生方法	控制的对象	不会做什么
event.stopPropagation()	停止后续传播路径	不阻止浏览器默认行为；不阻止当前元素其他监听器
event.stopImmediatePropagation()	停止传播，并阻止当前元素后续同类监听器	不等同于取消默认行为
event.preventDefault()	取消浏览器默认行为	不停止事件传播

3.1 stopPropagation()：别再传给父层

child.addEventListener('click', (event) => {
  event.stopPropagation()
  console.log('只处理子元素逻辑')
})

parent.addEventListener('click', () => {
  console.log('不会因为这次点击执行')
})

点击子元素后，父元素的冒泡监听器不会执行。

但要注意：stopPropagation() 不会阻止当前元素上已经注册的其他监听器。

button.addEventListener('click', (event) => {
  event.stopPropagation()
  console.log('监听器 A')
})

button.addEventListener('click', () => {
  console.log('监听器 B 仍会执行')
})

如果连当前元素后续的同类监听器也要阻止，才使用 stopImmediatePropagation()。不过在 Vue 组件业务中，这通常不是首选方案；更好的做法往往是理清事件职责，避免多个监听器互相争夺控制权。

3.2 preventDefault()：别执行浏览器默认动作

浏览器会为一部分事件提供默认行为，例如：

• 点击链接后跳转；
• 提交表单后导航或刷新页面；
• 勾选复选框；
• 滚动滚轮后滚动容器或页面。

preventDefault() 表示：这个行为由应用接管，浏览器不要执行默认动作。

link.addEventListener('click', (event) => {
  event.preventDefault()
  console.log('不跳转，改为执行自定义逻辑')
})

它不会自动阻止父元素监听器：

child.addEventListener('click', (event) => {
  event.preventDefault()
})

parent.addEventListener('click', () => {
  console.log('仍然会执行')
})

此外，只有 event.cancelable === true 时，取消默认行为才有效。对于不可取消事件，调用 preventDefault() 不会产生预期结果。

3.3 .stop 与 .prevent 可以同时存在

当一个交互既不应触发上层逻辑，也不应执行浏览器默认行为时，才需要同时使用：

<a href="/detail" @click.stop.prevent="openPreview">
  打开预览
</a>

它等价于在 Vue 生成的事件处理逻辑中，依次执行：

function handler(event) {
  event.stopPropagation()
  event.preventDefault()
  openPreview(event)
}

不要把"链式修饰符"理解成某种新的浏览器 API；它只是 Vue 帮你把原生事件操作按顺序写出来。

4. @wheel.prevent.stop 和 @wheel.stop 到底差在哪里

wheel 是用户转动鼠标滚轮或使用触控板等类似输入设备时触发的原生事件。它与 scroll 不是一回事：滚轮输入不必然造成滚动，滚动也可能由键盘、拖动滚动条或脚本引起。

@wheel.stop

<div class="panel" @wheel.stop="onWheel">
  ...
</div>

它的核心效果是：

function onWheelWrapper(event) {
  event.stopPropagation()
  onWheel(event)
}

结果： 当前 wheel 事件不会再向父级冒泡。

不会自动发生的事： 当前可滚动容器或页面依然可能滚动，因为浏览器默认滚动行为没有被取消。

适用场景：父层也监听了 wheel，但你不希望内层组件的滚轮操作触发父层业务逻辑。例如，父层用滚轮切换幻灯片，而内层是一个独立滚动面板。

@wheel.prevent

<div @wheel.prevent="zoomCanvas"></div>

它会调用 event.preventDefault()。

结果： 如果该次 wheel 事件可取消，浏览器的默认滚动行为会被阻止；你可以把滚轮输入改造成画布缩放、时间轴缩放或地图缩放。

不会自动发生的事： 事件仍然可能冒泡到父元素。

@wheel.prevent.stop

<div @wheel.prevent.stop="zoomCanvas"></div>

它同时完成两件事：

1. 阻止默认滚动；
2. 阻止事件继续向父元素传播。

适用场景：一个嵌在页面或弹窗内的画布区域，需要独占滚轮输入来缩放，同时不能触发页面外层的滚轮逻辑。

一个关于 wheel 的重要限制：不要随意阻止滚动

wheel 事件的高频触发和滚动体验直接相关。只有确实要接管滚轮行为时，才使用 .prevent。如果只是想监听滚动位置变化，应优先监听 scroll，并读取元素的 scrollTop、scrollLeft。

同时，不能组合：

<!-- 不要这样写 -->
<div @wheel.passive.prevent="onWheel"></div>

.passive 的含义是向浏览器承诺"这个监听器不会调用 preventDefault()"；.prevent 的含义恰好相反。Vue 也明确提示不要把二者同时使用：浏览器会忽略被动监听器中的 preventDefault()，并可能给出控制台警告。

5. Vue 事件修饰符：完整分类

Vue 的 @ 是 v-on: 的简写：

<button @click="save">保存</button>
<button v-on:click="save">保存</button>

Vue 官方事件修饰符可以按四类理解。

5.1 事件流与默认行为修饰符

修饰符	对应概念	常见写法	作用
.stop	stopPropagation()	@click.stop	阻止事件继续传播
.prevent	preventDefault()	@submit.prevent	阻止浏览器默认行为
.self	判断 target === currentTarget	@click.self	仅点击元素自身时执行，不处理来自子元素的事件
.capture	{ capture: true }	@click.capture	在捕获阶段处理事件
.once	{ once: true }	@click.once	监听器最多触发一次
.passive	{ passive: true }	@touchmove.passive	声明不会取消默认行为，帮助浏览器更快开始滚动等默认动作

.self 不是 .stop

<div @click.self="closeDialog">
  <section class="dialog-content">
    <button>保存</button>
  </section>
</div>

.self 的意思不是停止冒泡，而是：只有事件直接落在这个 div 自身时，才运行 closeDialog。点击内部按钮时，事件依旧会冒泡，只是这个 div 的处理器因为 event.target !== event.currentTarget 而不执行。

这很适合"点击遮罩关闭弹窗、点击弹窗内容不关闭"的场景。

修饰符顺序有实际影响

Vue 会按照书写顺序生成相关处理逻辑。因此：

<div @click.prevent.self="handler"></div>
<div @click.self.prevent="handler"></div>

两者不同：

• .prevent.self：先取消默认行为，再判断是否由元素自身触发，因此子元素触发的事件也可能被取消默认行为；
• .self.prevent：先判断是否由元素自身触发，只有判断通过后才取消默认行为。

一般建议把"过滤条件"放前面，把"副作用动作"放后面，例如优先写成 @click.self.prevent。

5.2 键盘修饰符

Vue 可以根据 KeyboardEvent.key 过滤键盘事件：

<input @keyup.enter="submit" />
<input @keydown.esc="close" />
<input @keyup.page-down="nextPage" />

常用内置别名包括：

修饰符	对应按键
.enter	Enter
.tab	Tab
.delete	Delete 或 Backspace
.esc	Escape
.space	空格
.up / .down / .left / .right	方向键

除了别名外，也可以使用符合 KeyboardEvent.key 名称的键，以短横线形式书写，例如 .page-down。

5.3 系统按键修饰符与 .exact

系统按键修饰符包括：

• .ctrl
• .alt
• .shift
• .meta

<div @click.ctrl="selectMultiple">Ctrl + 点击</div>
<input @keyup.alt.enter="submitSpecial" />

其中 .meta 在 macOS 上通常对应 Command（⌘），在 Windows 上通常对应 Windows 键。

.exact 用于限制"不能额外按住其他系统键"：

<!-- 按住 Ctrl 即可触发，即使同时按住 Shift 也会触发 -->
<button @click.ctrl="onClick">操作</button>

<!-- 必须恰好只按住 Ctrl，不能额外按住 Alt、Shift、Meta -->
<button @click.ctrl.exact="onCtrlClick">精确操作</button>

<!-- 不允许按住任何系统键 -->
<button @click.exact="onPlainClick">普通点击</button>

5.4 鼠标按键修饰符

Vue 还提供：

• .left
• .right
• .middle

<div @mouseup.left="onPrimaryButtonUp"></div>
<div @mouseup.right.prevent="openContextMenu"></div>
<div @mouseup.middle="openInWorkspace"></div>

它们表达的是"主按键、次按键、辅助按键"，并不绝对等于鼠标物理左、中、右键。对于左手鼠标布局、触控板或其他指针设备，物理按键与"主/次/辅助"映射可能不同。

6. .capture 与 .stop 能一起用吗

可以，但需要知道它们分别发生在不同维度：

<div @click.capture="trackEntry">
  <button @click.stop="runAction">执行</button>
</div>

当点击按钮时：

1. 外层 trackEntry 会在捕获阶段先执行；
2. 到达按钮后，runAction 执行并调用 stopPropagation()；
3. 事件不会再在冒泡阶段回到外层。

所以，子元素的 .stop 无法"撤销"已经发生的祖先捕获阶段监听。若你在祖先元素上使用 .capture，就意味着你希望在事件抵达子元素前优先观察或处理它。

7. .once、.passive 与原生 addEventListener 的关系

Vue 的 .capture、.once、.passive 对应的是原生监听器选项：

el.addEventListener('click', handler, {
  capture: true,
  once: true,
  passive: false
})

在 Vue 中可写为：

<button @click.capture.once="initialize">初始化</button>

而原生 addEventListener() 还有一个 Vue 模板修饰符没有直接对应的常用选项：signal。

const controller = new AbortController()

window.addEventListener('resize', onResize, {
  signal: controller.signal
})

// 统一移除与该 signal 关联的监听器
controller.abort()

当你在 Vue 组件中需要监听 window、document、第三方 DOM 节点或动态创建的元素时，这种原生写法仍然有价值。组件卸载时也应做好清理，或使用 AbortController 集中管理。

8. 选择修饰符的实用决策

可以按下面的问题快速选择：

1. 我要阻止父元素收到这个事件吗？

   • 要：.stop

2. 我要取消浏览器原本会做的动作吗？

   • 要：.prevent
   • 先确认事件可取消，且这不会破坏用户预期或可访问性。

3. 我只关心元素本身，不关心子元素触发的冒泡吗？

   • 要：.self

4. 我必须在子元素处理前先处理吗？

   • 要：.capture

5. 这个操作只能执行第一次吗？

   • 要：.once

6. 我只观察触摸/滚动类输入，绝不会取消默认行为，并希望减少滚动阻塞风险吗？

   • 可以考虑：.passive

7. 我是在处理快捷键或特定鼠标按键吗？

   • 使用键盘、系统按键或鼠标按键修饰符。

9. 常见误区

误区一：.stop 可以阻止滚动

不能。.stop 只阻止传播，不取消默认滚动；需要阻止默认滚动时使用 .prevent，并谨慎评估体验。

误区二：.prevent 可以阻止父元素点击事件

不能。.prevent 只取消默认行为；若还要阻止父元素监听器，需要加 .stop。

误区三：所有事件都能被 .prevent

不能。事件必须是可取消的；并且被动监听器中调用 preventDefault() 会被浏览器忽略。

误区四：wheel 就是 scroll

不是。wheel 表示滚轮或类似设备输入；scroll 表示滚动位置发生变化。要判断实际滚动方向或位置，通常应该监听 scroll 并读取 scrollTop、scrollLeft，而不是只依赖 WheelEvent.deltaY。

误区五：到处添加 .stop

不建议。过度阻断冒泡会破坏事件委托、弹窗外部点击关闭、全局埋点和父组件交互。只有当"事件不该离开当前组件边界"是明确需求时，才添加 .stop。

10. 总结

理解 Vue 事件修饰符的最短路径，是始终回到原生 DOM 事件：

事件类型：wheel、click、keydown、submit......
        ↓
事件传播：捕获 → 目标 → 冒泡
        ↓
控制传播：stopPropagation()
控制默认行为：preventDefault()
        ↓
Vue 语法糖：@事件.修饰符="处理函数"

因此：

<div @wheel.prevent.stop="onWheel"></div>

不是一种独立的"原生事件"，而是 Vue 对原生 wheel 事件做的组合封装：先取消可取消的默认滚动行为，再停止事件传播，最后执行你的 onWheel 逻辑。

当你不确定该用 .stop、.prevent 还是 .self 时，不要先背 API；先问自己：我要阻止的是事件路径，还是浏览器默认动作，还是只是要过滤触发来源？ 答案会自然对应到正确的修饰符。

参考资料

• Vue：事件处理与事件修饰符
• MDN：EventTarget.addEventListener()
• MDN：Event.preventDefault()
• MDN：Event.stopPropagation()
• MDN：WheelEvent