Vue 3 事件透传完全指南：告别 $listeners，掌握更现代的组件通信方式

从 Vue 2 升级到 Vue 3 后，许多开发者都会寻找熟悉的 $listeners 属性，却发现它已被移除。实际上，Vue 3 并未削弱事件传递能力，而是通过更智能、更简洁的内置机制重新设计了这一功能。事件透传在 Vue 3 中变得更加直观和自动化，在多数情况下你甚至无需进行任何额外编码。本文将深入解析 Vue 3 事件透传的原理与最佳实践，帮助你彻底掌握这一核心特性。

理解 Vue 3 事件自动透传机制

我们先从最常见也最省心的场景开始。当一个组件的根元素是原生 HTML 标签（例如

、 或 ），并且组件内部使用了插槽时，父组件在该组件上绑定的所有事件监听器，都会自动被附加到根元素上。这个过程完全由 Vue 运行时处理，无需手动干预。

通过一个基础的按钮组件示例可以清晰地看到这一点：

父组件（调用方）：

保存数据

子组件定义（MyCustomButton.vue）：

✅ 在这个例子中，父组件绑定的 click 和 mouseenter 事件会自动透传至子组件内部的

元素。用户与之交互时，父组件定义的方法会被正常触发。这种隐式的、符合直觉的透传方式，极大地提升了基础组件的开发效率与使用体验。

如何进行显式的手动事件透传

当然，自动透传并非适用于所有情况。当你的组件根节点是另一个 Vue 组件，或者你需要精确控制事件的流向（例如仅透传部分事件、阻止默认行为或向特定子元素传递事件）时，就需要使用 Vue 3 提供的显式透传工具：$attrs 对象。

在 Vue 3 的架构中，所有未被组件的 props 或 emits 选项显式声明的属性（Attributes）和事件监听器（Event Listeners），都会被集中收集到 $attrs 中。这意味着你可以像传递普通属性一样，灵活地手动传递事件。

以下是几种典型的应用场景与对应写法：

• 透传所有未被声明的属性与事件：
• 透传所有属性与事件，并合并新属性：
• 选择性透传特定事件：例如，只希望传递 click 和 focus 事件，可以采用对象语法：

⚠️ 请注意一个重要的命名转换规则：在 $attrs 对象中，事件监听器对应的键名会以 “on” 为前缀，并采用驼峰式命名法。例如，模板中写的 @click 对应 $attrs.onClick，@input 对应 $attrs.onInput。自定义事件遵循相同规则，如 @update:model-value 会转换为 $attrs['onUpdate:model-value']。

分离处理原生事件与自定义事件

在处理复杂组件时，我们常常需要区分对待原生 DOM 事件和自定义业务事件。例如，一个封装了输入框的组件，可能希望将 @click 直接绑定到内部的按钮上，而将 @change 这样的业务事件交由组件内部逻辑处理后再向上传递。

此时，可以在