[[381940]]

 本文轉(zhuǎn)載自微信公眾號(hào)「全棧修仙之路」，作者阿寶哥。轉(zhuǎn)載本文請聯(lián)系全棧修仙之路公眾號(hào)。  

在 Vue 的項(xiàng)目中，我們經(jīng)常會(huì)遇到 v-if、v-show、v-for 或 v-model 這些內(nèi)置指令，它們?yōu)槲覀兲峁┝瞬煌墓δ堋３耸褂眠@些內(nèi)置指令之外，Vue 也允許注冊自定義指令。

接下來，阿寶哥將使用 Vue 3 官方文檔 自定義指令 章節(jié)中使用的示例，來一步步揭開自定義指令背后的秘密。

提示：在閱讀本文前，建議您先閱讀 Vue 3 官方文檔 自定義指令 章節(jié)的內(nèi)容。

一、自定義指令

1、注冊全局自定義指令

const app = Vue.createApp({}) 
 
// 注冊一個(gè)全局自定義指令 v-focus 
app.directive('focus', { 
  // 當(dāng)被綁定的元素掛載到 DOM 中時(shí)被調(diào)用 
  mounted(el) { 
    // 聚焦元素 
    el.focus() 
  } 
}) 

2、使用全局自定義指令

<div id="app"> 
   <input v-focus /> 
</div> 

3、完整的使用示例

<div id="app"> 
   <input v-focus /> 
</div> 
<script> 
   const { createApp } = Vue 
    
   const app = Vue.createApp({}) // ① 
   app.directive('focus', { // ②  
     // 當(dāng)被綁定的元素掛載到 DOM 中時(shí)被調(diào)用 
     mounted(el) { 
       el.focus() // 聚焦元素 
     } 
   }) 
   app.mount('#app') // ③ 
</script> 

當(dāng)頁面加載完成后，頁面中的輸入框元素將自動(dòng)獲得焦點(diǎn)。該示例的代碼比較簡單，主要包含 3 個(gè)步驟：創(chuàng)建 App 對(duì)象、注冊全局自定義指令和應(yīng)用掛載。其中創(chuàng)建 App 對(duì)象的細(xì)節(jié)，阿寶哥會(huì)在后續(xù)的文章中單獨(dú)介紹，下面我們將重點(diǎn)分析其他 2 個(gè)步驟。首先我們先來分析注冊全局自定義指令的過程。

二、注冊全局自定義指令的過程

在以上示例中，我們使用 app 對(duì)象的 directive 方法來注冊全局自定義指令：

app.directive('focus', { 
  // 當(dāng)被綁定的元素掛載到 DOM 中時(shí)被調(diào)用 
  mounted(el) { 
    el.focus() // 聚焦元素 
  } 
}) 

當(dāng)然，除了注冊全局自定義指令外，我們也可以注冊局部指令，因?yàn)榻M件中也接受一個(gè) directives 的選項(xiàng)：

directives: { 
  focus: { 
    mounted(el) { 
      el.focus() 
    } 
  } 
} 

對(duì)于以上示例來說，我們使用的 app.directive 方法被定義在 runtime-core/src/apiCreateApp.ts 文件中：

