Vue核心特性07，深入 Vue 自定义指令：钩子函数、参数传递与注册方式全解析

原创于 2025-12-23 09:37:11 发布 · 588 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#vue.js #javascript #前端

前端同时被 2 个专栏收录

62 篇文章

订阅专栏

VUE

20 篇文章

订阅专栏

2025博客之星年度评选已开启 10w+人浏览 1.8k人参与

在 Vue 的开发体系中，指令是我们操作 DOM 的重要利器。除了v-if、v-for、v-bind这些内置指令外，Vue 还允许我们根据业务需求创建自定义指令，让 DOM 操作更具复用性和灵活性。本文将从钩子函数、参数传递、全局 / 局部注册三个核心维度，全面拆解 Vue 自定义指令的使用方法与实战技巧。

一、自定义指令的核心：钩子函数

自定义指令的本质是一组钩子函数的集合，Vue 为指令提供了多个生命周期钩子，用于在不同阶段执行 DOM 操作。无论是 Vue2 还是 Vue3，钩子函数的核心逻辑一致（仅命名和参数略有调整），我们先以Vue3（组合式 API） 为主进行讲解，最后补充 Vue2 的差异点。

1. Vue3 中的指令钩子函数

Vue3 为自定义指令提供了 6 个钩子函数，每个钩子对应指令的不同生命周期阶段：

钩子函数	触发时机
`created`	指令绑定到元素后立即调用（此时元素还未插入 DOM，无法操作 DOM）
`beforeMount`	指令绑定的元素被挂载到 DOM 之前调用
`mounted`	指令绑定的元素被挂载到 DOM 之后调用（最常用，可执行 DOM 初始化操作）
`beforeUpdate`	包含指令的组件更新之前调用（子组件尚未更新）
`updated`	包含指令的组件更新之后调用（子组件已更新）
`beforeUnmount`	指令绑定的元素被卸载之前调用
`unmounted`	指令绑定的元素被卸载之后调用（可执行清理操作，如移除事件监听）

2. 钩子函数的参数

每个钩子函数都会接收以下 4 个核心参数（参数名可自定义，但顺序固定）：

el：指令绑定的DOM 元素，可以直接操作（如el.style.color = 'red'）。
binding：一个对象，包含指令的绑定信息，核心属性如下：
- value：指令的绑定值（如v-directive="100"，则value为 100）。
- oldValue：指令的旧绑定值（仅在beforeUpdate和updated中可用）。
- arg：指令的参数（如v-directive:foo，则arg为foo）。
- modifiers：指令的修饰符对象（如v-directive.bar，则modifiers为{ bar: true }）。
- instance：使用指令的组件实例（Vue3 新增）。
- dir：指令的定义对象本身。
vnode：Vue 编译生成的虚拟节点。
prevVnode：上一个虚拟节点（仅在beforeUpdate和updated中可用）。

注意：除el外，其他参数都是只读的，不可修改；如果需要共享数据，可通过el的自定义属性实现。

3. 简单示例：实现一个聚焦指令

我们先通过一个经典的v-focus指令，体验钩子函数的使用：

<template>
  <input v-focus type="text" placeholder="自动聚焦输入框" />
</template>

<script setup>
// 定义局部自定义指令（后续会讲全局/局部注册）
const vFocus = {
  // 元素挂载后执行聚焦
  mounted(el) {
    el.focus() // 直接操作DOM元素
  }
}
</script>

上述代码中，我们仅使用了mounted钩子，在输入框挂载到 DOM 后执行聚焦操作，这就是自定义指令的基础用法。

二、自定义指令的灵活度：参数传递

实际开发中，指令往往需要接收动态参数、绑定值或修饰符，以实现更灵活的逻辑。我们通过几个示例来演示参数传递的方式。

1. 传递绑定值（value）

需求：实现一个v-color指令，根据传入的颜色值设置元素文字颜色。

<template>
  <!-- 传递字符串值 -->
  <div v-color="'red'">红色文字</div>
  <!-- 传递响应式变量 -->
  <div v-color="fontColor">动态颜色文字</div>
</template>

<script setup>
import { ref } from 'vue'

const fontColor = ref('blue')

// 定义v-color指令
const vColor = {
  mounted(el, binding) {
    // binding.value 是传入的颜色值
    el.style.color = binding.value
  },
  // 组件更新时，重新设置颜色
  updated(el, binding) {
    el.style.color = binding.value
  }
}
</script>

这里通过binding.value获取指令的绑定值，并在mounted和updated钩子中更新样式，支持静态值和响应式变量。

