Vue | Vue自定义指令详解：一篇带你搞懂Vue中的自定义指令

最新推荐文章于 2025-09-25 15:15:00 发布

原创最新推荐文章于 2025-09-25 15:15:00 发布 · 887 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#vue.js #javascript #vue指令 #Vue自定义指令

Vue.js 同时被 2 个专栏收录

74 篇文章

订阅专栏

⭐ Vue.js入门基础

13 篇文章

订阅专栏

自定义指令，是Vue提供的一种扩展和定制的机制，使开发者能够在组件中直接操作DOM、处理事件、添加样式等，并提供了与第三方库集成的方式，定义指令使得Vue在处理交互和DOM操作时更加灵活和强大，本文将带大家搞懂Vue中的自定义指令，需要的朋友可以参考下。

自定义指令的设计原则

在 Vue 中，自定义指令是通过调用 Vue.directive 方法或使用 directive 函数来创建的。自定义指令可以在 Vue 组件的模板中直接使用，并且可以绑定到元素、组件或模板的各种属性上。

自定义指令的设计遵循以下几个核心原则：

注册指令： 使用 Vue.directive 方法或 directive 函数来注册指令。这些方法接受两个参数：指令名称和指令配置对象。指令名称是一个字符串，用于在模板中绑定指令。指令配置对象包含一系列钩子函数和其他配置选项，用于定义指令的行为。
钩子函数： 指令配置对象中的钩子函数定义了指令的生命周期。常用的钩子函数包括 bind、mounted、update、componentUpdated 和 unbind。这些钩子函数在指令的不同生命周期阶段被调用，允许开发者在相应的时机执行自定义的逻辑。
钩子函数参数： 指令的钩子函数可以接受一些参数，用于传递信息给指令的行为逻辑。常用的参数包括 el（指令所绑定的元素）、binding（一个对象，包含指令的绑定值、参数、修饰符等信息）、vnode（Vue 编译生成的虚拟节点）和 oldVnode（上一个虚拟节点）等。
修饰符： 修饰符是附加在指令后面的特殊标记，用于修改指令的行为。Vue 提供了一些内置的修饰符，如 .prevent、.stop、.capture、.self 等，用于处理事件和事件修饰符。开发者也可以自定义修饰符，并在指令的行为逻辑中根据修饰符的值进行相应处理。

Vue 2 和 Vue 3 的自定义指令区别

Vue 3 的自定义指令在语法上与 Vue 2 的指令有一些不同，但核心概念和使用方式仍然相似。Vue 3 引入了 Composition API，并对指令的钩子函数进行了更细粒度的划分，提供了更灵活和可控的指令编写方式。以下是 Vue 2 和 Vue 3 的自定义指令之间的主要区别：

注册方式

Vue 2：在 Vue 2 中，使用全局的 Vue.directive 方法来注册自定义指令。指令名称作为第一个参数，指令配置对象作为第二个参数。
Vue 3：在 Vue 3 中，可以使用全局的 app.directive 方法或 directive 函数来注册自定义指令。指令名称作为第一个参数，指令配置对象作为第二个参数。

指令钩子函数

Vue 2：Vue 2 的指令钩子函数包括 bind、inserted、update、componentUpdated 和 unbind。这些钩子函数在指令的生命周期中不同的阶段被调用。
Vue 3：Vue 3 的指令钩子函数包括 beforeMount、mounted、beforeUpdate、updated、beforeUnmount 和 unmounted。这些钩子函数提供了更细粒度的控制，并与组件的生命周期钩子函数保持一致。

钩子函数参数

Vue 2：Vue 2 的指令钩子函数的参数包括 el、binding、vnode 和 oldVnode。其中，binding 对象中包含了指令的绑定值、参数、修饰符等信息。
Vue 3：Vue 3 的指令钩子函数的参数也包括 el、binding、vnode 和 prevVnode。prevVnode 是之前的虚拟节点，用于在更新钩子函数中进行比较。

指令修饰符

