自定义指令变化

理解自定义指令的基本概念

Vue.js 的自定义指令允许开发者直接操作 DOM 元素。与组件不同，指令更专注于底层 DOM 操作。一个典型的指令定义包含几个钩子函数：

Vue.directive('focus', {
  bind(el, binding, vnode) {
    // 指令第一次绑定到元素时调用
  },
  inserted(el, binding, vnode) {
    // 被绑定元素插入父节点时调用
  },
  update(el, binding, vnode, oldVnode) {
    // 所在组件的 VNode 更新时调用
  },
  componentUpdated(el, binding, vnode, oldVnode) {
    // 所在组件的 VNode 及其子 VNode 全部更新后调用
  },
  unbind(el, binding, vnode) {
    // 指令与元素解绑时调用
  }
})

指令参数详解

每个钩子函数都接收以下参数：

• el：指令所绑定的元素
• binding：包含多个属性的对象
  • name：指令名（不包含 v- 前缀）
  • value：指令的绑定值
  • oldValue：指令绑定的前一个值
  • expression：字符串形式的指令表达式
  • arg：传给指令的参数
  • modifiers：包含修饰符的对象

Vue.directive('demo', {
  bind(el, binding) {
    console.log(binding.value)    // => "hello"
    console.log(binding.oldValue)  // => undefined
    console.log(binding.arg)       // => "foo"
    console.log(binding.modifiers) // => { bar: true }
  }
})

// 使用示例
<div v-demo:foo.bar="'hello'"></div>

动态指令参数

指令的参数可以是动态的，这在需要响应式更新指令行为时特别有用：

<div v-pin:[direction]="200">我会被固定在页面上</div>

Vue.directive('pin', {
  bind(el, binding) {
    el.style.position = 'fixed'
    const direction = binding.arg || 'top'
    el.style[direction] = binding.value + 'px'
  },
  update(el, binding) {
    const direction = binding.arg || 'top'
    el.style[direction] = binding.value + 'px'
  }
})

new Vue({
  data() {
    return {
      direction: 'left'
    }
  }
})

指令的复用与组合

自定义指令可以组合使用，实现复杂功能。例如实现一个同时具备权限检查和聚焦功能的指令：

Vue.directive('auth-focus', {
  inserted(el, binding) {
    const hasPermission = checkPermission(binding.value)
    if (hasPermission) {
      el.focus()
    } else {
      el.disabled = true
    }
  }
})

function checkPermission(permission) {
  // 实际项目中这里会有更复杂的权限检查逻辑
  return ['admin', 'editor'].includes(permission)
}

指令与组件通信

指令可以通过组件实例访问组件的数据和方法：

Vue.directive('tooltip', {
  bind(el, binding, vnode) {
    const vm = vnode.context
    el.addEventListener('mouseenter', () => {
      vm.$refs.tooltip.show(binding.value)
    })
    el.addEventListener('mouseleave', () => {
      vm.$refs.tooltip.hide()
    })
  }
})

性能优化技巧

指令中的 DOM 操作可能会影响性能，需要注意优化：

Vue.directive('lazy-load', {
  inserted(el, binding) {
    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          el.src = binding.value
          observer.unobserve(el)
        }
      })
    })
    observer.observe(el)
  }
})

指令与 Vue 3 的组合式 API

在 Vue 3 中，指令的定义方式有所变化，更符合组合式 API 的风格：

const app = createApp({})

app.directive('highlight', {
  beforeMount(el, binding) {
    // Vue 3 中将 bind 改为 beforeMount
    el.style.backgroundColor = binding.value
  },
  updated(el, binding) {
    // 更新逻辑
    el.style.backgroundColor = binding.value
  }
})

复杂指令示例：拖拽指令

实现一个完整的拖拽功能指令：

Vue.directive('drag', {
  inserted(el) {
    el.style.cursor = 'move'
    el.style.userSelect = 'none'
    
    let startX, startY, initialLeft, initialTop
    
    el.addEventListener('mousedown', startDrag)
    
    function startDrag(e) {
      e.preventDefault()
      startX = e.clientX
      startY = e.clientY
      
      const styles = window.getComputedStyle(el)
      initialLeft = parseInt(styles.left) || 0
      initialTop = parseInt(styles.top) || 0
      
      document.addEventListener('mousemove', drag)
      document.addEventListener('mouseup', stopDrag)
    }
    
    function drag(e) {
      const dx = e.clientX - startX
      const dy = e.clientY - startY
      
      el.style.left = `${initialLeft + dx}px`
      el.style.top = `${initialTop + dy}px`
    }
    
    function stopDrag() {
      document.removeEventListener('mousemove', drag)
      document.removeEventListener('mouseup', stopDrag)
    }
  }
})

指令测试策略

为自定义指令编写测试用例：

import { mount } from '@vue/test-utils'
import directive from '@/directives/highlight'

test('highlight directive applies color', () => {
  const wrapper = mount({
    template: '<div v-highlight="\'yellow\'"></div>'
  }, {
    global: {
      directives: {
        highlight: directive
      }
    }
  })
  
  expect(wrapper.element.style.backgroundColor).toBe('yellow')
})

指令与 TypeScript

在 TypeScript 项目中定义指令：

import { DirectiveBinding } from 'vue'

interface HighlightDirectiveBinding extends DirectiveBinding {
  value: string
}

export default {
  mounted(el: HTMLElement, binding: HighlightDirectiveBinding) {
    el.style.backgroundColor = binding.value
  },
  updated(el: HTMLElement, binding: HighlightDirectiveBinding) {
    el.style.backgroundColor = binding.value
  }
}

全局指令与局部指令

比较全局注册和局部注册的区别：

// 全局指令
Vue.directive('global-dir', {
  // 选项
})

// 局部指令
const component = {
  directives: {
    'local-dir': {
      // 选项
    }
  },
  template: '<div v-local-dir></div>'
}

指令的生命周期变化

Vue 2 和 Vue 3 中指令生命周期的对比：

自定义指令的最佳实践

1. 保持指令单一职责：每个指令只做一件事
2. 考虑可访问性：确保指令不影响屏幕阅读器等辅助工具
3. 提供默认值：为可选参数提供合理的默认值
4. 处理边界情况：考虑指令在不同浏览器和场景下的表现
5. 文档化指令：为自定义指令编写清晰的文档说明

/**
 * v-debounce 防抖指令
 * @param {Function} value - 需要防抖的函数
 * @param {number} [delay=300] - 延迟时间(ms)
 * @param {boolean} [immediate=false] - 是否立即执行
 */
Vue.directive('debounce', {
  inserted(el, binding) {
    const { value, modifiers } = binding
    const delay = modifiers.delay || 300
    const immediate = modifiers.immediate || false
    
    let timer = null
    el.addEventListener('input', () => {
      if (timer) clearTimeout(timer)
      if (immediate && !timer) {
        value()
      }
      timer = setTimeout(() => {
        if (!immediate) {
          value()
        }
        timer = null
      }, delay)
    })
  }
})