1. 前言

在 Vue3 的开发生态中，自定义指令是一项极为灵活且强大的功能，它允许开发者对 DOM 元素进行底层操作，实现复用性高的特定逻辑。结合 TypeScript（TS）强类型的特性，能让自定义指令的开发更加规范、安全，减少运行时错误。本文将深入讲解基于 Vue3 + TS 的自定义指令开发，并通过实际的业务场景做一些示例。

2. 基础概念与优势

在 Vue 中，指令（Directives）是以v-为前缀的特殊属性，用于在模板中实现对 DOM 的操作。除了 Vue 自带的指令（如v-bind、v-on），开发者还可以根据业务需求创建自定义指令。自定义指令的核心作用是抽象出可复用的 DOM 操作逻辑，将其封装在指令中，在不同组件中重复使用，从而提高代码的复用性和开发效率。

Vue3 + TS 开发自定义指令的优势：

类型安全：TypeScript 的强类型系统能在开发阶段就检测出类型不匹配等错误，避免因数据类型问题导致的运行时错误。例如，在定义指令的钩子函数参数类型时，明确的类型声明能让开发者更清晰地知道每个参数的用途和数据类型，同时在编辑器中获得智能提示，提升编码效率。
代码规范与维护性：TS 的类型定义和接口约束，能让代码结构更加清晰。团队成员可以通过类型声明快速理解代码意图，降低代码维护成本。在大型项目中，统一的类型规范有助于保持代码风格的一致性，减少沟通成本。
更好的代码重构支持：当项目需求变更，需要对自定义指令进行重构时，TS 强大的类型检查机制能帮助开发者快速定位因代码修改导致的类型错误，确保重构后的代码逻辑正确，降低重构风险。

3. Vue3+TS自定义指令的创建与注册

下面是一个完整的流程示例：

3.1. 创建自定义指令

在 Vue3 中，使用app.directive方法来注册自定义指令。结合 TS，我们可以通过定义接口和类型别名来规范指令的参数和钩子函数。

以下是一个简单的示例，创建一个自定义指令v-focus，用于在元素插入 DOM 时自动获取焦点：

import { App, Directive, DirectiveBinding } from 'vue';

// 定义指令钩子函数的参数类型
interface FocusDirectiveBinding extends DirectiveBinding {value: boolean;
}

// 创建自定义指令
const focusDirective: Directive<HTMLElement, FocusDirectiveBinding> = {// 当指令绑定到元素时调用mounted(el: HTMLElement, binding: FocusDirectiveBinding) {if (binding.value) {el.focus();}}
};

export default focusDirective;

在上述代码中：

首先导入了App、Directive和DirectiveBinding等类型，用于定义指令相关的类型和接口。
接着定义了FocusDirectiveBinding接口，扩展了DirectiveBinding，明确了指令绑定值value的类型为boolean。
然后创建了focusDirective，它是一个实现了Directive接口的对象，包含了mounted钩子函数。在mounted钩子中，根据binding.value的值判断是否让元素获取焦点。

3.2. 注册自定义指令

注册自定义指令有两种方式：全局注册和局部注册。

全局注册：在main.ts文件中，将自定义指令注册到整个 Vue 应用中，使其在所有组件中都可用。

import { createApp } from 'vue';
import App from './App.vue';
import focusDirective from './directives/focus';

const app = createApp(App);
app.directive('focus', focusDirective);
app.mount('#app');

局部注册：在组件内部注册自定义指令，仅在当前组件及其子组件中生效。

	<template><input v-focus="isFocused" type="text" /></template><script lang="ts">import { defineComponent } from 'vue';import focusDirective from '../directives/focus';export default defineComponent({directives: {focus: focusDirective},data() {return {isFocused: true};}});
</script>

4. 实际场景示例

下面列举了几个使用例子，都是开发过程中会碰到的典型示例。

4.1. 权限指令控制

在企业级应用中，经常需要根据用户的权限来控制某些 DOM 元素的显示或隐藏。例如，只有管理员用户才能看到删除按钮，普通用户则隐藏该按钮。

import { App, Directive, DirectiveBinding } from 'vue';

// 定义权限指令的绑定值类型
interface PermissionDirectiveBinding extends DirectiveBinding {value: string[];
}

// 创建权限指令
const permissionDirective: Directive<HTMLElement, PermissionDirectiveBinding> = {mounted(el: HTMLElement, binding: PermissionDirectiveBinding) {const userPermissions = ['admin']; // 模拟用户权限列表const requiredPermissions = binding.value;if (!userPermissions.some(p => requiredPermissions.includes(p))) {el.style.display = 'none';}}
};

export default permissionDirective;

在模板中使用该指令：

<template><button v-permission="['admin']">删除</button>
</template>

4.2. 图片懒加载指令

在图片较多的页面，使用懒加载可以提升页面加载性能。通过自定义指令实现图片的懒加载功能：

import { App, Directive, DirectiveBinding } from 'vue';
import { IntersectionObserver } from '@w3c/IntersectionObserver';

// 定义懒加载指令的绑定值类型
interface LazyLoadDirectiveBinding extends DirectiveBinding {value: string;
}

// 创建懒加载指令
const lazyLoadDirective: Directive<HTMLImageElement, LazyLoadDirectiveBinding> = {mounted(el: HTMLImageElement, binding: LazyLoadDirectiveBinding) {const observer = new IntersectionObserver(([entry]) => {if (entry.isIntersecting) {el.src = binding.value;observer.unobserve(el);}});observer.observe(el);}
};

export default lazyLoadDirective;

在模板中使用该指令：

<template><img v-lazy-load="imageUrl" alt="懒加载图片" />
</template>

5. 优化与注意事项

缓存 DOM 操作：在指令的钩子函数中，如果涉及多次对 DOM 元素的相同操作，可以将结果缓存起来，避免重复计算，提升性能。例如，在计算元素的位置或尺寸时，可以将结果存储在变量中，后续使用时直接读取。
事件解绑：在unmounted钩子函数中，要记得解绑在mounted钩子中添加的事件监听器，防止内存泄漏。比如在上述懒加载指令中，使用IntersectionObserver观察元素时，在元素不再需要观察时，调用unobserve方法解除观察。
指令参数类型检查：在指令的钩子函数中，要对传入的参数进行严格的类型检查和合法性验证，避免因参数错误导致的异常。例如，在权限指令中，确保binding.value是一个数组类型，并且数组元素是字符串类型。
指令命名规范：自定义指令的命名要遵循一定的规范，建议采用v-前缀加上有意义的名称，方便团队成员理解和使用。同时，命名要避免与 Vue 自带的指令或项目中已有的指令冲突。

本次分享就到这儿啦，我是鹏多多，如果您看了觉得有帮助，欢迎评论，关注，点赞，转发，我们下次见~

往期文章