2. 传递指令参数（arg）

需求：增强v-color指令，支持设置文字颜色或背景颜色（通过参数指定）。

<template>
  <!-- 参数为text，设置文字颜色 -->
  <div v-color:text="'green'">绿色文字</div>
  <!-- 参数为bg，设置背景颜色 -->
  <div v-color:bg="'#f0f0f0'">浅灰色背景</div>
</template>

<script setup>
const vColor = {
  mounted(el, binding) {
    const { value, arg } = binding
    // 根据参数判断设置哪种样式
    if (arg === 'text') {
      el.style.color = value
    } else if (arg === 'bg') {
      el.style.backgroundColor = value
    }
  },
  updated(el, binding) {
    const { value, arg } = binding
    if (arg === 'text') {
      el.style.color = value
    } else if (arg === 'bg') {
      el.style.backgroundColor = value
    }
  }
}
</script>

通过binding.arg获取指令的参数，我们可以让指令根据不同参数执行不同逻辑，扩展指令的功能。

3. 传递指令修饰符（modifiers）

需求：给v-color指令添加修饰符bold，自动设置文字加粗。

<template>
  <!-- 带修饰符bold，文字颜色红色且加粗 -->
  <div v-color:text.bold="'red'">红色加粗文字</div>
</template>

<script setup>
const vColor = {
  mounted(el, binding) {
    const { value, arg, modifiers } = binding
    if (arg === 'text') {
      el.style.color = value
      // 判断是否有bold修饰符
      if (modifiers.bold) {
        el.style.fontWeight = 'bold'
      }
    } else if (arg === 'bg') {
      el.style.backgroundColor = value
    }
  },
  updated(el, binding) {
    // 同上，省略重复代码
  }
}
</script>

binding.modifiers是一个对象，键为修饰符名称，值为true。通过判断修饰符是否存在，我们可以为指令添加额外的行为。

4. 传递多个值：对象形式

如果需要传递多个参数，可以将绑定值设为对象：

<template>
  <div v-style="{ color: 'purple', fontSize: '20px' }">紫色20px文字</div>
</template>

<script setup>
const vStyle = {
  mounted(el, binding) {
    const { color, fontSize } = binding.value
    if (color) el.style.color = color
    if (fontSize) el.style.fontSize = fontSize
  }
}
</script>

三、自定义指令的作用域：全局注册与局部注册

自定义指令的注册方式分为全局注册和局部注册，分别对应不同的作用域场景。

1. 局部注册

局部注册的指令仅在当前组件内可用，是日常开发中最常用的方式，适用于组件专属的指令。

Vue3（组合式 API，`<script setup>`）

在<script setup>中，直接定义以v开头的变量（如vFocus、vColor），即可完成局部注册：

<script setup>
// 局部注册v-focus指令
const vFocus = {
  mounted(el) {
    el.focus()
  }
}
</script>

Vue3（选项式 API）

在组件的directives选项中定义指令：

export default {
  directives: {
    // 局部注册focus指令（使用时为v-focus）
    focus: {
      mounted(el) {
        el.focus()
      }
    }
  }
}

2. 全局注册

全局注册的指令在整个 Vue 应用的所有组件中都可使用，适用于通用型指令（如v-focus、v-loading）。

Vue3（创建应用时注册）

在main.js中通过app.directive方法注册全局指令：

import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

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

// 全局注册v-color指令
app.directive('color', {
  mounted(el, binding) {
    el.style.color = binding.value
  },
  updated(el, binding) {
    el.style.color = binding.value
  }
})

app.mount('#app')

注册后，任何组件都可以直接使用v-focus和v-color指令，无需再局部定义。

3. 注册方式的选择建议

局部注册：推荐用于组件专属的指令，避免全局污染，降低维护成本。
全局注册：适用于项目中多个组件共用的通用指令（如权限控制、加载状态、防抖节流等），但需注意不要过度全局注册，否则会增加应用的初始化开销。

四、Vue2 与 Vue3 的指令钩子差异

如果你还在使用 Vue2，需要注意指令钩子函数的命名和触发时机差异：

Vue2 钩子	Vue3 对应钩子	差异说明
`bind`	`beforeMount`	指令绑定到元素时调用
`inserted`	`mounted`	元素插入父 DOM 时调用
`update`	`beforeUpdate`	组件更新时调用（未更新子组件）
`componentUpdated`	`updated`	组件更新完成时调用（已更新子组件）
`unbind`	`unmounted`	指令与元素解绑时调用