Vue3 事件修饰符深度解析：从基础到高级应用的完整指南

摘要

事件修饰符是 Vue.js 中一个强大而优雅的特性，它允许我们以声明式的方式处理 DOM 事件细节。Vue3 在保留所有 Vue2 事件修饰符的基础上，还引入了一些新的修饰符。本文将深入探讨所有事件修饰符的工作原理、使用场景和最佳实践，通过详细的代码示例、执行流程分析和实际应用案例，帮助你彻底掌握 Vue3 事件修饰符的完整知识体系。

---

一、 什么是事件修饰符？为什么需要它？

1.1 传统事件处理的问题

在原生 JavaScript 中处理事件时，我们经常需要编写重复的样板代码：

// 原生 JavaScript 事件处理
element.addEventListener('click', function(event) {
  // 阻止默认行为
  event.preventDefault()
  
  // 停止事件传播
  event.stopPropagation()
  
  // 执行业务逻辑
  handleClick()
})

传统方式的问题：

• 代码冗余 ：每个事件处理函数都需要重复调用 preventDefault() 和 stopPropagation()
• 关注点混合：事件处理逻辑与 DOM 操作细节混合在一起
• 可读性差：代码意图不够清晰明确
• 维护困难：修改事件行为需要深入函数内部

1.2 Vue 事件修饰符的解决方案

Vue 的事件修饰符提供了一种声明式的解决方案：

<template>
  <!-- 使用事件修饰符 -->
  <a @click.prevent.stop="handleClick" href="/about">关于我们</a>
</template>

事件修饰符的优势：

• 代码简洁：以声明式的方式表达事件行为
• 关注点分离：业务逻辑与 DOM 细节分离
• 可读性强：代码意图一目了然
• 维护方便：修改事件行为只需改动模板

---

二、 Vue3 事件修饰符完整列表

2.1 事件修饰符分类总览

类别	修饰符	说明	Vue2	Vue3
事件传播	.stop	阻止事件冒泡	✅	✅
	.capture	使用捕获模式	✅	✅
	.self	仅当事件源是自身时触发	✅	✅
	.once	只触发一次	✅	✅
	.passive	不阻止默认行为	✅	✅
默认行为	.prevent	阻止默认行为	✅	✅
按键修饰	.enter	Enter 键	✅	✅
	.tab	Tab 键	✅	✅
	.delete	删除键	✅	✅
	.esc	Esc 键	✅	✅
	.space	空格键	✅	✅
	.up	上箭头	✅	✅
	.down	下箭头	✅	✅
	.left	左箭头	✅	✅
	.right	右箭头	✅	✅
系统修饰	.ctrl	Ctrl 键	✅	✅
	.alt	Alt 键	✅	✅
	.shift	Shift 键	✅	✅
	.meta	Meta 键	✅	✅
	.exact	精确匹配系统修饰符	✅	✅
鼠标修饰	.left	鼠标左键	✅	✅
	.right	鼠标右键	✅	✅
	.middle	鼠标中键	✅	✅
Vue3 新增	.vue	自定义事件专用	❌	✅

---

三、 事件传播修饰符详解

3.1 事件传播的基本概念

流程图：DOM 事件传播机制

flowchart TD A[事件发生] --> B[捕获阶段 Capture Phase] B --> C[从window向下传递到目标] C --> D[目标阶段 Target Phase] D --> E[到达事件目标元素] E --> F[冒泡阶段 Bubble Phase] F --> G[从目标向上传递到window] B --> H[.capture 在此阶段触发] D --> I[.self 检查事件源] F --> J[.stop 阻止继续冒泡]

3.2 .stop - 阻止事件冒泡

<template>
  <div class="stop-modifier-demo">
    <h2>.stop 修饰符 - 阻止事件冒泡</h2>
    
    <div class="demo-area">
      <!-- 外层容器 -->
      <div class="outer-box" @click="handleOuterClick">
        <p>外层容器 (点击我会触发)</p>
        
        <!-- 内层容器 - 不使用 .stop -->
        <div class="inner-box" @click="handleInnerClick">
          <p>内层容器 - 无 .stop (点击我会触发内外两层)</p>
        </div>
        
        <!-- 内层容器 - 使用 .stop -->
        <div class="inner-box stop-demo" @click.stop="handleInnerClickStop">
          <p>内层容器 - 有 .stop (点击我只触发内层)</p>
        </div>
      </div>
    </div>

    <div class="event-logs">
      <h3>事件触发日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 10) {
    logs.value.pop()
  }
}

const handleOuterClick = (event) => {
  addLog('🟢 外层容器被点击')
  console.log('外层点击事件:', event)
}

const handleInnerClick = (event) => {
  addLog('🔵 内层容器被点击 (无.stop - 会冒泡)')
  console.log('内层点击事件 (无.stop):', event)
}

const handleInnerClickStop = (event) => {
  addLog('🔴 内层容器被点击 (有.stop - 阻止冒泡)')
  console.log('内层点击事件 (有.stop):', event)
}
</script>

<style scoped>
.stop-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.demo-area {
  margin: 20px 0;
}