// packages/runtime-core/src/apiCreateApp.ts 
export function createAppAPI<HostElement>( 
  render: RootRenderFunction, 
  hydrate?: RootHydrateFunction 
): CreateAppFunction<HostElement> { 
  return function createApp(rootComponent, rootProps = null) { 
    const context = createAppContext() 
    let isMounted = false 
 
    const app: App = (context.app = { 
      // 省略部分代碼 
      _context: context, 
       
      // 用于注冊或檢索全局指令。 
      directive(name: string, directive?: Directive) { 
        if (__DEV__) { 
          validateDirectiveName(name) 
        } 
        if (!directive) { 
          return context.directives[name] as any 
        } 
        if (__DEV__ && context.directives[name]) { 
          warn(`Directive "${name}" has already been registered in target app.`) 
        } 
        context.directives[name] = directive 
        return app 
      }, 
 
    return app 
  } 
} 

通過觀察以上代碼，我們可以知道 directive 方法支持以下兩個(gè)參數(shù)：

• name：表示指令的名稱;
• directive(可選)：表示指令的定義。

name 參數(shù)比較簡單，所以我們重點(diǎn)分析 directive 參數(shù)，該參數(shù)的類型是 Directive類型：

// packages/runtime-core/src/directives.ts 
export type Directive<T = any, V = any> = 
  | ObjectDirective<T, V> 
  | FunctionDirective<T, V> 

由上可知 Directive 類型屬于聯(lián)合類型，所以我們需要繼續(xù)分析 ObjectDirective 和 FunctionDirective 類型。這里我們先來看一下 ObjectDirective 類型的定義：

// packages/runtime-core/src/directives.ts 
export interface ObjectDirective<T = any, V = any> { 
  created?: DirectiveHook<T, null, V> 
  beforeMount?: DirectiveHook<T, null, V> 
  mounted?: DirectiveHook<T, null, V> 
  beforeUpdate?: DirectiveHook<T, VNode<any, T>, V> 
  updated?: DirectiveHook<T, VNode<any, T>, V> 
  beforeUnmount?: DirectiveHook<T, null, V> 
  unmounted?: DirectiveHook<T, null, V> 
  getSSRProps?: SSRDirectiveHook 
} 

該類型定義了對(duì)象類型的指令，對(duì)象上的每個(gè)屬性表示指令生命周期上的鉤子。而 FunctionDirective 類型則表示函數(shù)類型的指令：

// packages/runtime-core/src/directives.ts 
export type FunctionDirective<T = any, V = any> = DirectiveHook<T, any, V> 
                               
export type DirectiveHook<T = any, Prev = VNode<any, T> | null, V = any> = ( 
  el: T, 
  binding: DirectiveBinding<V>, 
  vnode: VNode<any, T>, 
  prevVNode: Prev 
) => void               

介紹完 Directive 類型，我們再回顧一下前面的示例，相信你就會(huì)清晰很多：

app.directive('focus', { 
  // 當(dāng)被綁定的元素掛載到 DOM 中時(shí)觸發(fā) 
  mounted(el) { 
    el.focus() // 聚焦元素 
  } 
}) 

對(duì)于以上示例，當(dāng)我們調(diào)用 app.directive 方法注冊自定義 focus 指令時(shí)，就會(huì)執(zhí)行以下邏輯：

directive(name: string, directive?: Directive) { 
  if (__DEV__) { // 避免自定義指令名稱，與已有的內(nèi)置指令名稱沖突 
    validateDirectiveName(name) 
  } 
  if (!directive) { // 獲取name對(duì)應(yīng)的指令對(duì)象 
    return context.directives[name] as any 
  } 
  if (__DEV__ && context.directives[name]) { 
    warn(`Directive "${name}" has already been registered in target app.`) 
  } 
  context.directives[name] = directive // 注冊全局指令 
  return app 
} 

當(dāng) focus 指令注冊成功之后，該指令會(huì)被保存在 context 對(duì)象的 directives 屬性中，具體如下圖所示：

顧名思義 context 是表示應(yīng)用的上下文對(duì)象，那么該對(duì)象是如何創(chuàng)建的呢?其實(shí)，該對(duì)象是通過 createAppContext 函數(shù)來創(chuàng)建的：

const context = createAppContext() 

而 createAppContext 函數(shù)被定義在 runtime-core/src/apiCreateApp.ts 文件中：

// packages/runtime-core/src/apiCreateApp.ts 
export function createAppContext(): AppContext { 
  return { 
    app: null as any, 
    config: { 
      isNativeTag: NO, 
      performance: false, 
      globalProperties: {}, 
      optionMergeStrategies: {}, 
      isCustomElement: NO, 
      errorHandler: undefined, 
      warnHandler: undefined 
    }, 
    mixins: [], 
    components: {}, 
    directives: {}, 
    provides: Object.create(null) 
  } 
} 

看到這里，是不是覺得注冊全局自定義指令的內(nèi)部處理邏輯其實(shí)挺簡單的。那么對(duì)于已注冊的 focus 指令，何時(shí)會(huì)被調(diào)用呢?要回答這個(gè)問題，我們就需要分析另一個(gè)步驟 ——應(yīng)用掛載。

三、應(yīng)用掛載的過程

為了更加直觀地了解應(yīng)用掛載的過程，阿寶哥利用 Chrome 開發(fā)者工具，記錄了應(yīng)用掛載的主要過程：

通過上圖，我們就可以知道應(yīng)用掛載期間所經(jīng)歷的主要過程。此外，從圖中我們也發(fā)現(xiàn)了一個(gè)與指令相關(guān)的函數(shù) resolveDirective。很明顯，該函數(shù)用于解析指令，且該函數(shù)在render 方法中會(huì)被調(diào)用。在源碼中，我們找到了該函數(shù)的定義：

// packages/runtime-core/src/helpers/resolveAssets.ts 
export function resolveDirective(name: string): Directive | undefined { 
  return resolveAsset(DIRECTIVES, name) 
} 

在 resolveDirective 函數(shù)內(nèi)部，會(huì)繼續(xù)調(diào)用 resolveAsset 函數(shù)來執(zhí)行具體的解析操作。在分析 resolveAsset 函數(shù)的具體實(shí)現(xiàn)之前，我們在 resolveDirective 函數(shù)內(nèi)部加個(gè)斷點(diǎn)，來一睹 render 方法的 “芳容”：

在上圖中，我們看到了與 focus 指令相關(guān)的 _resolveDirective("focus") 函數(shù)調(diào)用。前面我們已經(jīng)知道在 resolveDirective 函數(shù)內(nèi)部會(huì)繼續(xù)調(diào)用 resolveAsset 函數(shù)，該函數(shù)的具體實(shí)現(xiàn)如下：

// packages/runtime-core/src/helpers/resolveAssets.ts 
function resolveAsset( 
  type: typeof COMPONENTS | typeof DIRECTIVES, 
  name: string, 
  warnMissing = true 
) { 
  const instance = currentRenderingInstance || currentInstance 
  if (instance) { 
    const Component = instance.type 
    // 省略解析組件的處理邏輯 
    const res = 
      // 局部注冊 
      resolve(instance[type] || (Component as ComponentOptions)[type], name) || 
      // 全局注冊 
      resolve(instance.appContext[type], name) 
    return res 
  } else if (__DEV__) { 
    warn( 
      `resolve${capitalize(type.slice(0, -1))} ` + 
        `can only be used in render() or setup().` 
    ) 
  } 
} 

因?yàn)樽?focus 指令時(shí)，使用的是全局注冊的方式，所以解析的過程會(huì)執(zhí)行 resolve(instance.appContext[type], name) 該語句，其中 resolve 方法的定義如下：

function resolve(registry: Record<string, any> | undefined, name: string) { 
  return ( 
    registry && 
    (registry[name] || 
      registry[camelize(name)] || 
      registry[capitalize(camelize(name))]) 
  ) 
} 

分析完以上的處理流程，我們可以知道在解析全局注冊的指令時(shí)，會(huì)通過 resolve 函數(shù)從應(yīng)用的上下文對(duì)象中獲取已注冊的指令對(duì)象。在獲取到 _directive_focus 指令對(duì)象后，render 方法內(nèi)部會(huì)繼續(xù)調(diào)用 _withDirectives 函數(shù)，用于把指令添加到 VNode 對(duì)象上，該函數(shù)被定義在 runtime-core/src/directives.ts 文件中：

// packages/runtime-core/src/directives.ts 
export function withDirectives<T extends VNode>( 
  vnode: T, 
  directives: DirectiveArguments 
): T { 
  const internalInstance = currentRenderingInstance // 獲取當(dāng)前渲染的實(shí)例 
  const instance = internalInstance.proxy 
  const bindings: DirectiveBinding[] = vnode.dirs || (vnode.dirs = []) 
  for (let i = 0; i < directives.length; i++) { 
    let [dir, value, arg, modifiers = EMPTY_OBJ] = directives[i] 
    // 在 mounted 和 updated 時(shí)，觸發(fā)相同行為，而不關(guān)系其他的鉤子函數(shù) 
    if (isFunction(dir)) { // 處理函數(shù)類型指令 
      dir = { 
        mounted: dir, 
        updated: dir 
      } as ObjectDirective 
    } 
    bindings.push({ 
      dir, 
      instance, 
      value, 
      oldValue: void 0, 
      arg, 
      modifiers 
    }) 
  } 
  return vnode 
} 

因?yàn)橐粋€(gè)節(jié)點(diǎn)上可能會(huì)應(yīng)用多個(gè)指令，所以 withDirectives 函數(shù)在 VNode 對(duì)象上定義了一個(gè) dirs 屬性且該屬性值為數(shù)組。對(duì)于前面的示例來說，在調(diào)用 withDirectives 函數(shù)之后，VNode 對(duì)象上就會(huì)新增一個(gè) dirs 屬性，具體如下圖所示：

