Vue 3 自定义指令开发

1. 自定义指令概述

自定义指令（Custom Directives）是Vue中用于扩展HTML元素功能的机制，允许开发者在DOM元素上添加自定义行为。在Vue 3中，自定义指令可以通过全局注册或局部注册的方式使用，它提供了一种灵活的方式来操作DOM元素。

1.1 为什么需要自定义指令

虽然Vue鼓励使用组件化开发，但在某些情况下，我们需要直接操作DOM元素，例如：

• 自动聚焦输入框
• 滚动到指定位置
• 实现拖拽功能
• 集成第三方库
• 添加自定义动画效果
• 实现权限控制

1.2 Vue 3自定义指令的特点

Vue 3的自定义指令具有以下特点：

• 组合式API支持：在组合式API中可以使用自定义指令
• 生命周期钩子：提供了完整的生命周期钩子，如created、mounted、updated等
• 灵活的注册方式：支持全局注册和局部注册
• 类型安全：在TypeScript环境下，支持类型推断和类型检查
• 支持多个修饰符：可以通过修饰符扩展指令的功能
• 支持动态参数：可以根据条件动态改变指令的参数

2. 自定义指令的基本使用

2.1 基本语法

在Vue 3中，自定义指令的基本语法如下：

// 全局注册
const app = createApp(App)

app.directive('focus', {
  // 指令的生命周期钩子
  mounted(el) {
    // 在元素挂载后自动聚焦
    el.focus()
  }
})