.outer-box {
  padding: 30px;
  background: #e3f2fd;
  border: 2px solid #2196f3;
  border-radius: 8px;
  cursor: pointer;
  transition: background 0.3s;
}

.outer-box:hover {
  background: #bbdefb;
}

.outer-box p {
  margin: 0 0 15px 0;
  font-weight: bold;
  color: #1976d2;
}

.inner-box {
  padding: 20px;
  margin: 15px 0;
  background: #f3e5f5;
  border: 2px solid #9c27b0;
  border-radius: 6px;
  cursor: pointer;
  transition: background 0.3s;
}

.inner-box:hover {
  background: #e1bee7;
}

.inner-box p {
  margin: 0;
  color: #7b1fa2;
}

.stop-demo {
  background: #fff3e0;
  border-color: #ff9800;
}

.stop-demo p {
  color: #ef6c00;
}

.event-logs {
  margin-top: 30px;
  padding: 20px;
  background: #f5f5f5;
  border-radius: 8px;
}

.event-logs h3 {
  margin: 0 0 15px 0;
  color: #333;
}

.log-item {
  padding: 8px 12px;
  margin: 5px 0;
  background: white;
  border-radius: 4px;
  border-left: 4px solid #4caf50;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

3.3 .capture - 使用事件捕获模式

<template>
  <div class="capture-modifier-demo">
    <h2>.capture 修饰符 - 事件捕获模式</h2>
    
    <div class="demo-area">
      <!-- 捕获阶段触发 -->
      <div class="capture-box" @click.capture="handleCaptureClick">
        <p>捕获阶段容器 (使用 .capture)</p>
        
        <div class="target-box" @click="handleTargetClick">
          <p>目标元素 (正常冒泡阶段)</p>
        </div>
      </div>
    </div>

    <div class="explanation">
      <h3>执行顺序说明:</h3>
      <ol>
        <li>点击目标元素时，首先触发 <strong>.capture</strong> 阶段的事件</li>
        <li>然后触发目标元素自身的事件</li>
        <li>最后是冒泡阶段的事件 (本例中没有)</li>
      </ol>
    </div>

    <div class="event-logs">
      <h3>事件触发顺序:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
}

const handleCaptureClick = () => {
  addLog('1️⃣ 捕获阶段: 外层容器 (.capture)')
}

const handleTargetClick = () => {
  addLog('2️⃣ 目标阶段: 内层元素 (正常)')
}
</script>

<style scoped>
.capture-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.capture-box {
  padding: 30px;
  background: #fff3e0;
  border: 2px dashed #ff9800;
  border-radius: 8px;
}

.capture-box p {
  margin: 0 0 15px 0;
  color: #ef6c00;
  font-weight: bold;
}

.target-box {
  padding: 20px;
  background: #e8f5e8;
  border: 2px solid #4caf50;
  border-radius: 6px;
  cursor: pointer;
  transition: background 0.3s;
}

.target-box:hover {
  background: #c8e6c9;
}

.target-box p {
  margin: 0;
  color: #2e7d32;
}

.explanation {
  margin: 20px 0;
  padding: 20px;
  background: #e3f2fd;
  border-radius: 8px;
}

.explanation h3 {
  margin: 0 0 10px 0;
  color: #1976d2;
}

.explanation ol {
  margin: 0;
  color: #333;
}

.log-item {
  padding: 8px 12px;
  margin: 5px 0;
  background: white;
  border-radius: 4px;
  border-left: 4px solid #ff9800;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

3.4 .self - 仅当事件源是自身时触发

<template>
  <div class="self-modifier-demo">
    <h2>.self 修饰符 - 仅自身触发</h2>
    
    <div class="demo-area">
      <!-- 不使用 .self -->
      <div class="container" @click="handleContainerClick">
        <p>普通容器 (点击子元素也会触发)</p>
        <button class="child-btn">子元素按钮</button>
      </div>
      
      <!-- 使用 .self -->
      <div class="container self-demo" @click.self="handleContainerSelfClick">
        <p>.self 容器 (只有点击容器本身才触发)</p>
        <button class="child-btn">子元素按钮</button>
      </div>
    </div>

    <div class="event-logs">
      <h3>事件触发日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 8) {
    logs.value.pop()
  }
}

const handleContainerClick = (event) => {
  addLog(`🔵 容器被点击 (target: ${event.target.tagName})`)
}

const handleContainerSelfClick = (event) => {
  addLog(`🔴 .self 容器被点击 (只有点击容器本身才触发)`)
}
</script>

<style scoped>
.self-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.demo-area {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 20px;
  margin: 20px 0;
}

.container {
  padding: 25px;
  border: 2px solid #666;
  border-radius: 8px;
  cursor: pointer;
  transition: background 0.3s;
  min-height: 120px;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}

.container:hover {
  background: #f5f5f5;
}

.container p {
  margin: 0 0 15px 0;
  font-weight: bold;
  text-align: center;
}

.self-demo {
  border-color: #e91e63;
  background: #fce4ec;
}

.self-demo:hover {
  background: #f8bbd9;
}

