Vue - @ 事件指南：原生 / 内置 / 自定义事件全解析

前言

在 Vue 开发中，@ 是 v-on 指令的简写，是绑定事件监听的核心语法。很多新手容易混淆不同类型的 @ 事件用法，本文整理了 Vue 中所有常用的 @ 事件类型，包括原生 DOM 事件、内置组件事件、自定义事件，以及提升开发效率的事件修饰符，看完就能直接上手用！

一、 Vue @ 事件的核心分类

Vue 中的 @ 事件本质是对 DOM 事件 / 组件事件的封装，核心分为三大类：

• 原生 DOM 事件：浏览器自带的基础交互事件
• Vue 内置组件事件：Vue 官方组件专属的状态监听事件
• 自定义事件：组件间通信的核心自定义事件

二、原生 DOM 事件

这类事件是浏览器原生支持的 DOM 事件，Vue 可直接通过 @ 绑定，覆盖绝大部分交互场景，按类型整理如下：

1. 鼠标事件

事件语法	说明	常用场景
@click	点击事件（最常用）	按钮点击、卡片跳转
@dblclick	双击事件	列表项编辑、文件重命名
@mouseenter	鼠标进入（不冒泡）	悬浮提示、菜单展开
@mouseleave	鼠标离开（不冒泡）	悬浮提示隐藏、菜单收起
@mousemove	鼠标移动	拖拽跟随、坐标监听
@mousedown	鼠标按下	拖拽开始、按住触发
@mouseup	鼠标松开	拖拽结束、松开停止
@contextmenu	右键菜单事件	自定义右键菜单

2. 键盘事件

事件语法	说明	注意点
@keydown	键盘按下时触发	可监听组合键（如 @keydown.ctrl.s）
@keyup	键盘松开时触发	常用 @keyup.enter 监听回车
@keypress	键盘按压时触发	已逐步废弃，推荐用 keydown 替代

3. 表单事件

事件语法	说明	触发时机对比
@input	输入框内容变化	实时触发（每输入一个字符都触发）
@change	表单值变化	失去焦点 / 选择完成后触发（如下拉框选值）
@submit	表单提交事件	点击提交按钮 / 按回车触发
@focus	元素获取焦点	输入框激活、下拉框展开
@blur	元素失去焦点	输入框失活、表单校验

4. 移动端触摸事件

事件语法	说明	适用场景
@touchstart	触摸开始	移动端点击、滑动开始
@touchend	触摸结束	移动端点击完成、滑动结束

5. 页面 / 窗口事件

事件语法	说明	优化建议
@scroll	滚动事件	监听页面滚动加载、导航栏吸顶
@resize	窗口大小变化	响应式布局适配、画布重绘

6.使用示例

<template>
  <div>
    <!-- 点击事件 -->
    <button @click="handleClick">普通点击</button>
    <!-- 键盘事件（监听回车） -->
    <input @keyup.enter="handleSearch" placeholder="按回车搜索" />
    <!-- 表单输入事件 -->
    <input @input="handleInput" @blur="handleBlur" placeholder="实时输入监听" />
  </div>
</template>

<script setup>
const handleClick = () => console.log('按钮被点击');
const handleSearch = () => console.log('执行搜索');
const handleInput = (e) => console.log('实时输入：', e.target.value);
const handleBlur = () => console.log('输入框失活，可做校验');
</script>

---

三、 Vue 内置组件事件：监听生命周期

Vue 的内置组件（如动画、路由）拥有自己独特的"生命周期事件"，让我们能精准控制交互细节。

内置组件	常用事件	触发时机
<transition>	@before-enter / @enter	进入动画开始前与执行中
	@after-enter	动画完全结束，常用于清理工作
	@leave / @after-leave	离开动画的相关节点
<router-link>	@click	点击跳转（Vue Router 内部处理）
	@navigate	(Vue Router 4+) 导航正式开始时触发

---

四、 自定义事件：父子通信核心

自定义事件是 Vue 父子组件通信的重要方式，子组件通过 emit 触发事件，父组件通过 @ 监听事件并接收参数。

1. 子组件触发 ：使用 emit 抛出事件和数据。

2. 父组件监听 ：通过 @ 绑定回调。

<!-- 子组件 Child.vue -->
<template>
  <button @click="sendData">向父组件传值</button>
</template>

<script setup>
  // 定义可触发的自定义事件
  const emit = defineEmits(['custom-event']);

  const sendData = () => {
    // 触发事件并传递参数
    emit('custom-event', { name: 'Vue', version: '3.x' });
  };
</script>

<!-- 父组件 Parent.vue -->
<template>
  <!-- 监听子组件自定义事件 -->
  <Child @custom-event="handleCustomEvent" />
</template>

<script setup>
  import Child from './Child.vue';

  const handleCustomEvent = (data) => {
    console.log('接收子组件数据：', data); // 输出：{ name: 'Vue', version: '3.x' }
  };
</script>

---

五、 扩展：事件修饰符

Vue 提供事件修饰符简化事件处理逻辑，无需手动调用 e.preventDefault()/e.stopPropagation()，常用修饰符如下：

1. 流程控制

• .stop：阻止冒泡 。相当于 e.stopPropagation()。
• .prevent：阻止默认行为 。常用于 <a> 标签和 <form> 提交。
• .capture：使用捕获模式触发事件。

2. 触发频率与性能

• .once：只触发一次。之后再点击将失效。

• .passive：提升性能（移动端必用） 。

3. 按键与鼠标修饰符

• .enter / .esc / .space：特定按键触发。
• .left / .right / .middle：限制特定的鼠标按键。