// 局部注册
export default {
  directives: {
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}

在模板中，使用v-前缀来使用自定义指令：

<template>
  <input type="text" v-focus placeholder="Auto focus!" />
</template>

2.2 指令的生命周期钩子

Vue 3的自定义指令提供了以下生命周期钩子：

2.3 指令钩子的参数

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

• el：指令绑定的DOM元素
• binding：包含指令信息的对象，具有以下属性：
  • value：指令的绑定值
  • oldValue：指令的旧绑定值（在beforeUpdate和updated钩子中可用）
  • arg：指令的参数
  • modifiers：指令的修饰符对象
  • instance：使用指令的组件实例
  • dir：指令的定义对象
• vnode：虚拟DOM节点
• prevVnode：前一个虚拟DOM节点（在beforeUpdate和updated钩子中可用）

3. 自定义指令的高级使用

3.1 带参数的指令

自定义指令可以接收参数，通过:语法传递：

app.directive('scroll', {
  mounted(el, binding) {
    // 获取指令参数
    const direction = binding.arg || 'top'
    const offset = binding.value || 0
    
    // 根据参数执行不同的滚动操作
    if (direction === 'top') {
      window.scrollTo(0, offset)
    } else if (direction === 'left') {
      window.scrollTo(offset, 0)
    }
  }
})

在模板中使用：

<template>
  <div v-scroll:top="100">Scroll to top 100px</div>
  <div v-scroll:left="200">Scroll to left 200px</div>
</template>

3.2 带修饰符的指令

自定义指令可以使用修饰符，通过.语法传递：

app.directive('color', {
  mounted(el, binding) {
    // 获取修饰符
    const { red, blue, green } = binding.modifiers
    
    // 根据修饰符设置颜色
    if (red) {
      el.style.color = 'red'
    } else if (blue) {
      el.style.color = 'blue'
    } else if (green) {
      el.style.color = 'green'
    } else {
      // 使用绑定值作为颜色
      el.style.color = binding.value || 'black'
    }
  }
})

在模板中使用：

<template>
  <div v-color.red>Red text</div>
  <div v-color.blue>Blue text</div>
  <div v-color="'purple'">Purple text</div>
</template>

3.3 动态参数

自定义指令可以使用动态参数，通过[ ]语法传递：

app.directive('dynamic', {
  mounted(el, binding) {
    // 获取动态参数
    const prop = binding.arg
    const value = binding.value
    
    // 设置元素的属性或样式
    if (prop) {
      el.style[prop] = value
    }
  }
})

在模板中使用：

<template>
  <div v-dynamic:[prop]="value">Dynamic style</div>
</template>

<script>
export default {
  setup() {
    const prop = ref('fontSize')
    const value = ref('20px')
    
    return {
      prop,
      value
    }
  }
}
</script>

4. 自定义指令的生命周期钩子详解

4.1 created

created钩子在指令绑定到元素后，在属性或事件监听器应用之前执行。这个钩子主要用于初始化工作，例如设置元素的初始状态。

app.directive('init', {
  created(el, binding) {
    // 设置元素的初始文本
    el.textContent = binding.value || 'Initial text'
  }
})

4.2 beforeMount

beforeMount钩子在元素插入DOM之前执行。这个钩子主要用于准备工作，例如获取元素的初始尺寸。

app.directive('measure', {
  beforeMount(el) {
    // 记录元素的初始尺寸
    const rect = el.getBoundingClientRect()
    console.log('Initial size:', rect.width, rect.height)
  }
})

4.3 mounted

mounted钩子在元素插入DOM之后执行。这个钩子主要用于DOM操作，例如自动聚焦、滚动到指定位置等。

app.directive('scroll-to', {
  mounted(el, binding) {
    // 滚动到指定元素
    el.scrollIntoView({
      behavior: binding.value?.behavior || 'smooth',
      block: binding.value?.block || 'start',
      inline: binding.value?.inline || 'nearest'
    })
  }
})

4.4 beforeUpdate

beforeUpdate钩子在元素更新之前执行。这个钩子主要用于获取更新前的DOM状态。

app.directive('track-update', {
  beforeUpdate(el, binding) {
    // 记录更新前的文本内容
    console.log('Before update:', el.textContent)
  }
})

4.5 updated

updated钩子在元素更新之后执行。这个钩子主要用于处理更新后的DOM状态。

app.directive('highlight', {
  updated(el, binding) {
    // 根据条件高亮元素
    if (binding.value) {
      el.style.backgroundColor = 'yellow'
    } else {
      el.style.backgroundColor = ''
    }
  }
})

4.6 beforeUnmount

beforeUnmount钩子在元素从DOM中移除之前执行。这个钩子主要用于清理工作，例如移除事件监听器、清除定时器等。

app.directive('countdown', {
  mounted(el, binding) {
    // 启动倒计时
    const endTime = binding.value
    const timer = setInterval(() => {
      const now = new Date().getTime()
      const remaining = Math.max(0, Math.floor((endTime - now) / 1000))
      el.textContent = `Remaining: ${remaining}s`
      
      if (remaining === 0) {
        clearInterval(timer)
      }
    }, 1000)
    
    // 保存定时器到元素上
    el._countdownTimer = timer
  },
  
  beforeUnmount(el) {
    // 清理定时器
    if (el._countdownTimer) {
      clearInterval(el._countdownTimer)
    }
  }
})

4.7 unmounted

unmounted钩子在元素从DOM中移除之后执行。这个钩子主要用于最终的清理工作。

app.directive('external-resource', {
  mounted(el, binding) {
    // 加载外部资源
    const script = document.createElement('script')
    script.src = binding.value
    document.body.appendChild(script)
    
    // 保存脚本元素到元素上
    el._externalScript = script
  },
  
  unmounted(el) {
    // 移除外部资源
    if (el._externalScript) {
      document.body.removeChild(el._externalScript)
    }
  }
})

5. 自定义指令的注册方式

5.1 全局注册

全局注册的指令可以在整个应用中使用，适合于经常使用的指令：

const app = createApp(App)

// 全局注册单个指令
app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

// 批量注册指令
const directives = {
  focus: {
    mounted(el) {
      el.focus()
    }
  },
  color: {
    mounted(el, binding) {
      el.style.color = binding.value
    }
  }
}

for (const [name, directive] of Object.entries(directives)) {
  app.directive(name, directive)
}

app.mount('#app')

5.2 局部注册

局部注册的指令只能在注册它的组件中使用，适合于特定组件使用的指令：

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

5.3 在组合式API中使用

在组合式API中，可以使用defineDirective函数来定义指令：

import { defineDirective } from 'vue'

export default {
  setup() {
    // 定义指令
    const focusDirective = defineDirective({
      mounted(el) {
        el.focus()
      }
    })
    
    return {
      // ...
    }
  },
  
  directives: {
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}

6. 自定义指令的最佳实践

6.1 只在必要时使用

虽然自定义指令很强大，但也不要过度使用，否则会导致以下问题：

• 违背声明式编程原则：直接操作DOM会使代码更难维护和测试
• 耦合度高：组件与DOM元素的实现细节耦合在一起
• 性能问题：频繁操作DOM可能会导致性能问题
• 难以测试：自定义指令的行为难以模拟和测试

建议只在以下情况下使用自定义指令：

• 需要直接操作DOM元素
• 功能与元素紧密相关，不适合封装成组件
• 多个组件需要共享相同的DOM操作逻辑

6.2 保持指令的简洁性

自定义指令应该保持简洁，只负责单一功能：

// 好的做法：指令只负责单一功能
app.directive('focus', {
  mounted(el) {
    el.focus()
  }
})

// 不好的做法：指令负责多个功能
app.directive('complex', {
  mounted(el, binding) {
    // 功能1：聚焦
    if (binding.modifiers.focus) {
      el.focus()
    }
    
    // 功能2：设置颜色
    if (binding.modifiers.color) {
      el.style.color = binding.value
    }
    
    // 功能3：设置字体大小
    if (binding.modifiers.size) {
      el.style.fontSize = binding.arg
    }
  }
})

6.3 清理资源

在指令的生命周期钩子中，特别是在beforeUnmount和unmounted钩子中，一定要清理资源，如事件监听器、定时器、外部资源等：

app.directive('interval', {
  mounted(el, binding) {
    // 启动定时器
    const timer = setInterval(() => {
      // 执行操作
      el.textContent = new Date().toLocaleTimeString()
    }, binding.value || 1000)
    
    // 保存定时器到元素上
    el._intervalTimer = timer
  },
  
  beforeUnmount(el) {
    // 清理定时器
    if (el._intervalTimer) {
      clearInterval(el._intervalTimer)
    }
  }
})

6.4 使用修饰符扩展功能

使用修饰符来扩展指令的功能，提高指令的灵活性：

app.directive('click-outside', {
  mounted(el, binding) {
    // 定义点击外部的处理函数
    const handleClickOutside = (event) => {
      // 如果点击的是元素内部，不执行操作
      if (el.contains(event.target)) {
        return
      }
      
      // 如果有once修饰符，只执行一次
      if (binding.modifiers.once) {
        document.removeEventListener('click', handleClickOutside)
      }
      
      // 执行绑定的函数
      binding.value(event)
    }
    
    // 保存处理函数到元素上
    el._handleClickOutside = handleClickOutside
    
    // 添加事件监听器
    document.addEventListener('click', handleClickOutside)
  },
  
  beforeUnmount(el) {
    // 移除事件监听器
    if (el._handleClickOutside) {
      document.removeEventListener('click', el._handleClickOutside)
    }
  }
})

在模板中使用：

<template>
  <div v-click-outside.once="handleClickOutside">
    Click outside me!
  </div>
</template>

6.5 支持TypeScript类型检查

在TypeScript环境下，为自定义指令添加类型定义，提高类型安全性：

// types/directives.d.ts
declare module 'vue' {
  interface GlobalComponents {
    // 组件类型定义
  }
  
  interface Directive {
    // 扩展指令类型
    focus?: Directive
    color?: Directive
  }
}

export {}

// directive.ts
import type { Directive } from 'vue'

export const focusDirective: Directive = {
  mounted(el) {
    el.focus()
  }
}

7. 自定义指令的高级应用

7.1 实现拖拽功能

使用自定义指令实现拖拽功能：

app.directive('drag', {
  mounted(el) {
    let isDragging = false
    let startX = 0
    let startY = 0
    let initialX = 0
    let initialY = 0
    
    // 设置元素的初始样式
    el.style.position = 'absolute'
    
    // 鼠标按下事件
    const handleMouseDown = (e: MouseEvent) => {
      isDragging = true
      startX = e.clientX
      startY = e.clientY
      initialX = el.offsetLeft
      initialY = el.offsetTop
      
      document.addEventListener('mousemove', handleMouseMove)
      document.addEventListener('mouseup', handleMouseUp)
    }
    
    // 鼠标移动事件
    const handleMouseMove = (e: MouseEvent) => {
      if (!isDragging) return
      
      const dx = e.clientX - startX
      const dy = e.clientY - startY
      
      el.style.left = `${initialX + dx}px`
      el.style.top = `${initialY + dy}px`
    }
    
    // 鼠标释放事件
    const handleMouseUp = () => {
      isDragging = false
      document.removeEventListener('mousemove', handleMouseMove)
      document.removeEventListener('mouseup', handleMouseUp)
    }
    
    // 添加事件监听器
    el.addEventListener('mousedown', handleMouseDown)
    
    // 保存事件处理函数到元素上
    el._dragHandlers = {
      handleMouseDown,
      handleMouseMove,
      handleMouseUp
    }
  },
  
  beforeUnmount(el) {
    // 移除事件监听器
    if (el._dragHandlers) {
      el.removeEventListener('mousedown', el._dragHandlers.handleMouseDown)
      document.removeEventListener('mousemove', el._dragHandlers.handleMouseMove)
      document.removeEventListener('mouseup', el._dragHandlers.handleMouseUp)
    }
  }
})

在模板中使用：

<template>
  <div v-drag style="width: 100px; height: 100px; background-color: red; cursor: move;">
    Drag me!
  </div>
</template>

7.2 实现权限控制

使用自定义指令实现权限控制：

app.directive('permission', {
  mounted(el, binding) {
    // 获取当前用户的权限
    const userPermissions = ['read', 'write', 'delete']
    
    // 检查用户是否有指定的权限
    const hasPermission = userPermissions.includes(binding.value)
    
    // 如果没有权限，隐藏元素
    if (!hasPermission) {
      el.style.display = 'none'
    }
  }
})

在模板中使用：

<template>
  <button v-permission="'write'">编辑</button>
  <button v-permission="'delete'">删除</button>
</template>

7.3 实现无限滚动

使用自定义指令实现无限滚动功能：

app.directive('infinite-scroll', {
  mounted(el, binding) {
    // 监听滚动事件
    const handleScroll = () => {
      // 计算元素的滚动位置
      const scrollTop = el.scrollTop
      const scrollHeight = el.scrollHeight
      const clientHeight = el.clientHeight
      
      // 如果滚动到底部，执行绑定的函数
      if (scrollTop + clientHeight >= scrollHeight - 100) {
        binding.value()
      }
    }
    
    // 添加事件监听器
    el.addEventListener('scroll', handleScroll)
    
    // 保存事件处理函数到元素上
    el._infiniteScrollHandler = handleScroll
  },
  
  beforeUnmount(el) {
    // 移除事件监听器
    if (el._infiniteScrollHandler) {
      el.removeEventListener('scroll', el._infiniteScrollHandler)
    }
  }
})

在模板中使用：

<template>
  <div 
    v-infinite-scroll="loadMore" 
    style="height: 300px; overflow-y: auto;"
  >
    <div v-for="item in items" :key="item.id" style="padding: 10px; margin: 5px; border: 1px solid #ccc;">
      {{ item.name }}
    </div>
  </div>
</template>

<script>
export default {
  setup() {
    const items = ref([])
    let page = 1
    
    const loadMore = () => {
      // 模拟加载更多数据
      for (let i = 0; i < 10; i++) {
        items.value.push({
          id: page * 10 + i,
          name: `Item ${page * 10 + i}`
        })
      }
      page++
    }
    
    // 初始加载数据
    loadMore()
    
    return {
      items,
      loadMore
    }
  }
}
</script>

8. 自定义指令的性能优化

8.1 避免频繁操作DOM

避免在指令的生命周期钩子中频繁操作DOM，特别是在updated钩子中：

// 好的做法：使用防抖函数
app.directive('debounce', {
  mounted(el, binding) {
    let timeout = null
    
    const handleInput = () => {
      clearTimeout(timeout)
      timeout = setTimeout(() => {
        binding.value(el.value)
      }, binding.arg || 300)
    }
    
    el.addEventListener('input', handleInput)
    el._debounceHandler = handleInput
  },
  
  beforeUnmount(el) {
    if (el._debounceHandler) {
      el.removeEventListener('input', el._debounceHandler)
    }
  }
})

// 不好的做法：频繁操作DOM
app.directive('direct-update', {
  updated(el, binding) {
    // 每次更新都操作DOM
    el.textContent = binding.value
  }
})

8.2 使用IntersectionObserver优化滚动事件

对于滚动相关的指令，使用IntersectionObserver替代scroll事件，提高性能：

app.directive('lazy-load', {
  mounted(el, binding) {
    // 创建IntersectionObserver实例
    const observer = new IntersectionObserver((entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          // 当元素进入视口时，加载图片
          el.src = binding.value
          // 停止观察
          observer.unobserve(el)
        }
      })
    })
    
    // 开始观察元素
    observer.observe(el)
    
    // 保存observer到元素上
    el._lazyLoadObserver = observer
  },
  
  beforeUnmount(el) {
    // 停止观察
    if (el._lazyLoadObserver) {
      el._lazyLoadObserver.disconnect()
    }
  }
})