.child-btn {
  padding: 8px 16px;
  background: #2196f3;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.child-btn:hover {
  background: #1976d2;
}

.event-logs {
  margin-top: 30px;
  padding: 20px;
  background: #f5f5f5;
  border-radius: 8px;
}
</style>

3.5 .once - 只触发一次

<template>
  <div class="once-modifier-demo">
    <h2>.once 修饰符 - 只触发一次</h2>
    
    <div class="demo-area">
      <div class="button-group">
        <button @click="handleNormalClick" class="btn">
          普通按钮 (可重复点击)
        </button>
        <button @click.once="handleOnceClick" class="btn once-btn">
          .once 按钮 (只触发一次)
        </button>
      </div>
      
      <div class="counter-display">
        <div class="counter">
          <span>普通点击: </span>
          <strong>{{ normalCount }}</strong>
        </div>
        <div class="counter">
          <span>Once 点击: </span>
          <strong>{{ onceCount }}</strong>
        </div>
      </div>
    </div>

    <div class="event-logs">
      <h3>事件触发日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const normalCount = ref(0)
const onceCount = ref(0)
const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 6) {
    logs.value.pop()
  }
}

const handleNormalClick = () => {
  normalCount.value++
  addLog(`🔵 普通按钮点击: ${normalCount.value}`)
}

const handleOnceClick = () => {
  onceCount.value++
  addLog(`🔴 ONCE 按钮点击: ${onceCount.value} (只会显示一次!)`)
}
</script>

<style scoped>
.once-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.button-group {
  display: flex;
  gap: 20px;
  justify-content: center;
  margin: 30px 0;
}

.btn {
  padding: 12px 24px;
  border: none;
  border-radius: 6px;
  cursor: pointer;
  font-size: 16px;
  transition: all 0.3s;
}

.btn:first-child {
  background: #2196f3;
  color: white;
}

.btn:first-child:hover {
  background: #1976d2;
  transform: translateY(-2px);
}

.once-btn {
  background: #ff9800;
  color: white;
}

.once-btn:hover {
  background: #f57c00;
  transform: translateY(-2px);
}

.counter-display {
  display: flex;
  justify-content: center;
  gap: 40px;
  margin: 20px 0;
}

.counter {
  padding: 15px 25px;
  background: white;
  border: 2px solid #e0e0e0;
  border-radius: 8px;
  text-align: center;
  min-width: 150px;
}

.counter span {
  display: block;
  color: #666;
  margin-bottom: 5px;
}

.counter strong {
  font-size: 24px;
  color: #333;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: white;
  border-radius: 4px;
  border-left: 4px solid #2196f3;
  font-family: 'Courier New', monospace;
}

.log-item:contains('ONCE') {
  border-left-color: #ff9800;
}
</style>

3.6 .passive - 不阻止默认行为

<template>
  <div class="passive-modifier-demo">
    <h2>.passive 修饰符 - 不阻止默认行为</h2>
    
    <div class="demo-area">
      <div class="scroll-container">
        <div class="scroll-content">
          <div v-for="n in 50" :key="n" class="scroll-item">
            项目 {{ n }}
          </div>
        </div>
      </div>
      
      <div class="control-info">
        <p>尝试滚动上面的区域，观察控制台输出：</p>
        <ul>
          <li>使用 <code>.passive</code> 的事件处理函数不会调用 <code>preventDefault()</code></li>
          <li>这可以提升滚动性能，特别是移动端</li>
        </ul>
      </div>
    </div>

    <div class="performance-metrics">
      <h3>性能指标:</h3>
      <div class="metrics">
        <div class="metric">
          <span>滚动事件触发次数:</span>
          <strong>{{ scrollCount }}</strong>
        </div>
        <div class="metric">
          <span>阻塞时间:</span>
          <strong>{{ blockTime }}ms</strong>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'

const scrollCount = ref(0)
const blockTime = ref(0)

onMounted(() => {
  const scrollContainer = document.querySelector('.scroll-container')
  
  // 模拟阻塞操作
  const heavyOperation = () => {
    const start = performance.now()
    let result = 0
    for (let i = 0; i < 1000000; i++) {
      result += Math.random()
    }
    const end = performance.now()
    blockTime.value = (end - start).toFixed(2)
    return result
  }
  
  // 添加 passive 事件监听器
  scrollContainer.addEventListener('scroll', (event) => {
    scrollCount.value++
    heavyOperation()
    console.log('passive 滚动事件 - 不会阻止默认行为')
  }, { passive: true })
})
</script>

<style scoped>
.passive-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.scroll-container {
  height: 200px;
  border: 2px solid #ddd;
  border-radius: 8px;
  overflow-y: scroll;
  margin: 20px 0;
}

.scroll-content {
  padding: 10px;
}

.scroll-item {
  padding: 15px;
  margin: 5px 0;
  background: #f5f5f5;
  border-radius: 4px;
  border-left: 4px solid #4caf50;
}

.control-info {
  padding: 20px;
  background: #e3f2fd;
  border-radius: 8px;
  margin: 20px 0;
}

.control-info p {
  margin: 0 0 10px 0;
  font-weight: bold;
}