Vue 2：Vue 2 的指令修饰符可以通过 v- 前缀使用，例如 v-on:click.stop。Vue 2 提供了一些内置的事件修饰符，如 .stop、.prevent、.capture、.self 等。
Vue 3：Vue 3 的指令修饰符不再使用 v- 前缀，而是直接在指令后面使用，例如 @click.stop。Vue 3 内置的事件修饰符仍然可用，但要与 @ 符号一起使用。

常见的自定义指令应用场景

操作 DOM

自定义指令可用于直接操作 DOM 元素，例如设置样式、添加类名、聚焦元素、滚动等。这样可以避免直接在组件中操作 DOM，保持组件的职责单一。

<template> 
     <div> 
         <input v-focus /> 
     </div> 
</template> 
<script> 
    // 自定义指令：聚焦元素 
    Vue.directive('focus', { 
        inserted(el) { 
            el.focus(); 
        } 
    }); 
</script>

事件处理

自定义指令可用于处理事件，如监听点击事件、滚动事件、拖拽事件等。通过自定义指令，可以封装特定的事件处理逻辑，并在组件中复用。

在以下示例中，定义了一个自定义指令 v-draggable，它绑定在一个具有 draggable 类的元素上。当鼠标按下或触摸开始时，启动拖拽功能。在拖拽过程中，元素会跟随鼠标或手指的移动而改变位置。当鼠标释放或触摸结束时，停止拖拽。

<template> 
  <div> 
      <div class="draggable" v-draggable> Drag me!</div> 
  </div> 
</template>
<script>
  // 自定义指令：拖拽 
  Vue.directive('draggable', { 
      bind(el) { 
          el.style.position = 'absolute'; 
          el.style.cursor = 'move'; 
          let offsetX = 0; 
          let offsetY = 0; 
          let isDragging = false; 
          el.addEventListener('mousedown', startDrag); 
          el.addEventListener('touchstart', startDrag);
          function startDrag(e) { 
              e.preventDefault(); 
              if (e.type === 'touchstart') { 
                  offsetX = e.touches[0].clientX - el.getBoundingClientRect().left; 
                  offsetY = e.touches[0].clientY - el.getBoundingClientRect().top; 
              } else { 
                  offsetX = e.clientX - el.getBoundingClientRect().left; 
                  offsetY = e.clientY - el.getBoundingClientRect().top; 
              }
                  isDragging = true; 
                  document.addEventListener('mousemove', handleDrag); 
                  document.addEventListener('touchmove', handleDrag); 
                  document.addEventListener('mouseup', stopDrag); 
                  document.addEventListener('touchend', stopDrag); 
              }
              function handleDrag(e) { 
                  e.preventDefault(); 
                  let x = 0; 
                  let y = 0; 
                  if (e.type === 'touchmove') { 
                      x = e.touches[0].clientX - offsetX; y = e.touches[0].clientY - offsetY; 
                  } else { 
                      x = e.clientX - offsetX; 
                      y = e.clientY - offsetY; 
                  } 
                      el.style.left = x + 'px'; 
                      el.style.top = y + 'px'; 
              }
            function stopDrag() { 
                isDragging = false;
                document.removeEventListener('mousemove', handleDrag); 
                document.removeEventListener('touchmove', handleDrag);
                document.removeEventListener('mouseup', stopDrag); 
                document.removeEventListener('touchend', stopDrag); 
          } 
      } 
  });
</script>
<style> 
  .draggable { 
      width: 100px; 
      height: 100px; 
      background-color: #ccc; 
      text-align: center; 
      line-height: 100px; 
   } 
</style>

表单验证

自定义指令可用于表单验证，例如检查输入是否满足特定的条件、格式化输入等。自定义指令可以在输入框失去焦点或值变化时进行验证，并给出相应的提示信息。

在以下示例中，定义了一个自定义指令 v-validate，它用于验证表单输入。通过指令的参数来指定验证类型，例如 required 表示必填字段，email 表示邮箱格式验证。

在 validateField 函数中，我们根据指令的参数进行相应的验证逻辑，并根据验证结果来显示或隐藏错误提示。

当表单提交时，我们在 submitForm 方法中检查必填字段是否都已填写。如果有未填写的字段，我们将 showError 设置为 true，显示错误提示信息。否则，我们将 showError 设置为 false，执行表单提交操作。

