深入理解 Vue 自定义指令--Vue 3 版本

参考文献： Vue.js (vuejs.org)，声明此篇博客是作为vue官方文档的学习笔记

一.什么是自定义指令？

  Vue 中的指令（directive）是带有 v- 前缀的特殊属性，像 v-if、v-model、v-for 是内置指令。

自定义指令允许我们封装复用的 DOM 操作逻辑，比如自动聚焦、设置样式、监听元素变化等

二.自定义指令的使用时机​

只有当所需功能只能通过直接的 DOM 操作来实现时，才应该使用自定义指令。

一个常见例子是使元素获取焦点的 v-focus 指令。

<script setup>
// 在模板中启用 v-focus
const vFocus = {
  mounted: (el) => el.focus()
}
</script>

<template>
  <input v-focus />
</template>

三.指令钩子:和vue3的生命周期函数一样

const myDirective = {
  // 在绑定元素的 attribute 前
  // 或事件监听器应用前调用
  created(el, binding, vnode) {
  },
  // 在元素被插入到 DOM 前调用
  beforeMount(el, binding, vnode) {},
  // 在绑定元素的父组件
  // 及他自己的所有子节点都挂载完成后调用
  mounted(el, binding, vnode) {},
  // 绑定元素的父组件更新前调用
  beforeUpdate(el, binding, vnode, prevVnode) {},
  // 在绑定元素的父组件
  // 及他自己的所有子节点都更新后调用
  updated(el, binding, vnode, prevVnode) {},
  // 绑定元素的父组件卸载前调用
  beforeUnmount(el, binding, vnode) {},
  // 绑定元素的父组件卸载后调用
  unmounted(el, binding, vnode) {}
}

是不是有点懵？下面我们来看看这些参数都代表什么意思

自定义指令接收的参数

el	指令绑定到的元素。这可以用于直接操作 DOM
binding	一个对象，包含以下属性 1.value：传递给指令的值。例如在 v-my-directive="1 + 1" 中，值是 2。 2.oldValue：之前的值，仅在 beforeUpdate 和 updated 中可用。无论值是否更改，它都可用。 3.arg：传递给指令的参数 (如果有的话)。例如在 v-my-directive:foo 中，参数是 "foo"。 4.modifiers：一个包含修饰符的对象 (如果有的话)。例如在 v-my-directive.foo.bar 中，修饰符对象是 { foo: true, bar: true }。 5.instance：使用该指令的组件实例。 6.dir：指令的定义对象。
vnode	代表绑定元素的底层 VNode
prevVnode	代表之前的渲染中指令所绑定元素的 VNode。仅在 beforeUpdate 和 updated 钩子中可用

                                 注意： 除了 el 外，其他参数都是只读的

对于，binding参数，是不是还不清楚？，看个例子就好了

<div v-loading:aaa.bbb="ccc">

我们得到这样的binding参数：

{
  arg: 'aaa',
  modifiers: { bbb: true },
  value: ccc,
  oldValue: 上一次的ccc
}

自定义指令的参数也可以是动态的。举例来说：

<div v-example:[arg]="value"></div>

这里指令的参数会基于组件的 arg 数据属性响应式地更新

对象字面量​

如果你的指令需要多个值，你可以向它传递一个 JavaScript 对象字面量。别忘了，指令也可以接收任何合法的 JavaScript 表达式。

<div v-demo="{ color: 'white', text: 'hello!' }"></div>

app.directive('demo', (el, binding) => {
  console.log(binding.value.color) // => "white"
  console.log(binding.value.text) // => "hello!"
})

下面是一个，权限控制的实战应用，结合了hooks

import type { App } from 'vue'
import { CACHE_KEY, useCache } from '@/hooks/web/useCache'

const { t } = useI18n() // 国际化

export function hasPermi(app: App<Element>) {
  app.directive('hasPermi', (el, binding) => {
    const { wsCache } = useCache()
    const { value } = binding
    const all_permission = '*:*:*'
    const permissions = wsCache.get(CACHE_KEY.USER).permissions

    if (value && value instanceof Array && value.length > 0) {
      const permissionFlag = value

      const hasPermissions = permissions.some((permission: string) => {
        return all_permission === permission || permissionFlag.includes(permission)
      })

      if (!hasPermissions) {
        el.parentNode && el.parentNode.removeChild(el)
      }
    } else {
      throw new Error(t('permission.hasPermission'))
    }
  })
}

export function isPermi(permi:string) {
  const { wsCache } = useCache()
  const permissions = wsCache.get(CACHE_KEY.USER).permissions
  return permissions.includes(permi)
}

使用方式

v-hasPermi="['erp:finance-receipt:export']"

意图是：判断当前用户是否拥有某个权限标识，如果没有就移除元素

他的binding参数

{
  instance: Proxy(Object),
  value: ['erp:finance-receipt:export'], // 用户绑定的权限数组
  oldValue: undefined,
  arg: undefined,                        // 没有使用参数
  modifiers: {},                         // 没有使用修饰符
  dir: { ... }                           // 当前指令定义本身
}