通過上面的分析，我們已經(jīng)知道在組件的 render 方法中，我們會(huì)通過 withDirectives函數(shù)把指令注冊對(duì)應(yīng)的 VNode 對(duì)象上。那么 focus 指令上定義的鉤子什么時(shí)候會(huì)被調(diào)用呢?在繼續(xù)分析之前，我們先來介紹一下指令對(duì)象所支持的鉤子函數(shù)。

一個(gè)指令定義對(duì)象可以提供如下幾個(gè)鉤子函數(shù) (均為可選)：

• created：在綁定元素的屬性或事件監(jiān)聽器被應(yīng)用之前調(diào)用。
• beforeMount：當(dāng)指令第一次綁定到元素并且在掛載父組件之前調(diào)用。
• mounted：在綁定元素的父組件被掛載后調(diào)用。
• beforeUpdate：在更新包含組件的 VNode 之前調(diào)用。
• updated：在包含組件的 VNode 及其子組件的 VNode 更新后調(diào)用。
• beforeUnmount：在卸載綁定元素的父組件之前調(diào)用。
• unmounted：當(dāng)指令與元素解除綁定且父組件已卸載時(shí)，只調(diào)用一次。

介紹完這些鉤子函數(shù)之后，我們再來回顧一下前面介紹的 ObjectDirective 類型：