<template> 
  <div> 
      <form @submit.prevent="submitForm"> 
          <label for="name">Name:</label> 
          <input id="name" v-model="name" v-validate.required /> 
          <label for="email">Email:</label> 
          <input id="email" v-model="email" v-validate.email /> 
          <button type="submit">Submit</button> 
      </form> 
      <p v-show="showError" class="error-message">Please fill in all the required fields.</p> 
  </div> 
</template>
<script>
 // 自定义指令：表单验证 
 Vue.directive('validate', { 
     bind(el, binding) { 
         const { value } = binding; 
         function validateField() { 
             const inputValue = el.value; 
             if (value === 'required' && !inputValue.trim()) { 
                 showError(true); 
             } else if (value === 'email' && !validateEmail(inputValue)) { 
                 showError(true); 
             } else { 
                 showError(false); 
             } 
           }
          el.addEventListener('blur', validateField);
          function showError(show) { 
              el.classList.toggle('error', show); 
          } 
          function validateEmail(email) { 
              const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; 
              return regex.test(email); 
          } 
       } 
  });
  export default { 
      data() { 
          return { 
              name: '', 
              email: '', 
              showError: false 
           }; 
      }, 
      methods: { 
          submitForm() { 
              // 表单提交逻辑 
              if (this.name && this.email) { 
                  // 执行表单提交操作 
                  this.showError = false; 
              } else { 
                  this.showError = true; 
               } 
             } 
          } 
     };
</script>
<style> 
 .error { 
     border-color: red; 
  } 
  .error-message { 
      color: red; 
      margin-top: 5px; 
  }
</style>

第三方库集成： 自定义指令可用于与第三方库进行集成，如集成日期选择器、富文本编辑器、图表库等。通过自定义指令，可以在组件中方便地使用第三方库提供的功能。

以下是一个示例，展示如何使用自定义指令来集成日期选择器（这里以 flatpickr 库为例），在这个示例中，我们定义了一个自定义指令 v-datepicker，它用于将日期选择器集成到输入框中。我们使用了 flatpickr 这个第三方库来实现日期选择器的功能。

在 mounted 钩子中，我们使用 flatpickr 函数将日期选择器应用到指令所在的输入框上。我们可以通过配置对象来设置日期选择器的选项，例如日期格式、事件回调等。

在日期选择器的 onChange 事件回调中，我们将选中的日期赋值给指令的绑定值 binding.value，以便在父组件中获取选择的日期值。

在 beforeUnmount 钩子中，我们销毁日期选择器实例，以释放资源并防止内存泄漏。

<template> 
  <div> 
      <input v-datepicker v-model="selectedDate" /> 
  </div> 
</template>
<script> 
  import flatpickr from 'flatpickr'; 
  // 自定义指令：集成 flatpickr 
  Vue.directive('datepicker', { 
      mounted(el, binding) { 
          flatpickr(el, { 
              dateFormat: 'Y-m-d', 
              onChange(selectedDates) { 
                  binding.value = selectedDates[0];
              } 
     }); 
  }, 
  beforeUnmount(el) { 
      const flatpickrInstance = flatpickrInstance(el);
      if (flatpickrInstance) { 
          flatpickrInstance.destroy(); 
       } 
      } 
  }); 
</script>

动画和过渡效果

自定义指令可用于处理动画和过渡效果，例如实现元素的淡入淡出、滑动等效果。通过自定义指令，可以在元素的插入、更新、移除等过程中添加动画效果。

在以下示例中，我们定义了一个自定义指令 v-fade-transition，它用于为元素添加淡入淡出的过渡效果。

在 beforeMount 钩子中，我们设置元素的初始透明度为 0，并添加过渡效果的 CSS 属性。

在 mounted 钩子中，我们将元素的透明度设置为 1，实现淡入效果。

在 beforeUnmount 钩子中，我们将元素的透明度设置为 0，实现淡出效果。

在组件的模板中，我们使用 v-if 指令来控制元素的显示与隐藏，同时将自定义指令 v-fade-transition 应用在这个元素上，实现淡入淡出的过渡效果。

