Vue 3 自定义指令：从“瑞士军刀”到“专属工具” !

---

🔥 以龙息淬炼代码，在时光灰烬中重铸技术星河 ！

欢迎来到 晷龙烬的博客小窝✨！

这里记录技术学习点滴，分享实用技巧，偶尔聊聊奇思妙想～

原创内容✍️，转载请注明出处～感谢支持❤️！请尊重原创📩！

欢迎在评论区交流🌟！

引言

你好呀！如果你已经熟悉Vue 2的自定义指令，那么恭喜你，Vue 3的自定义指令会让你感觉更加顺手和强大！如果你还没接触过，那也没关系，今天我们就从零开始，用大白话把Vue 3的自定义指令聊明白。

Vue 3在保持核心概念不变的基础上，对自定义指令的API进行了一些重要的优化和调整。它不再是"瑞士军刀"式的通用工具，而是更像你根据项目需求打造的"专属工具"，更加灵活、更加符合现代开发习惯。

一、 Vue 3 自定义指令的"变"与"不变"

不变的核心思想

自定义指令的核心思想没变：封装可复用的DOM操作逻辑。无论是让输入框自动聚焦，还是实现图片懒加载，这个根本目的始终如一。

重要的变化

1. 钩子函数重命名：为了更好的语义化和一致性，Vue 3对指令的生命周期钩子进行了重命名。
2. 更灵活的注册方式：与组件类似，指令的注册和使用方式更加统一。
3. 更好的TypeScript支持：Vue 3的Composition API让指令的类型推断更加友好。

二、 全新的生命周期钩子

这是Vue 3自定义指令最明显的变化。让我们对比一下：

Vue 2 钩子	Vue 3 钩子	调用时机	说明
bind	created	指令绑定到元素时	只调用一次，进行初始化设置
inserted	mounted	元素插入父节点时	元素已挂载到DOM中
update	updated	组件更新时	所在组件的VNode更新后调用
componentUpdated	-	-	在Vue 3中被移除 ，功能合并到updated中
unbind	unmounted	指令与元素解绑时	进行清理工作，防止内存泄漏

另外，Vue 3还新增了两个钩子：

• beforeMount ：在元素挂载到DOM之前调用（类似Vue 2的bind，但时机略有不同）。
• beforeUpdate：在元素本身更新之前调用。

三、 创建你的第一个Vue 3自定义指令

1. 全局注册

在Vue 3中，我们使用app.directive()来全局注册指令：

// main.js 或类似入口文件
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

// 注册一个全局自定义指令 `v-focus`
app.directive('focus', {
  // 当被绑定的元素挂载到 DOM 中时......
  mounted(el) {
    // 聚焦元素
    el.focus()
  }
})

app.mount('#app')

使用方式完全一样：

<template>
  <input v-focus placeholder="我会自动获得焦点">
</template>

2. 局部注册

在组件内部，通过directives选项注册局部指令：