.control-info ul {
  margin: 0;
  color: #333;
}

.control-info code {
  background: #fff;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Courier New', monospace;
}

.performance-metrics {
  padding: 20px;
  background: #fff3e0;
  border-radius: 8px;
}

.performance-metrics h3 {
  margin: 0 0 15px 0;
  color: #e65100;
}

.metrics {
  display: flex;
  gap: 30px;
}

.metric {
  display: flex;
  flex-direction: column;
  align-items: center;
}

.metric span {
  color: #666;
  margin-bottom: 5px;
}

.metric strong {
  font-size: 24px;
  color: #e65100;
}
</style>

---

四、 默认行为修饰符

4.1 .prevent - 阻止默认行为

<template>
  <div class="prevent-modifier-demo">
    <h2>.prevent 修饰符 - 阻止默认行为</h2>
    
    <div class="demo-area">
      <div class="form-group">
        <h3>表单提交示例</h3>
        <form @submit="handleFormSubmit" class="prevent-form">
          <input v-model="username" placeholder="请输入用户名" class="form-input" />
          <button type="submit" class="btn">普通提交</button>
          <button type="submit" @click.prevent="handlePreventSubmit" class="btn prevent-btn">
            使用 .prevent
          </button>
        </form>
      </div>
      
      <div class="link-group">
        <h3>链接点击示例</h3>
        <a href="https://vuejs.org" @click="handleLinkClick" class="link">
          普通链接 (会跳转)
        </a>
        <a href="https://vuejs.org" @click.prevent="handlePreventLinkClick" class="link prevent-link">
          使用 .prevent (不会跳转)
        </a>
      </div>
    </div>

    <div class="event-logs">
      <h3>事件触发日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const username = ref('')
const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 8) {
    logs.value.pop()
  }
}

const handleFormSubmit = (event) => {
  addLog('📝 表单提交 (页面会刷新)')
  // 这里可以添加表单验证等逻辑
}

const handlePreventSubmit = () => {
  addLog('🛑 表单提交 (使用 .prevent，页面不会刷新)')
  // 在这里处理 AJAX 提交等逻辑
  if (username.value) {
    addLog(`✅ 提交用户名: ${username.value}`)
  }
}

const handleLinkClick = () => {
  addLog('🔗 链接点击 (会跳转到 Vue.js 官网)')
}

const handlePreventLinkClick = () => {
  addLog('🚫 链接点击 (使用 .prevent，不会跳转)')
  // 可以在这里处理路由跳转等逻辑
}
</script>

<style scoped>
.prevent-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.form-group, .link-group {
  margin: 30px 0;
  padding: 25px;
  background: #f8f9fa;
  border-radius: 8px;
}

.form-group h3, .link-group h3 {
  margin: 0 0 15px 0;
  color: #333;
}

.prevent-form {
  display: flex;
  gap: 10px;
  align-items: center;
  flex-wrap: wrap;
}

.form-input {
  padding: 10px;
  border: 1px solid #ddd;
  border-radius: 4px;
  flex: 1;
  min-width: 200px;
}

.btn {
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  font-size: 14px;
}

.btn:first-of-type {
  background: #2196f3;
  color: white;
}

.prevent-btn {
  background: #ff5722;
  color: white;
}

.btn:hover {
  opacity: 0.9;
}

.link-group {
  display: flex;
  flex-direction: column;
  gap: 15px;
}

.link {
  padding: 12px 20px;
  background: #e3f2fd;
  border: 1px solid #2196f3;
  border-radius: 4px;
  text-decoration: none;
  color: #1976d2;
  text-align: center;
  transition: background 0.3s;
}

.prevent-link {
  background: #ffebee;
  border-color: #f44336;
  color: #d32f2f;
}

.link:hover {
  background: #bbdefb;
}

.prevent-link:hover {
  background: #ffcdd2;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: white;
  border-radius: 4px;
  border-left: 4px solid #2196f3;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

---

五、 按键修饰符详解

5.1 常用按键修饰符

<template>
  <div class="key-modifier-demo">
    <h2>按键修饰符 - 键盘事件处理</h2>
    
    <div class="demo-area">
      <div class="input-group">
        <h3>输入框按键事件</h3>
        <input 
          v-model="inputText"
          @keyup.enter="handleEnter"
          @keyup.tab="handleTab"
          @keyup.delete="handleDelete"
          @keyup.esc="handleEsc"
          @keyup.space="handleSpace"
          placeholder="尝试按 Enter、Tab、Delete、Esc、Space 键"
          class="key-input"
        />
      </div>
      
      <div class="arrow-group">
        <h3>方向键控制</h3>
        <div class="arrow-controls">
          <div class="arrow-row">
            <button @keyup.up="handleUp" class="arrow-btn up">↑</button>
          </div>
          <div class="arrow-row">
            <button @keyup.left="handleLeft" class="arrow-btn left">←</button>
            <button @keyup.down="handleDown" class="arrow-btn down">↓</button>
            <button @keyup.right="handleRight" class="arrow-btn right">→</button>
          </div>
        </div>
        <p>点击按钮后按方向键测试</p>
      </div>
    </div>

    <div class="key-logs">
      <h3>按键事件日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const inputText = ref('')
const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 10) {
    logs.value.pop()
  }
}

