背景与问题界定

Vue3 的自定义指令相比 Vue2 有重大的 API 变更——钩子函数从 bind/inserted/update 等 5 个调整为 created/mounted/updated/unmounted 等统一生命周期风格。这一变化让指令的行为更加可预测，但也带来了迁移成本。在实际项目中，自定义指令的编排能力经常被低估：许多可以在指令层面优雅解决的问题，开发者在组件内用 watch 和 onMounted 手动实现了。例如表单页面的自动聚焦需要遍历所有输入框 DOM；按钮级别的权限控制需要在每个模板片段中写 v-if="hasPermission('xxx')"；滚动加载大量监听器散落在各个组件的 setup 中。这些问题可以通过精心设计的自定义指令系统化解决，同时减少模板中的逻辑噪声。

目标拆解与工程约束

  • 指令的响应式参数绑定：指令值应支持响应式变量，当变量变化时指令行为自动更新，不需要手动更新 DOM。
  • 资源生命周期管理：指令绑定的 DOM 事件监听器、IntersectionObserver、定时器等资源必须在指令 unmounted 时完全释放。
  • 指令组合：多个指令作用于同一元素时不应相互冲突，例如 v-focus 和 v-tooltip 同时作用在一个输入框上应各自正常工作。
  • 指令可测试：支持通过 @vue/test-utils 的 attachTo 挂载指令到真实 DOM，独立验证指令的 DOM 操作结果。

方案设计

我们将自定义指令分为三个层级：通用工具指令、业务增强指令 和 权限编排指令。

通用工具指令包括 v-focus 自动聚焦、v-debounce 防抖输入、v-click-outside 点击外部关闭等。这些指令只依赖标准的 DOM API，不引入任何业务逻辑，可以作为一个独立的 npm 包维护：

// v-debounce 示例
const vDebounce: Directive = {
  mounted(el: HTMLInputElement, binding) {
    const delay = binding.value ?? 300
    let timer: ReturnType<typeof setTimeout> | null = null

    el.addEventListener('input', (e: Event) => {
      if (timer) clearTimeout(timer)
      const target = e.target as HTMLInputElement
      timer = setTimeout(() => {
        el.dispatchEvent(new CustomEvent('debounce-update', {
          detail: { value: target.value }
        }))
      }, delay)
    })
  },
  unmounted() {
    // 全局注册时 Vue 自动处理，独立使用时需自行清理
  }
}

业务增强指令处理常见的业务模式。例如 v-ellipsis 实现可展开的多行文本截断，v-infinite-scroll 提供列表触底加载。这些指令将特定的业务交互逻辑封装到指令层，保持组件的模板干净。

权限控制指令是自定义指令在大型应用中的杀手级应用。通过 v-permission="'user:edit'" 的声明式语法，实现按钮级别的权限控制：

const vPermission: Directive<HTMLElement, string | string[]> = {
  mounted(el, binding, vnode) {
    const requiredPerms = Array.isArray(binding.value) ? binding.value : [binding.value]
    const hasPerm = requiredPerms.every(p =>
      (vnode.appContext as any)?.config?.globalProperties?.$perms?.includes(p)
    )
    if (!hasPerm) {
      el.parentNode?.removeChild(el)
    }
  },
  updated(el, binding, vnode) {
    // 响应式权限变更时重新检查
    const requiredPerms = Array.isArray(binding.value) ? binding.value : [binding.value]
    const hasPerm = requiredPerms.every(p =>
      (vnode.appContext as any)?.config?.globalProperties?.$perms?.includes(p)
    )
    if (!hasPerm && el.parentNode) {
      el.parentNode.removeChild(el)
    }
  }
}

对于指令组合的场景，我们遵循 Vue3 的指令设计哲学：每个指令只关心自己绑定的元素，不依赖其他指令的存在。如果需要指令间的协调，通过共享元素的自定义 dataset 属性来实现。

实施路径与关键决策

  • 全局注册 vs 局部注册：通用工具指令全局注册，业务指令在模块内局部注册，避免全局污染。
  • 指令值设计：简单场景用 v-dir="value"，多参数场景用对象格式 v-dir="{ delay: 500, immediate: true }"。
  • 指令测试方案：利用 @vue/test-utils 的 mount + attachTo: document.body 渲染包含指令的元素，通过 fireEvent 验证 DOM 行为。
  • 指令的 Tree Shaking：全局注册的指令如果未被使用，可以通过定义注册函数实现按需引入。

验证指标与可持续迭代

通过审计工具统计项目中 onMounted + querySelector 的模式出现次数，预期减少 70% 以上。指令的单测覆盖率达到 100%，每个指令至少包含"正常使用"、“参数变化”、“卸载清理"三个测试用例。后续迭代方向包括：基于 Vue3 Teleport 的模态框指令，服务端渲染环境下的指令降级策略，以及自定义指令的 DevTools 调试面板。

工程落地思考

自定义指令是 Vue3 中少有的直接操作 DOM 的"硬编码"接口。它提供了一个非常有价值的抽象层次——介于模板和组合函数之间。组合函数负责逻辑，指令负责行为，模板负责声明。当一个交互模式可以简洁地表达为"给这个元素加上某个行为"时，它就是自定义指令的绝佳场景。但在实际项目中，能用组合函数解决的问题不应该用指令——指令的挂载和更新钩子相比组合函数有更多的隐式行为，且不易于单元测试。找到指令和组合函数之间的边界，是判别一个 Vue3 开发者熟练度的重要标志。