<script>
export default {
  directives: {
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}
</script>

四、 钩子函数的参数详解

Vue 3的指令钩子函数接收的参数更加清晰：

app.directive('demo', {
  created(el, binding, vnode, prevVnode) {
    // el: 指令绑定的元素
    // binding: 一个对象，包含指令的信息
    // vnode: 当前虚拟节点
    // prevVnode: 上一个虚拟节点（仅在 beforeUpdate 和 updated 中可用）
  },
  mounted(el, binding) {
    // 最常用的钩子
    console.log(binding.value)    // 指令的值
    console.log(binding.oldValue) // 之前的值（仅在 updated 中可用）
    console.log(binding.arg)      // 传递给指令的参数
    console.log(binding.modifiers) // 修饰符对象
    console.log(binding.instance) // 使用指令的组件实例
    console.log(binding.dir)      // 指令的定义对象
  }
})

五、 实战：Vue 3 风格的实用指令

例子1：权限控制指令（支持动态权限）*

// 全局注册
app.directive('permission', {
  mounted(el, binding) {
    checkPermission(el, binding)
  },
  updated(el, binding) {
    // 权限可能动态变化，需要在更新时重新检查
    checkPermission(el, binding)
  }
})

function checkPermission(el, binding) {
  const { value, modifiers } = binding
  const currentUser = useUserStore() // 假设使用Pinia存储用户信息
  
  // value可以是单个权限，也可以是权限数组
  const requiredPermissions = Array.isArray(value) ? value : [value]
  const hasPermission = requiredPermissions.some(perm => 
    currentUser.permissions.includes(perm)
  )
  
  if (!hasPermission) {
    if (modifiers.hide) {
      el.style.display = 'none'
    } else if (modifiers.disable) {
      el.disabled = true
      el.classList.add('disabled')
    } else {
      // 默认移除元素
      el.parentNode?.removeChild(el)
    }
  }
}

使用方式：

<button v-permission="'article.delete'">删除文章</button>
<button v-permission.hide="['article.edit', 'article.delete']">编辑/删除</button>
<button v-permission.disable="'admin'">管理员功能</button>

例子2：现代化的防抖指令（Composition API风格）

import { debounce } from 'lodash-es'

// 使用Composition API风格定义指令
const debounceDirective = {
  mounted(el, binding) {
    const { value, arg, modifiers } = binding
    const delay = arg ? parseInt(arg) : 300
    
    if (typeof value !== 'function') {
      console.warn('v-debounce指令的值必须是一个函数')
      return
    }
    
    // 使用lodash的debounce，也可以自己实现
    const debouncedFn = debounce(value, delay)
    
    // 存储debounced函数，以便清理
    el._debouncedHandler = debouncedFn
    
    // 监听事件
    const eventType = modifiers.input ? 'input' : 'click'
    el.addEventListener(eventType, debouncedFn)
  },
  unmounted(el) {
    // 清理工作
    if (el._debouncedHandler) {
      el._debouncedHandler.cancel?.()
      el._debouncedHandler = null
    }
  }
}

app.directive('debounce', debounceDirective)

六、 使用Composition API编写指令

Vue 3的Composition API让指令的编写更加灵活：

// 自定义指令工厂函数
function createClickOutsideDirective() {
  return {
    mounted(el, binding) {
      el._clickOutsideHandler = (event) => {
        if (!(el === event.target || el.contains(event.target))) {
          binding.value(event)
        }
      }
      document.addEventListener('click', el._clickOutsideHandler)
    },
    unmounted(el) {
      document.removeEventListener('click', el._clickOutsideHandler)
    }
  }
}

// 注册指令
app.directive('click-outside', createClickOutsideDirective())

使用：

<div v-click-outside="closeDropdown">
  <!-- 下拉菜单内容 -->
</div>

七、 常见问题解答

Q: Vue 2的指令能在Vue 3中使用吗？

A: 大部分可以，但需要检查钩子函数名称是否需要修改。建议逐步迁移到Vue 3的新API。

Q: 什么时候应该使用自定义指令？

A: 当你需要直接操作DOM、封装可复用的DOM行为、集成第三方库时。

Q: 自定义指令和组件有什么区别？

A: 组件关注的是数据和模板的封装，指令关注的是DOM行为的封装。指令通常用于增强现有元素的功能。

Q: 可以在Composition API的setup函数中使用指令吗？

A: 可以，通过v-directive在模板中使用，或者在setup中通过ref和指令组合使用。

结语

Vue 3的自定义指令在保持核心功能的同时，通过更清晰的API设计、更好的TypeScript支持和更灵活的组合方式，为开发者提供了更强大的工具。无论是简单的DOM操作，还是复杂的交互逻辑，自定义指令都能让你的代码更加整洁、可维护。

记住，好的自定义指令就像好的工具------它不应该让你感觉到它的存在，而是让你更高效地完成工作。希望这篇文章能帮助你在Vue 3项目中更好地使用自定义指令！

---

------ 完 ------

✨ 至此结束 ✨

💡 点赞关注，解锁更多技术干货！

我是 晷龙烬

期待与你的下次相遇～