const handleEnter = (event) => {
  addLog('↵ Enter 键被按下')
  if (inputText.value.trim()) {
    addLog(`💾 保存内容: "${inputText.value}"`)
    inputText.value = ''
  }
}

const handleTab = () => {
  addLog('↹ Tab 键被按下')
}

const handleDelete = () => {
  addLog('⌫ Delete 键被按下')
}

const handleEsc = () => {
  addLog('⎋ Esc 键被按下 - 取消操作')
  inputText.value = ''
}

const handleSpace = () => {
  addLog('␣ Space 键被按下')
}

const handleUp = () => {
  addLog('↑ 上方向键 - 向上移动')
}

const handleDown = () => {
  addLog('↓ 下方向键 - 向下移动')
}

const handleLeft = () => {
  addLog('← 左方向键 - 向左移动')
}

const handleRight = () => {
  addLog('→ 右方向键 - 向右移动')
}
</script>

<style scoped>
.key-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.input-group, .arrow-group {
  margin: 30px 0;
  padding: 25px;
  background: #f8f9fa;
  border-radius: 8px;
}

.input-group h3, .arrow-group h3 {
  margin: 0 0 15px 0;
  color: #333;
}

.key-input {
  width: 100%;
  padding: 12px;
  border: 2px solid #ddd;
  border-radius: 6px;
  font-size: 16px;
  transition: border-color 0.3s;
}

.key-input:focus {
  outline: none;
  border-color: #2196f3;
}

.arrow-controls {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 10px;
}

.arrow-row {
  display: flex;
  gap: 10px;
  justify-content: center;
}

.arrow-btn {
  width: 60px;
  height: 60px;
  border: 2px solid #666;
  border-radius: 8px;
  background: white;
  font-size: 20px;
  cursor: pointer;
  transition: all 0.3s;
  display: flex;
  align-items: center;
  justify-content: center;
}

.arrow-btn:focus {
  outline: none;
  background: #e3f2fd;
  border-color: #2196f3;
}

.arrow-btn:hover {
  transform: scale(1.1);
}