8.3 缓存计算结果

对于需要频繁计算的指令，缓存计算结果，避免重复计算：

app.directive('cache', {
  mounted(el, binding) {
    // 缓存计算结果
    const cache = new Map()
    
    const compute = (value) => {
      if (cache.has(value)) {
        return cache.get(value)
      }
      
      // 复杂的计算逻辑
      const result = value * 2 + 1
      cache.set(value, result)
      
      return result
    }
    
    el.textContent = compute(binding.value)
    el._compute = compute
  },
  
  updated(el, binding) {
    // 使用缓存的计算结果
    el.textContent = el._compute(binding.value)
  }
})

9. 实战练习

练习1：实现自动聚焦指令

创建一个自定义指令v-focus，当元素挂载后自动聚焦：

• 全局注册该指令
• 在模板中使用该指令
• 测试自动聚焦效果

练习2：实现颜色切换指令

创建一个自定义指令v-color，可以根据绑定值和修饰符设置元素的颜色：

• 支持直接设置颜色值：v-color="'red'"
• 支持修饰符：v-color.red, v-color.blue
• 支持动态颜色：v-color="dynamicColor"

练习3：实现滚动到指定位置指令

创建一个自定义指令v-scroll-to，点击元素时滚动到指定位置：

• 支持滚动到顶部：v-scroll-to="'top'"
• 支持滚动到底部：v-scroll-to="'bottom'"
• 支持滚动到指定元素：v-scroll-to="elementRef"
• 支持平滑滚动：v-scroll-to:smooth="'top'"

10. 总结

自定义指令是Vue 3中用于扩展HTML元素功能的强大机制，它具有以下特点：

• 提供了完整的生命周期钩子，如created、mounted、updated等
• 支持全局注册和局部注册
• 支持参数、修饰符和动态参数
• 可以直接操作DOM元素
• 适合于实现跨组件的DOM操作逻辑
• 支持TypeScript类型检查

掌握自定义指令的使用方法和最佳实践，是编写可靠、高效Vue应用的关键。通过合理使用自定义指令，可以在组件化开发的基础上，灵活地扩展HTML元素的功能，实现复杂的交互效果。

11. 扩展阅读

• Vue 3 自定义指令官方文档
• Vue 3 指令API
• Vue 3 TypeScript支持
• DOM操作最佳实践

通过本集的学习，我们深入理解了Vue 3中自定义指令的开发方法和最佳实践。在下一集中，我们将学习插件开发与使用，这是Vue中用于扩展Vue应用功能的重要机制。