Vue3 自定义指令开发

🌟 核心概念重构

1. 生命周期对比

全局注册指令通过app.directive()方法在整个应用可用，而局部注册仅在组件作用域内有效，两种方式在SSR渲染、Tree-shaking优化等方面有显著差异。

2. 注册方式对比

// 全局注册
const app = createApp({})
app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

// 局部注册
const Component = {
  directives: {
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}

🛠️ 企业级指令开发模式

TypeScript类型注解确保指令参数的类型校验，组合式API封装使指令具备响应式能力，同时支持逻辑复用和内存管理，符合现代前端工程化标准。

1. 类型安全指令（TypeScript）

import type { Directive, DirectiveBinding } from 'vue'

type TooltipBinding = DirectiveBinding<{
  content: string
  placement?: 'top' | 'bottom'
}>

const vTooltip: Directive<HTMLElement, TooltipBinding['value']> = {
  mounted(el, binding) {
    initTooltip(el, binding.value)
  },
  updated(el, binding) {
    updateTooltip(el, binding.value)
  }
}

2. 组合式API指令

import { ref, onUnmounted } from 'vue'

export function useResizeObserver() {
  const observer = ref(null)

  const vResize = {
    mounted(el, { value: callback }) {
      observer.value = new ResizeObserver(entries => {
        callback(entries[0].contentRect)
      })
      observer.value.observe(el)
    },
    unmounted(el) {
      observer.value?.unobserve(el)
    }
  }

  return { vResize }
}

// 组件内使用
const { vResize } = useResizeObserver()
export default {
  directives: { resize: vResize }
}

🚀 高阶应用场景

权限控制指令通过Vuex/Pinia状态管理实现动态DOM操作，拖拽指令采用事件委托和坐标变换技术，同时处理PC端和移动端事件。

1. 权限控制指令

const vPermission = {
  beforeMount(el, { value: roles }) {
    const userRoles = store.getters.roles
    if (!roles.some(role => userRoles.includes(role))) {
      el.parentNode?.removeChild(el)
    }
  }
}

// 使用：<button v-permission="['admin']">删除</button>

2. 拖拽指令（支持移动端）

const vDrag = {
  mounted(el, { value: callback }) {
    let startX, startY, currentX = 0, currentY = 0
    const handleStart = (e) => {
      e.preventDefault()
      const touch = e.touches?.[0] || e
      startX = touch.clientX - currentX
      startY = touch.clientY - currentY
      document.addEventListener('mousemove', handleMove)
      document.addEventListener('mouseup', handleEnd)
      document.addEventListener('touchmove', handleMove)
      document.addEventListener('touchend', handleEnd)
    }

    const handleMove = (e) => {
      const touch = e.touches?.[0] || e
      currentX = touch.clientX - startX
      currentY = touch.clientY - startY
      el.style.transform = `translate(${currentX}px, ${currentY}px)`
      callback?.({ x: currentX, y: currentY })
    }

    const handleEnd = () => {
      document.removeEventListener('mousemove', handleMove)
      document.removeEventListener('mouseup', handleEnd)
      document.removeEventListener('touchmove', handleMove)
      document.removeEventListener('touchend', handleEnd)
    }

    el.addEventListener('mousedown', handleStart)
    el.addEventListener('touchstart', handleStart)
  }
}

🏆 性能优化与最佳实践

防抖/节流实现采用事件委托和内存清理，配置参数化设计支持动态调整IntersectionObserver阈值等关键参数。

1. 防抖/节流实现

const vDebounceClick = {
  mounted(el, { value: { handler, delay = 300 } }) {
    let timer = null
    el._debounceHandler = (e) => {
      timer && clearTimeout(timer)
      timer = setTimeout(() => handler(e), delay)
    }
    el.addEventListener('click', el._debounceHandler)
  },
  unmounted(el) {
    el.removeEventListener('click', el._debounceHandler)
  }
}

// 使用：<button v-debounce-click="{ handler: submit, delay: 500 }">

2. 指令配置参数化

const vLazyLoad = {
  mounted(el, { value, modifiers, arg }) {
    const config = {
      root: arg === 'parent' ? el.parentElement : null,
      threshold: modifiers.instant ? 1.0 : 0.1,
      ...(typeof value === 'object' ? value : { src: value })
    }

    const observer = new IntersectionObserver(([entry]) => {
      if (entry.isIntersecting) {
        el.src = config.src
        observer.unobserve(el)
      }
    }, config)

    observer.observe(el)
    el._observer = observer
  },
  unmounted(el) {
    el._observer?.disconnect()
  }
}

// 使用：<img v-lazy-load:parent.instant="{ src: 'image.jpg', threshold: 0.5 }">

🚧 企业级问题解决方案

SSR兼容方案通过生命周期控制避免客户端API的服务器端调用，单元测试方案采用Vitest+Testing Library实现DOM操作验证，确保指令稳定性。

1. SSR兼容方案

const vClientOnly = {
  mounted(el, binding) {
    binding.value?.()
  }
}

// 使用：<div v-client-only="initMap"></div>

2. 指令单元测试

import { mount } from '@vue/test-utils'
import { describe, it, expect } from 'vitest'

describe('vTooltip', () => {
  it('should show tooltip on hover', async () => {
    const wrapper = mount({
      template: `<div v-tooltip="'Help text'"></div>`,
      directives: { tooltip }
    })
    await wrapper.trigger('mouseenter')
    expect(document.querySelector('.tooltip').textContent).toBe('Help text')
  })
})

📊 指令开发决策树

基于架构考量的技术选型指南

mermaid
graph TD
  A[需要DOM操作?] -->|是| B[需要响应式更新?]
  A -->|否| C[使用组合式函数]
  B -->|是| D[使用指令生命周期]
  B -->|否| E[使用事件监听]
  D --> F[是否需要跨组件复用?]
  F -->|是| G[全局注册指令]
  F -->|否| H[局部注册指令]

通过掌握这些进阶技巧，可开发出高复用性、类型安全且性能优异的自定义指令，满足企业级应用复杂需求