Vue SFC 中可直接在 components 选项的 directives 对象内定义局部指令,如 focus,模板中用 v-focus;钩子函数 mounted(Vue 3)或 inserted(Vue 2)接收 el 和 binding,支持参数、值与修饰符,作用域限于当前组件。

在 Vue 单文件组件(SFC)中编写自定义指令操作 DOM 元素,不需要全局注册,直接在组件内部定义局部指令即可。它轻量、作用域明确,适合只在当前组件或其子组件中复用的 DOM 行为。
在 components 选项里声明 directives
Vue 2 和 Vue 3 的单文件组件都支持通过 components 选项中的 directives 对象 定义局部指令。注意不是写在 methods 或 data 里,而是作为组件配置项之一:
- 指令名不带 v- 前缀,比如定义 focus,模板中使用 v-focus
- 每个指令是一个对象,包含生命周期钩子函数,最常用的是 mounted(Vue 3)或 inserted(Vue 2)
- 钩子函数接收两个参数:el(绑定的 DOM 元素)和 binding(含 value、arg、modifiers 等信息)
一个自动聚焦输入框的完整示例
以下是在 .vue 文件中实现 v-focus 指令的标准写法(兼容 Vue 3 Composition API + Options API 风格):
<template>
<input v-focus placeholder="一渲染就聚焦" />
</template>
<p><script>
export default {
directives: {
focus: {
mounted(el) {
el.focus()
// 可选:加个视觉反馈
el.style.outline = '2px solid #42b883'
}
}
}
}
</script>带参数和修饰符的进阶用法
指令可以接收参数(如 v-focus.arg)、值(v-focus="true")和修饰符(v-focus.lazy)。在 mounted 中通过 binding 解构获取:
立即学习“前端免费学习笔记(深入)”;
- binding.value:指令等号后的值,比如 v-focus="false" → false
- binding.arg:点号后的参数,比如 v-focus:select → arg 是 'select'
- binding.modifiers:修饰符对象,比如 v-focus.lazy → { lazy: true }
例如,实现“聚焦后自动选中文本”:
focus: {
mounted(el, binding) {
if (binding.arg === 'select' && binding.value !== false) {
el.focus()
el.select()
}
}
}模板中可写成:<input v-focus:select="true">
注意事项和常见坑
局部指令只在当前组件内生效,子组件无法直接使用(除非显式透传或也定义同名指令)。另外要注意:
- 不要在 mounted 中做异步操作后修改 el(如 setTimeout 后 focus),因为 el 可能已被移除或失活
- 如果需要响应数据变化更新 DOM,用 updated 钩子,但要小心无限循环(避免在 updated 里改触发更新的响应式数据)
- Vue 3 中推荐用 mounted 替代旧版的 inserted;Vue 2 仍可用 inserted,但 mounted 更语义清晰
- 指令不能访问 this,如需访问组件实例,可通过 binding.instance(Vue 3)或 binding.context(Vue 2,已废弃)——但应尽量避免,保持指令纯净


















