如何实现Vue3自定义指令的TypeScript修饰符编译时类型校验

核心思路 #

Vue3默认不会对自定义指令的修饰符做类型校验，要实现未知修饰符触发TS编译错误的需求，需通过扩展Vue的全局自定义指令类型，为指定指令绑定专属的修饰符联合类型，同时约束指令的参数类型。

具体步骤 #

1. 定义专属类型并扩展Vue全局接口 #

创建类型声明文件（比如src/types/directives.ts），在其中指定允许的修饰符类型，并扩展Vue的ComponentCustomDirectives接口：

import type { Directive } from 'vue';

// 定义当前指令允许的修饰符
type MyCustomDirectiveKnownModifiers = 'foo' | 'bar';

// 扩展Vue全局自定义指令类型，为指定指令绑定修饰符约束
declare module 'vue' {
  interface ComponentCustomDirectives {
    'my-custom-directive': Directive<HTMLElement, unknown, MyCustomDirectiveKnownModifiers>;
  }
}

2. 实现自定义指令逻辑 #

在指令注册文件（比如src/directives/index.ts）中编写指令逻辑，此时binding参数的modifiers属性会自动继承我们定义的类型约束：

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

const app = createApp(App);

app.directive('my-custom-directive', {
  mounted(el, binding) {
    // 合法访问：TS不会报错
    if (binding.modifiers.foo) {
      el.style.color = 'red';
    }
    if (binding.modifiers.bar) {
      el.style.fontSize = '20px';
    }
    // 非法访问：直接触发TS编译错误
    // if (binding.modifiers.baz) {}
  },
});

app.mount('#app');

3. 模板中的类型校验效果 #

在Vue单文件组件模板中使用指令时：

• 合法用法（无TS错误）：

  <div v-my-custom-directive.foo />
  <div v-my-custom-directive.bar />
  <div v-my-custom-directive.foo.bar />
  

• 非法用法（触发TS编译错误）：

  <div v-my-custom-directive.baz /> <!-- TS提示：属性“baz”不存在于类型“Record<MyCustomDirectiveKnownModifiers, boolean>”上 -->
  

关键说明 #

• 不要直接全局扩展DirectiveBinding类型，否则会影响所有自定义指令的类型校验，通过ComponentCustomDirectives为单个指令指定类型更精准。
• 确保tsconfig.json的include数组包含你的类型声明文件，比如"include": ["src/**/*"]，让TS能识别到扩展的类型。

内容的提问来源于stack exchange，提问作者amtc