当点击按钮时，我们通过 toggleVisibility 方法来切换元素的显示与隐藏。

<template> 
  <div> 
      <button @click="toggleVisibility">Toggle</button> 
      <div v-if="isVisible" v-fade-transition> 
          Content 
      </div>
  </div> 
</template>
<script> 
  // 自定义指令：淡入淡出过渡效果 
  Vue.directive('fade-transition', { 
      beforeMount(el) { 
          el.style.opacity = '0'; 
          el.style.transition = 'opacity 0.5s';
      }, 
      mounted(el) { 
          el.style.opacity = '1'; 
      }, 
      beforeUnmount(el) { 
          el.style.opacity = '0'; 
      } 
  });
  export default { 
      data() { 
          return { 
              isVisible: false 
          }; 
      }, 
      methods: { 
          toggleVisibility() { 
              this.isVisible = !this.isVisible; 
           } 
      } 
   }; 
</script>
<style> 
    .fade-transition { 
        transition: opacity 0.5s; 
    } 
</style>

权限控制

自定义指令可用于权限控制，例如根据用户的角色或权限，动态显示或隐藏某些元素。自定义指令可以根据用户的权限信息，决定元素的可见性或可操作性。

在以下示例中，我们定义了一个自定义指令 v-permission，它用于根据用户权限控制元素的可用性。

在 mounted 钩子中，我们获取指令的绑定值 permission，并检查用户的权限数组 userPermissions 是否包含该权限。如果用户没有该权限，我们禁用按钮元素（el.disabled = true），添加禁用样式类（el.classList.add('disabled')），并设置提示信息（el.title）。

在组件的模板中，我们在按钮元素上使用 v-permission 指令，并将相应的权限字符串作为指令的参数，用于权限控制。

另外，我们使用 v-show 指令结合 isAdmin 数据属性来控制管理员权限下的按钮的显示与隐藏。

<template> 
  <div> 
      <button v-permission="'edit'">Edit</button>
      <button v-permission="'delete'">Delete</button> 
      <button v-permission="'create'" v-show="isAdmin">Create</button> 
  </div> 
</template>
<script> 
 // 模拟用户权限 
 const userPermissions = ['edit', 'delete']; 
 // 自定义指令：权限控制 
 Vue.directive('permission', { 
     mounted(el, binding) { 
         const permission = binding.value; 
         if (!userPermissions.includes(permission)) {
         el.disabled = true; 
         el.classList.add('disabled'); 
         el.title = 'You do not have permission to perform this action'; 
      } 
    } 
});
export default { data() { 
    return { 
        isAdmin: true // 用户是否是管理员 
     }; 
   } 
}; 
</script>
<style> 
.disabled { 
    opacity: 0.5; 
    cursor: not-allowed; 
 }  
</style>

响应式操作

自定义指令可用于监听数据的变化，并在数据变化时执行相应的操作。例如，自定义指令可以监听滚动位置，根据滚动位置改变某些元素的样式或行为。

如下示例中，我们定义了一个自定义指令 v-scroll-spy，它用于监听容器元素的滚动事件。

在 mounted 钩子中，我们为容器元素添加了 scroll 事件监听器，当容器滚动时，会触发 handleScroll 方法。

在 beforeUnmount 钩子中，我们移除了 scroll 事件监听器，以防止内存泄漏。

在 handleScroll 方法中，我们通过 event.target.scrollTop 获取到容器的滚动位置，然后根据滚动位置执行相应的操作。在这个示例中，当滚动位置大于 200px 时，我们输出一条日志。

在组件的模板中，我们使用 v-scroll-spy 指令应用在一个滚动容器上，并通过 v-for 指令渲染了几个示例部分。

<template> 
  <div v-scroll-spy> 
      <div class="section" v-for="section in sections" :key="section.id"> {{ section.content }} 
      </div> 
  </div> 