.up { border-color: #4caf50; color: #4caf50; }
.down { border-color: #2196f3; color: #2196f3; }
.left { border-color: #ff9800; color: #ff9800; }
.right { border-color: #9c27b0; color: #9c27b0; }

.arrow-group p {
  text-align: center;
  margin: 15px 0 0 0;
  color: #666;
  font-style: italic;
}

.key-logs {
  margin-top: 30px;
  padding: 20px;
  background: #2c3e50;
  border-radius: 8px;
  color: white;
}

.key-logs h3 {
  margin: 0 0 15px 0;
  color: #42b883;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: #34495e;
  border-radius: 4px;
  border-left: 4px solid #42b883;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

5.2 系统修饰符

<template>
  <div class="system-modifier-demo">
    <h2>系统修饰符 - 组合键处理</h2>
    
    <div class="demo-area">
      <div class="modifier-group">
        <h3>系统修饰符测试</h3>
        <div class="key-combinations">
          <div class="key-item" @click.ctrl="handleCtrlClick">
            Ctrl + 点击
          </div>
          <div class="key-item" @click.alt="handleAltClick">
            Alt + 点击
          </div>
          <div class="key-item" @click.shift="handleShiftClick">
            Shift + 点击
          </div>
          <div class="key-item" @click.meta="handleMetaClick">
            Meta (Cmd) + 点击
          </div>
        </div>
      </div>
      
      <div class="exact-modifier">
        <h3>.exact 修饰符 - 精确匹配</h3>
        <div class="exact-combinations">
          <button @click="handleAnyClick" class="exact-btn">
            任意点击
          </button>
          <button @click.ctrl="handleCtrlOnlyClick" class="exact-btn">
            Ctrl + 点击
          </button>
          <button @click.ctrl.exact="handleExactCtrlClick" class="exact-btn exact">
            .exact Ctrl (仅 Ctrl)
          </button>
        </div>
      </div>
    </div>

    <div class="system-logs">
      <h3>系统修饰符事件日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 8) {
    logs.value.pop()
  }
}

const handleCtrlClick = () => {
  addLog('🎛️ Ctrl + 点击')
}

const handleAltClick = () => {
  addLog('⎇ Alt + 点击')
}

const handleShiftClick = () => {
  addLog('⇧ Shift + 点击')
}

const handleMetaClick = () => {
  addLog('⌘ Meta (Cmd) + 点击')
}

const handleAnyClick = () => {
  addLog('🔄 任意点击 (无修饰符)')
}

const handleCtrlOnlyClick = () => {
  addLog('🎛️ Ctrl + 点击 (可能包含其他修饰符)')
}

const handleExactCtrlClick = () => {
  addLog('🎛️ .exact Ctrl + 点击 (仅 Ctrl，无其他修饰符)')
}
</script>

<style scoped>
.system-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.modifier-group, .exact-modifier {
  margin: 30px 0;
  padding: 25px;
  background: #f8f9fa;
  border-radius: 8px;
}

.modifier-group h3, .exact-modifier h3 {
  margin: 0 0 15px 0;
  color: #333;
}

.key-combinations {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
  gap: 15px;
}

.key-item {
  padding: 20px;
  background: white;
  border: 2px solid #e0e0e0;
  border-radius: 8px;
  text-align: center;
  cursor: pointer;
  transition: all 0.3s;
  font-weight: bold;
}

.key-item:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
}

.key-item:nth-child(1) { border-color: #2196f3; color: #2196f3; }
.key-item:nth-child(2) { border-color: #ff9800; color: #ff9800; }
.key-item:nth-child(3) { border-color: #4caf50; color: #4caf50; }
.key-item:nth-child(4) { border-color: #9c27b0; color: #9c27b0; }

.exact-combinations {
  display: flex;
  gap: 15px;
  flex-wrap: wrap;
}

.exact-btn {
  padding: 12px 20px;
  border: 2px solid #666;
  border-radius: 6px;
  background: white;
  cursor: pointer;
  font-size: 14px;
  transition: all 0.3s;
}

.exact-btn:hover {
  background: #f5f5f5;
}

.exact-btn.exact {
  border-color: #e91e63;
  color: #e91e63;
  font-weight: bold;
}

.system-logs {
  margin-top: 30px;
  padding: 20px;
  background: #2c3e50;
  border-radius: 8px;
  color: white;
}

.system-logs h3 {
  margin: 0 0 15px 0;
  color: #42b883;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: #34495e;
  border-radius: 4px;
  border-left: 4px solid #42b883;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

---

六、 鼠标按键修饰符

6.1 鼠标按键修饰符使用

<template>
  <div class="mouse-modifier-demo">
    <h2>鼠标按键修饰符</h2>
    
    <div class="demo-area">
      <div class="mouse-test-area">
        <div 
          class="click-zone"
          @click.left="handleLeftClick"
          @click.middle="handleMiddleClick"
          @click.right="handleRightClick"
        >
          <p>在此区域测试鼠标按键：</p>
          <ul>
            <li>左键点击 - 正常点击</li>
            <li>中键点击 - 鼠标滚轮点击</li>
            <li>右键点击 - 弹出上下文菜单</li>
          </ul>
        </div>
      </div>
      
      <div class="context-menu-info">
        <p><strong>注意：</strong>右键点击时，使用 <code>.prevent</code> 可以阻止浏览器默认的上下文菜单：</p>
        <div 
          class="prevent-context-zone"
          @click.right.prevent="handlePreventRightClick"
        >
          右键点击这里不会显示浏览器菜单
        </div>
      </div>
    </div>

    <div class="mouse-logs">
      <h3>鼠标事件日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 6) {
    logs.value.pop()
  }
}

const handleLeftClick = () => {
  addLog('🖱️ 鼠标左键点击')
}

const handleMiddleClick = () => {
  addLog('🎯 鼠标中键点击')
}

const handleRightClick = (event) => {
  addLog('📋 鼠标右键点击 (会显示浏览器上下文菜单)')
}

const handlePreventRightClick = () => {
  addLog('🚫 鼠标右键点击 (使用 .prevent，不显示浏览器菜单)')
  // 可以在这里显示自定义上下文菜单
}
</script>

<style scoped>
.mouse-modifier-demo {
  padding: 20px;
  max-width: 800px;
  margin: 0 auto;
}

.mouse-test-area {
  margin: 30px 0;
  padding: 25px;
  background: #f8f9fa;
  border-radius: 8px;
}

.click-zone {
  padding: 40px;
  background: white;
  border: 3px dashed #2196f3;
  border-radius: 8px;
  text-align: center;
  cursor: pointer;
  transition: background 0.3s;
}

.click-zone:hover {
  background: #e3f2fd;
}

.click-zone p {
  margin: 0 0 15px 0;
  font-weight: bold;
  color: #1976d2;
}

.click-zone ul {
  text-align: left;
  display: inline-block;
  margin: 0;
  color: #333;
}

.click-zone li {
  margin: 8px 0;
}

.context-menu-info {
  margin: 30px 0;
  padding: 25px;
  background: #fff3e0;
  border-radius: 8px;
}

.context-menu-info p {
  margin: 0 0 15px 0;
  color: #e65100;
}

.prevent-context-zone {
  padding: 20px;
  background: #ffebee;
  border: 2px solid #f44336;
  border-radius: 6px;
  text-align: center;
  cursor: pointer;
  font-weight: bold;
  color: #d32f2f;
}

.mouse-logs {
  margin-top: 30px;
  padding: 20px;
  background: #2c3e50;
  border-radius: 8px;
  color: white;
}

.mouse-logs h3 {
  margin: 0 0 15px 0;
  color: #42b883;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: #34495e;
  border-radius: 4px;
  border-left: 4px solid #42b883;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

---

七、 事件修饰符的组合使用

7.1 修饰符链式调用

<template>
  <div class="combined-modifier-demo">
    <h2>事件修饰符组合使用</h2>
    
    <div class="demo-area">
      <div class="combination-examples">
        <div class="example">
          <h3>1. 阻止冒泡 + 阻止默认行为</h3>
          <a 
            href="#"
            @click.prevent.stop="handlePreventStop"
            class="combined-link"
          >
            @click.prevent.stop
          </a>
          <p>既阻止链接跳转，又阻止事件冒泡</p>
        </div>
        
        <div class="example">
          <h3>2. 捕获阶段 + 只触发一次</h3>
          <div 
            @click.capture.once="handleCaptureOnce"
            class="capture-once-box"
          >
            @click.capture.once
            <button>内部按钮</button>
          </div>
          <p>在捕获阶段触发，且只触发一次</p>
        </div>
        
        <div class="example">
          <h3>3. 精确组合键 + 阻止默认</h3>
          <button 
            @keydown.ctrl.exact.prevent="handleExactCtrlPrevent"
            class="exact-ctrl-btn"
          >
            聚焦后按 Ctrl (精确)
          </button>
          <p>精确匹配 Ctrl 键，阻止默认行为</p>
        </div>
        
        <div class="example">
          <h3>4. 自身检查 + 阻止冒泡</h3>
          <div 
            @click.self.stop="handleSelfStop"
            class="self-stop-box"
          >
            @click.self.stop
            <button>点击按钮不会触发</button>
          </div>
          <p>只有点击容器本身才触发，并阻止冒泡</p>
        </div>
      </div>
    </div>

    <div class="combination-logs">
      <h3>组合修饰符事件日志:</h3>
      <div v-for="(log, index) in logs" :key="index" class="log-item">
        {{ log }}
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref } from 'vue'

const logs = ref([])

const addLog = (message) => {
  const timestamp = new Date().toLocaleTimeString()
  logs.value.unshift(`[${timestamp}] ${message}`)
  if (logs.value.length > 8) {
    logs.value.pop()
  }
}

const handlePreventStop = () => {
  addLog('🔗 prevent.stop: 阻止跳转和冒泡')
}

const handleCaptureOnce = () => {
  addLog('🎯 capture.once: 捕获阶段触发，只触发一次')
}

const handleExactCtrlPrevent = (event) => {
  addLog('⌨️ ctrl.exact.prevent: 精确 Ctrl，阻止默认行为')
  event.preventDefault()
}

const handleSelfStop = () => {
  addLog('🎯 self.stop: 仅自身触发，阻止冒泡')
}
</script>

<style scoped>
.combined-modifier-demo {
  padding: 20px;
  max-width: 1000px;
  margin: 0 auto;
}

.combination-examples {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 20px;
  margin: 30px 0;
}

.example {
  padding: 20px;
  background: #f8f9fa;
  border-radius: 8px;
  border: 1px solid #e9ecef;
}

.example h3 {
  margin: 0 0 15px 0;
  color: #333;
  font-size: 16px;
}

.example p {
  margin: 10px 0 0 0;
  color: #666;
  font-size: 14px;
  font-style: italic;
}

.combined-link {
  display: block;
  padding: 12px;
  background: #e3f2fd;
  border: 2px solid #2196f3;
  border-radius: 6px;
  text-decoration: none;
  color: #1976d2;
  text-align: center;
  font-weight: bold;
  transition: background 0.3s;
}

.combined-link:hover {
  background: #bbdefb;
}

.capture-once-box {
  padding: 20px;
  background: #fff3e0;
  border: 2px solid #ff9800;
  border-radius: 6px;
  text-align: center;
  cursor: pointer;
  font-weight: bold;
  color: #e65100;
}

.capture-once-box button {
  margin-top: 10px;
  padding: 8px 16px;
  background: #ff9800;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.exact-ctrl-btn {
  width: 100%;
  padding: 12px;
  background: #fce4ec;
  border: 2px solid #e91e63;
  border-radius: 6px;
  color: #c2185b;
  font-weight: bold;
  cursor: pointer;
  transition: background 0.3s;
}

.exact-ctrl-btn:focus {
  outline: none;
  background: #f8bbd9;
}

.self-stop-box {
  padding: 20px;
  background: #e8f5e8;
  border: 2px solid #4caf50;
  border-radius: 6px;
  text-align: center;
  cursor: pointer;
  font-weight: bold;
  color: #2e7d32;
}

.self-stop-box button {
  margin-top: 10px;
  padding: 8px 16px;
  background: #4caf50;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.combination-logs {
  margin-top: 30px;
  padding: 20px;
  background: #2c3e50;
  border-radius: 8px;
  color: white;
}

.combination-logs h3 {
  margin: 0 0 15px 0;
  color: #42b883;
}

.log-item {
  padding: 10px 15px;
  margin: 5px 0;
  background: #34495e;
  border-radius: 4px;
  border-left: 4px solid #42b883;
  font-family: 'Courier New', monospace;
  font-size: 14px;
}
</style>

---

八、 最佳实践和注意事项

8.1 事件修饰符最佳实践

<template>
  <div class="best-practices-demo">
    <h2>事件修饰符最佳实践</h2>
    
    <div class="practices">
      <div class="practice-item good">
        <h3>✅ 推荐做法</h3>
        <div class="code-example">
          <pre><code>&lt;!-- 清晰的修饰符顺序 --&gt;
&lt;form @submit.prevent.stop="handleSubmit"&gt;
&lt;!-- 适当的修饰符组合 --&gt;
&lt;a @click.prevent="handleLinkClick"&gt;
&lt;!-- 使用 .exact 精确控制 --&gt;
&lt;button @keyup.ctrl.exact="handleExactCtrl"&gt;</code></pre>
        </div>
      </div>
      
      <div class="practice-item bad">
        <h3>❌ 避免做法</h3>
        <div class="code-example">
          <pre><code>&lt;!-- 过度使用修饰符 --&gt;
&lt;button @click.prevent.stop.self="handleClick"&gt;
&lt;!-- 混淆的修饰符顺序 --&gt;
&lt;form @submit.stop.prevent="handleSubmit"&gt;
&lt;!-- 不必要的修饰符 --&gt;
&lt;div @click.self.prevent="handleClick"&gt;</code></pre>
        </div>
      </div>
    </div>

    <div class="performance-tips">
      <h3>性能提示</h3>
      <ul>
        <li>使用 <code>.passive</code> 改善滚动性能，特别是移动端</li>
        <li>避免在频繁触发的事件上使用复杂的修饰符组合</li>
        <li>使用 <code>.once</code> 清理不需要持续监听的事件</li>
        <li>合理使用 <code>.prevent</code> 避免不必要的默认行为阻止</li>
      </ul>
    </div>

    <div class="accessibility-considerations">
      <h3>可访问性考虑</h3>
      <ul>
        <li>确保键盘导航支持所有交互功能</li>
        <li>使用适当的 ARIA 标签描述交互行为</li>
        <li>测试屏幕阅读器兼容性</li>
        <li>提供键盘快捷键的视觉提示</li>
      </ul>
    </div>
  </div>
</template>

<script setup>
// 最佳实践示例代码
const handleSubmit = () => {
  console.log('表单提交处理')
}

const handleLinkClick = () => {
  console.log('链接点击处理')
}

const handleExactCtrl = () => {
  console.log('精确 Ctrl 键处理')
}
</script>

<style scoped>
.best-practices-demo {
  padding: 20px;
  max-width: 900px;
  margin: 0 auto;
}

.practices {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 30px;
  margin: 30px 0;
}

.practice-item {
  padding: 25px;
  border-radius: 8px;
}

.practice-item.good {
  background: #e8f5e8;
  border: 2px solid #4caf50;
}

.practice-item.bad {
  background: #ffebee;
  border: 2px solid #f44336;
}

.practice-item h3 {
  margin: 0 0 15px 0;
  color: inherit;
}

.code-example {
  background: white;
  border-radius: 6px;
  padding: 15px;
  overflow-x: auto;
}

.code-example pre {
  margin: 0;
  font-family: 'Courier New', monospace;
  font-size: 14px;
  line-height: 1.4;
}

.performance-tips, .accessibility-considerations {
  margin: 30px 0;
  padding: 25px;
  background: #e3f2fd;
  border-radius: 8px;
}

.performance-tips h3, .accessibility-considerations h3 {
  margin: 0 0 15px 0;
  color: #1976d2;
}

.performance-tips ul, .accessibility-considerations ul {
  margin: 0;
  color: #333;
}

.performance-tips li, .accessibility-considerations li {
  margin: 8px 0;
}

.performance-tips code, .accessibility-considerations code {
  background: #fff;
  padding: 2px 6px;
  border-radius: 3px;
  font-family: 'Courier New', monospace;
  font-size: 12px;
}
</style>

---

九、 总结

9.1 事件修饰符核心价值

1. 声明式编程：以声明的方式表达事件行为意图
2. 代码简洁：减少样板代码，提高开发效率
3. 可读性强：代码意图一目了然
4. 维护方便：修改事件行为只需改动模板

9.2 事件修饰符分类总结

类别	主要修饰符	使用场景
事件传播	.stop .capture .self	控制事件传播流程
默认行为	.prevent .passive	管理浏览器默认行为
按键处理	.enter .tab .esc 等	键盘交互处理
系统修饰	.ctrl .alt .shift .meta	组合键操作
精确控制	.exact	精确匹配修饰符
鼠标按键	.left .right .middle	区分鼠标按键
次数控制	.once	一次性事件处理

9.3 最佳实践要点

1. 合理排序 ：按照 .capture → .once → .passive → .prevent → .stop → .self 的顺序
2. 适度使用：避免过度复杂的修饰符组合
3. 性能考虑 ：在频繁事件上使用 .passive
4. 可访问性：确保键盘导航支持所有功能

Vue3 的事件修饰符提供了一种优雅而强大的方式来处理 DOM 事件细节，通过合理使用这些修饰符，可以编写出更加简洁、可读和可维护的 Vue 代码。

---

如果这篇文章对你有帮助，欢迎点赞、收藏和评论！有任何问题都可以在评论区讨论。