// packages/runtime-core/src/directives.ts 
export interface ObjectDirective<T = any, V = any> { 
  created?: DirectiveHook<T, null, V> 
  beforeMount?: DirectiveHook<T, null, V> 
  mounted?: DirectiveHook<T, null, V> 
  beforeUpdate?: DirectiveHook<T, VNode<any, T>, V> 
  updated?: DirectiveHook<T, VNode<any, T>, V> 
  beforeUnmount?: DirectiveHook<T, null, V> 
  unmounted?: DirectiveHook<T, null, V> 
  getSSRProps?: SSRDirectiveHook 
} 

好的，接下來我們來分析一下 focus 指令上定義的鉤子什么時(shí)候被調(diào)用。同樣，阿寶哥在focus 指令的 mounted 方法中加個(gè)斷點(diǎn)：

在圖中右側(cè)的調(diào)用棧中，我們看到了 invokeDirectiveHook 函數(shù)，很明顯該函數(shù)的作用就是調(diào)用指令上已注冊的鉤子。出于篇幅考慮，具體的細(xì)節(jié)阿寶哥就不繼續(xù)介紹了，感興趣的小伙伴可以自行斷點(diǎn)調(diào)試一下。

四、阿寶哥有話說

4.1 Vue 3 有哪些內(nèi)置指令?

在介紹注冊全局自定義指令的過程中，我們看到了一個(gè) validateDirectiveName 函數(shù)，該函數(shù)用于驗(yàn)證自定義指令的名稱，從而避免自定義指令名稱，與已有的內(nèi)置指令名稱沖突。

// packages/runtime-core/src/directives.ts 
export function validateDirectiveName(name: string) { 
  if (isBuiltInDirective(name)) { 
    warn('Do not use built-in directive ids as custom directive id: ' + name) 
  } 
} 

在 validateDirectiveName 函數(shù)內(nèi)部，會(huì)通過 isBuiltInDirective(name) 語句來判斷是否為內(nèi)置指令：

const isBuiltInDirective = /*#__PURE__*/ makeMap( 
  'bind,cloak,else-if,else,for,html,if,model,on,once,pre,show,slot,text' 
) 

