Vue 自定义指令实战：从基础到高级应用场景

Vue 的模板语法和组件系统已经能覆盖绝大多数开发需求，但当我们需要对 DOM 进行底层操作时，自定义指令便成为最优雅的解决方案。无论是自动聚焦、权限控制、懒加载，还是拖拽、复制粘贴、防抖节流，自定义指令都能以声明式的方式将复杂的 DOM 逻辑封装成可复用的 v-xxx。本文将从指令的基础概念出发，逐步深入到高级实战场景，帮助你真正掌握这一利器。

一、自定义指令基础：从注册到生命周期

1.1 两种注册方式

Vue 3 中自定义指令可以通过全局或局部方式注册。

全局注册：

const app = Vue.createApp({})
app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

局部注册：

export default {
  directives: {
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}

1.2 指令的钩子函数

Vue 3 为自定义指令提供了完整的生命周期钩子，与组件生命周期类似但作用于元素：

• created：元素属性或事件监听器被应用前调用
• beforeMount：元素被插入 DOM 前调用
• mounted：元素插入父节点后调用（最常用）
• beforeUpdate：元素自身更新前调用
• updated：元素及子节点更新后调用
• beforeUnmount：元素卸载前调用
• unmounted：元素卸载后调用

每个钩子接收四个参数：el、binding、vnode、prevVnode。其中 binding 对象包含 value、oldValue、arg、modifiers 等关键信息，是传递指令参数的核心。

1.3 一个简单示例：自动聚焦

<input v-focus />

app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

这个例子虽然简单，但已经体现了自定义指令的核心价值：将 DOM 操作从组件逻辑中抽离，让模板更干净。

二、进阶实战：参数、修饰符与动态值

2.1 传递参数与修饰符

假设我们需要一个指令，让元素在点击时复制内容到剪贴板，并支持 success 修饰符来显示提示：

<button v-copy:name.success="copyText">复制</button>

app.directive('copy', {
  mounted(el, binding) {
    el.addEventListener('click', () => {
      navigator.clipboard.writeText(binding.value).then(() => {
        if (binding.modifiers.success) {
          alert('复制成功')
        }
      })
    })
  }
})

这里 :name 是参数，.success 是修饰符，binding.value 是传入的值。这种设计让指令具备了极强的表达力。

2.2 响应式更新

指令的值可能是响应式的，需要在 updated 钩子中处理变化：

app.directive('color', {
  mounted(el, binding) {
    el.style.color = binding.value
  },
  updated(el, binding) {
    if (binding.value !== binding.oldValue) {
      el.style.color = binding.value
    }
  }
})

三、高级应用场景

3.1 权限控制指令

在后台系统中，按钮级别的权限控制非常常见。通过自定义指令可以优雅地实现：

app.directive('permission', {
  mounted(el, binding) {
    const { value } = binding
    const roles = store.getters.roles
    if (value && !roles.includes(value)) {
      el.parentNode && el.parentNode.removeChild(el)
    }
  }
})

使用方式：

<button v-permission="'admin'">删除用户</button>

当用户没有 admin 角色时，按钮会被直接移除，避免用户看到无权限的操作入口。

3.2 图片懒加载

懒加载是性能优化的重要手段，利用 IntersectionObserver 配合自定义指令可以轻松实现：

app.directive('lazy', {
  mounted(el, binding) {
    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          el.src = binding.value
          observer.unobserve(el)
        }
      })
    })
    observer.observe(el)
  },
  unmounted(el) {
    // 清理观察器
  }
})

<img v-lazy="imageUrl" alt="图片" />

这个指令在元素进入视口时才加载真实图片，大幅减少初始加载时间。

3.3 拖拽指令

拖拽是另一个经典场景。通过监听 mousedown、mousemove、mouseup 事件，可以实现元素自由拖动：

app.directive('draggable', {
  mounted(el) {
    let startX, startY, initialLeft, initialTop
    const onMouseDown = (e) => {
      startX = e.clientX
      startY = e.clientY
      const rect = el.getBoundingClientRect()
      initialLeft = rect.left
      initialTop = rect.top
      document.addEventListener('mousemove', onMouseMove)
      document.addEventListener('mouseup', onMouseUp)
    }
    const onMouseMove = (e) => {
      const dx = e.clientX - startX
      const dy = e.clientY - startY
      el.style.position = 'fixed'
      el.style.left = initialLeft + dx + 'px'
      el.style.top = initialTop + dy + 'px'
    }
    const onMouseUp = () => {
      document.removeEventListener('mousemove', onMouseMove)
      document.removeEventListener('mouseup', onMouseUp)
    }
    el.addEventListener('mousedown', onMouseDown)
  }
})

使用：

<div v-draggable class="box">拖我</div>

3.4 防抖指令

表单提交、搜索输入等场景中，防抖能有效减少函数调用次数：

app.directive('debounce', {
  mounted(el, binding) {
    let timer = null
    el.addEventListener('click', () => {
      clearTimeout(timer)
      timer = setTimeout(() => {
        binding.value()
      }, binding.arg || 500)
    })
  }
})

<button v-debounce:800="handleSubmit">提交</button>

通过参数 :800 动态指定延迟时间，灵活且直观。

3.5 长按指令

移动端常见的长按操作：

app.directive('longpress', {
  mounted(el, binding) {
    let timer = null
    const start = () => {
      timer = setTimeout(() => {
        binding.value()
      }, 600)
    }
    const cancel = () => clearTimeout(timer)
    el.addEventListener('mousedown', start)
    el.addEventListener('mouseup', cancel)
    el.addEventListener('mouseleave', cancel)
  }
})

<button v-longpress="handleDelete">长按删除</button>

四、最佳实践与注意事项

1. 及时清理副作用：在 unmounted 钩子中移除事件监听、取消定时器、断开观察器，避免内存泄漏。
2. 避免过度使用：能用组件或计算属性解决的问题，优先不用指令。指令适合纯粹的 DOM 操作。
3. 保持单一职责：一个指令只做一件事，组合使用比堆砌逻辑更好。
4. 考虑 SSR 兼容：在服务端渲染中，只有 created 和 beforeMount 会被调用，涉及 DOM 的操作应放在 mounted 之后。
5. TypeScript 支持：Vue 3 提供了 Directive 类型，可以为指令参数添加类型约束，提升开发体验。

五、总结

自定义指令是 Vue 中一把被低估的“瑞士军刀”。从简单的自动聚焦，到权限控制、懒加载、拖拽、防抖等复杂场景，它都能以声明式的方式将 DOM 逻辑封装得干净利落。掌握指令的生命周期、参数传递和修饰符机制，再结合具体业务场景灵活运用，你会发现很多原本需要大量组件代码才能实现的功能，用一行 v-xxx 就能优雅解决。

在实际项目中，建议将常用的自定义指令统一放在 directives/ 目录下，通过插件方式全局注册，形成团队内部的指令库。这样不仅能提升开发效率，还能让代码风格更加统一。

未经允许不得转载：任鹏个人博客 » Vue 自定义指令实战：从基础到高级应用场景