</template>
<script> 
 // 自定义指令：滚动监听 
 Vue.directive('scroll-spy', { 
     mounted(el) { 
         el.addEventListener('scroll', this.handleScroll); 
     }, 
     beforeUnmount(el) { 
     el.removeEventListener('scroll', this.handleScroll); 
     },
     methods: { 
         handleScroll(event) { 
             // 获取滚动位置 
             const scrollTop = event.target.scrollTop; 
             // 根据滚动位置触发不同的操作 
             // 这里可以根据需要自定义滚动监听的逻辑 
             if (scrollTop > 200) { 
                  // 滚动位置大于 200px 执行操作 
                  console.log('Scrolled beyond 200px'); 
                }
               } 
           } 
      });
      export default { 
          data() { 
              return { 
                  sections: [ 
                      { id: 1, content: 'Section 1' }, 
                      { id: 2, content: 'Section 2' }, 
                      { id: 3, content: 'Section 3' } 
                   ] }; 
               } 
        }; 
</script>
<style> 
   .section { 
       height: 200px; 
       margin-bottom: 20px; 
       border: 1px solid #ccc; 
       padding: 20px; 
    } 
</style>

性能优化

自定义指令可用于性能优化，例如延迟加载、虚拟滚动等。通过自定义指令，可以根据需要延迟加载某些元素或优化滚动的性能。下面是一个示例，展示如何使用自定义指令实现滚动监听实现图片懒加载：

<template> 
  <div> 
      <div class="image-container" v-scroll-lazy> 
          <img v-for="image in images" :key="image.id" :src="image.src" class="lazy-image" /> 
      </div> 
  </div> 
</template>
<script> 
 // 自定义指令：滚动懒加载 
 Vue.directive('scroll-lazy', { 
     mounted(el) { 
         const lazyImages = el.querySelectorAll('.lazy-image'); 
         this.loadImagesOnScroll(lazyImages); 
         // 添加滚动事件监听器 
         el.addEventListener('scroll', () => { 
             this.loadImagesOnScroll(lazyImages); 
         }); 
        }, 
     beforeUnmount(el) { 
     // 移除滚动事件监听器 
     el.removeEventListener('scroll', () => { this.loadImagesOnScroll(lazyImages); 
     }); 
  },
  methods: { 
      loadImagesOnScroll(lazyImages) {
          lazyImages.forEach(image => {
              if (this.isImageVisible(image) && !image.src) { 
                  // 加载图片 
                  image.src = image.dataset.src; 
              } 
          }); 
       }, 
       isImageVisible(image) { 
           const rect = image.getBoundingClientRect(); 
           return ( 
           rect.top >= 0 && 
           rect.left >= 0 && 
           rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && 
           rect.right <= (window.innerWidth || document.documentElement.clientWidth) 
         ); 
       } 
     } 
});
export default { 
    data() { 
        return { 
            images: [ 
                { id: 1, src: '', dataSrc: 'image1.jpg' }, 
                { id: 2, src: '', dataSrc: 'image2.jpg' }, 
                { id: 3, src: '', dataSrc: 'image3.jpg' } 
          ] 
       }; 
    } 
}; 
</script>
<style> 
.image-container { 
   height: 300px; 
   overflow: auto; 
} 
.lazy-image { 
    width: 100%; 
    height: auto; 
 } 
</style>

在这个示例中，我们定义了一个自定义指令 v-scroll-lazy，它用于在滚动容器中实现图片懒加载。

在 mounted 钩子中，我们获取到所有具有 .lazy-image 类的图片元素，并通过 loadImagesOnScroll 方法进行初始的图片加载。然后，我们添加了滚动事件监听器，在滚动时继续加载更多的图片。

在 beforeUnmount 钩子中，我们移除了滚动事件监听器。

在 loadImagesOnScroll 方法中，我们遍历每个图片元素，检查它是否可见并且尚未加载。如果是，则将 data-src 属性的值设置为 src 属性，触发图片加载。

在 isImageVisible 方法中，我们使用 getBoundingClientRect 方法来判断图片是否在可视区域内。

在组件的模板中，我们使用 v-scroll-lazy 指令应用在一个滚动容器上，并通过 v-for 指令渲染了几个示例图片。每个图片都有一个 data-src 属性，表示真实的图片路径。一开始，src 属性为空，当图片进入可视区域时，会触发图片加载。

相关参考：Vue | Vue中的自定义指令详解_儒雅的烤地瓜优快云博客