以上代碼中的 makeMap 函數(shù)，用于生成一個(gè) map 對(duì)象(Object.create(null))并返回一個(gè)函數(shù)，用于檢測某個(gè) key 是否存在 map 對(duì)象中。另外，通過以上代碼，我們就可以很清楚地了解 Vue 3 中為我們提供了哪些內(nèi)置指令。

4.2 指令有幾種類型?

在 Vue 3 中指令分為 ObjectDirective 和 FunctionDirective 兩種類型：

// packages/runtime-core/src/directives.ts 
export type Directive<T = any, V = any> = 
  | ObjectDirective<T, V> 
  | FunctionDirective<T, V> 

ObjectDirective

export interface ObjectDirective<T = any, V = any> { 
  created?: DirectiveHook<T, null, V> 
  beforeMount?: DirectiveHook<T, null, V> 
  mounted?: DirectiveHook<T, null, V> 
  beforeUpdate?: DirectiveHook<T, VNode<any, T>, V> 
  updated?: DirectiveHook<T, VNode<any, T>, V> 
  beforeUnmount?: DirectiveHook<T, null, V> 
  unmounted?: DirectiveHook<T, null, V> 
  getSSRProps?: SSRDirectiveHook 
} 

FunctionDirective

export type FunctionDirective<T = any, V = any> = DirectiveHook<T, any, V> 
                               
export type DirectiveHook<T = any, Prev = VNode<any, T> | null, V = any> = ( 
  el: T, 
  binding: DirectiveBinding<V>, 
  vnode: VNode<any, T>, 
  prevVNode: Prev 
) => void 

如果你想在 mounted 和 updated 時(shí)觸發(fā)相同行為，而不關(guān)心其他的鉤子函數(shù)。那么你可以通過將回調(diào)函數(shù)傳遞給指令來實(shí)現(xiàn)：

app.directive('pin', (el, binding) => { 
  el.style.position = 'fixed' 
  const s = binding.arg || 'top' 
  el.style[s] = binding.value + 'px' 
}) 

4.3 注冊全局指令與局部指令有什么區(qū)別?

注冊全局指令

app.directive('focus', { 
  // 當(dāng)被綁定的元素掛載到 DOM 中時(shí)被調(diào)用 
  mounted(el) { 
    el.focus() // 聚焦元素 
  } 
}); 

注冊局部指令

const Component = defineComponent({ 
  directives: { 
    focus: { 
      mounted(el) { 
        el.focus() 
      } 
    } 
  }, 
  render() { 
    const { directives } = this.$options; 
    return [withDirectives(h('input'), [[directives.focus, ]])] 
  } 
}); 

解析全局注冊和局部注冊的指令

// packages/runtime-core/src/helpers/resolveAssets.ts 
function resolveAsset( 
  type: typeof COMPONENTS | typeof DIRECTIVES, 
  name: string, 
  warnMissing = true 
) { 
  const instance = currentRenderingInstance || currentInstance 
  if (instance) { 
    const Component = instance.type 
    // 省略解析組件的處理邏輯 
    const res = 
      // 局部注冊 
      resolve(instance[type] || (Component as ComponentOptions)[type], name) || 
      // 全局注冊 
      resolve(instance.appContext[type], name) 
    return res 
  } 
} 

4.4 內(nèi)置指令和自定義指令生成的渲染函數(shù)有什么區(qū)別?

要了解內(nèi)置指令和自定義指令生成的渲染函數(shù)的區(qū)別，阿寶哥以 v-if 、v-show 內(nèi)置指令和 v-focus 自定義指令為例，然后使用 Vue 3 Template Explorer 這個(gè)在線工具來編譯生成渲染函數(shù)：

v-if 內(nèi)置指令

<input v-if="isShow" /> 
 
const _Vue = Vue 
return function render(_ctx, _cache, $props, $setup, $data, $options) { 
  with (_ctx) { 
    const { createVNode: _createVNode, openBlock: _openBlock,  
      createBlock: _createBlock, createCommentVNode: _createCommentVNode } = _Vue 
 
    return isShow 
      ? (_openBlock(), _createBlock("input", { key: 0 })) 
      : _createCommentVNode("v-if", true) 
  } 
} 

對(duì)于 v-if 指令來說，在編譯后會(huì)通過 ?: 三目運(yùn)算符來實(shí)現(xiàn)動(dòng)態(tài)創(chuàng)建節(jié)點(diǎn)的功能。

v-show 內(nèi)置指令

<input v-show="isShow" /> 
   
const _Vue = Vue 
return function render(_ctx, _cache, $props, $setup, $data, $options) { 
  with (_ctx) { 
    const { vShow: _vShow, createVNode: _createVNode, withDirectives: _withDirectives,  
      openBlock: _openBlock, createBlock: _createBlock } = _Vue 
 
    return _withDirectives((_openBlock(), _createBlock("input", null, null, 512 /* NEED_PATCH */)), [ 
      [_vShow, isShow] 
    ]) 
  } 
} 

以上示例中的 vShow 指令被定義在 packages/runtime-dom/src/directives/vShow.ts文件中，該指令屬于 ObjectDirective 類型的指令，該指令內(nèi)部定義了beforeMount、mounted、updated 和 beforeUnmount 四個(gè)鉤子。

v-focus 自定義指令

<input v-focus /> 
 
const _Vue = Vue 
return function render(_ctx, _cache, $props, $setup, $data, $options) { 
  with (_ctx) { 
    const { resolveDirective: _resolveDirective, createVNode: _createVNode,  
      withDirectives: _withDirectives, openBlock: _openBlock, createBlock: _createBlock } = _Vue 
 
    const _directive_focus = _resolveDirective("focus") 
    return _withDirectives((_openBlock(), _createBlock("input", null, null, 512 /* NEED_PATCH */)), [ 
      [_directive_focus] 
    ]) 
  } 
} 

通過對(duì)比 v-focus 與 v-show 指令生成的渲染函數(shù)，我們可知 v-focus 自定義指令與v-show 內(nèi)置指令都會(huì)通過 withDirectives 函數(shù)，把指令注冊到 VNode 對(duì)象上。而自定義指令相比內(nèi)置指令來說，會(huì)多一個(gè)指令解析的過程。

此外，如果在 input 元素上，同時(shí)應(yīng)用了 v-show 和 v-focus 指令，則在調(diào)用 _withDirectives 函數(shù)時(shí)，將使用二維數(shù)組：

<input v-show="isShow" v-focus /> 
 
const _Vue = Vue 
return function render(_ctx, _cache, $props, $setup, $data, $options) { 
  with (_ctx) { 
    const { vShow: _vShow, resolveDirective: _resolveDirective, createVNode: _createVNode,  
      withDirectives: _withDirectives, openBlock: _openBlock, createBlock: _createBlock } = _Vue 
 
    const _directive_focus = _resolveDirective("focus") 
    return _withDirectives((_openBlock(), _createBlock("input", null, null, 512 /* NEED_PATCH */)), [ 
      [_vShow, isShow], 
      [_directive_focus] 
    ]) 
  } 
} 

4.5 如何在渲染函數(shù)中應(yīng)用指令?

除了在模板中應(yīng)用指令之外，利用前面介紹的 withDirectives 函數(shù)，我們可以很方便地在渲染函數(shù)中應(yīng)用指定的指令：

<div id="app"></div> 
<script> 
   const { createApp, h, vShow, defineComponent, withDirectives } = Vue 
   const Component = defineComponent({ 
     data() { 
       return { value: true } 
     }, 
     render() { 
       return [withDirectives(h('div', '我是阿寶哥'), [[vShow, this.value]])] 
     } 
   }); 
   const app = Vue.createApp(Component) 
   app.mount('#app') 
</script> 

本文阿寶哥主要介紹了在 Vue 3 中如何自定義指令、如何注冊全局和局部指令。為了讓大家能夠更深入地掌握自定義指令的相關(guān)知識(shí)，阿寶哥從源碼的角度分析了指令的注冊和應(yīng)用過程。

在后續(xù)的文章中，阿寶哥將會(huì)介紹一些特殊的指令，當(dāng)然也會(huì)重點(diǎn)分析一下雙向綁定的原理，感興趣的小伙伴不要錯(cuò)過喲。

五、參考資源

• Vue 3 官網(wǎng) - 自定義指令
• Vue 3 官網(wǎng) - 應(yīng)用 API