カスタムディレクティブ ​

はじめに ​

コアに設定されているデフォルトのディレクティブのセット（v-model や v-show など）に加え、Vue では独自のカスタムディレクティブを登録することができます。

Vue におけるコードの再利用として 2 つの方法を紹介してきました:コンポーネントとコンポーザブルです。コンポーネントはメインブロックの構築、コンポーザブルはステートフルなロジックの再利用に重点を置いています。一方、カスタムディレクティブは主にプレーンな要素に対する低レベルの DOM アクセスを伴うロジックを再利用することを目的としています。

カスタムディレクティブは、コンポーネントと同様のライフサイクルフックを含むオブジェクトとして定義されます。フックは、ディレクティブがバインドされている要素を受け取ります。以下は Vue によって要素が DOM に挿入されたときに入力欄にフォーカスするディレクティブの例です:

<script setup>
// テンプレート内で v-focus が有効になります
const vFocus = {
  mounted: (el) => el.focus()
}
</script>

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

const focus = {
  mounted: (el) => el.focus()
}

export default {
  directives: {
    // テンプレート内で v-focus が有効になります
    focus
  }
}

<input v-focus />

ページの他の場所をクリックしていないと仮定すると、上の入力欄は自動的にフォーカスされるはずです。このディレクティブはページロード時だけでなく、Vue によって要素が動的に挿入されたときにも機能するため、autofocus 属性よりも便利です。

export default {
  setup() {
    /*...*/
  },
  directives: {
    // テンプレート内で v-focus が有効になります
    focus: {
      /* ... */
    }
  }
}

また、カスタムディレクティブをアプリケーションレベルでグローバル登録することもよくあります:

const app = createApp({})

// 全てのコンポーネントで v-focus が使用可能
app.directive('focus', {
  /* ... */
})

ディレクティブフック ​

ディレクティブ定義オブジェクトは、いくつかのフック関数（すべて任意です）を提供することができます:

const myDirective = {
  // バインドされた要素の属性や
  // イベントリスナーが適用される前に呼ばれます
  created(el, binding, vnode, prevVnode) {
    // 引数の詳細については下を参照してください
  },
  // 要素が DOM に挿入される直前に呼ばれます
  beforeMount(el, binding, vnode, prevVnode) {},
  // バインドされた要素の親コンポーネントと
  // そのすべての子要素がマウントされたときに呼び出されます
  mounted(el, binding, vnode, prevVnode) {},
  // 親コンポーネントが更新される前に呼ばれます
  beforeUpdate(el, binding, vnode, prevVnode) {},
  // 親コンポーネントとすべての子要素が
  // 更新された後に呼ばれます
  updated(el, binding, vnode, prevVnode) {},
  // 親コンポーネントがアンマウントされる前に呼ばれます
  beforeUnmount(el, binding, vnode, prevVnode) {},
  // 親コンポーネントのアンマウント時に呼ばれます
  unmounted(el, binding, vnode, prevVnode) {}
}

フックの引数 ​

ディレクティブフックには以下の引数が渡されます:

• el: ディレクティブがバインドされている要素。DOM を直接操作するために使用されます。

• binding: 以下のプロパティを含むオブジェクト。

  • value: ディレクティブに渡される値。例えば v-my-directive="1 + 1" の場合、値は 2 となります。
  • oldValue: 更新前の値。 beforeUpdate と updated でのみ利用可能です。値が変更されているかどうかに関係なく利用できます。
  • arg: ディレクティブに渡される引数がある場合に存在する引数。例えば v-my-directive:foo の場合、引数は "foo" となります。
  • modifiers: 修飾子がある時に、それを含むオブジェクト。例えば v-my-directive.foo.bar の場合、修飾子オブジェクトは { foo: true, bar: true } となります。
  • instance: ディレクティブが使用されるコンポーネントのインスタンス。
  • dir: ディレクティブ定義オブジェクト。

• vnode: バインドされた要素を表す基礎となる VNode。

• prevVnode: 前のレンダリングからバインドされた要素を表す VNode。beforeUpdate と updated フックでのみ利用可能です。

例として、次のようなディレクティブの使い方を考えてみましょう:

<div v-example:foo.bar="baz">

引数 binding は以下のような構造のオブジェクトになります:

{
  arg: 'foo',
  modifiers: { bar: true },
  value: /* `baz` の値 */,
  oldValue: /* 前回の更新による `baz` の値 */
}

組み込みのディレクティブと同様に、カスタムディレクティブの引数も動的にできます。例えば:

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

ここでは、ディレクティブの引数は、コンポーネントの状態にある arg プロパティに基づいてリアクティブに更新されます。

関数のショートハンド ​

よくあることとして、カスタムディレクティブが mounted と updated に対して同じ動作をさせ、他のフックを必要としないことがあります。このような場合、ディレクティブを関数として定義することができます:

<div v-color="color"></div>

app.directive('color', (el, binding) => {
  // `mounted` と `updated` の両方で呼ばれます
  el.style.color = binding.value
})

オブジェクトリテラル ​

ディレクティブが複数の値を必要とする場合、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!"
})

コンポーネントでの使い方 ​

コンポーネントで使用すると、フォールスルー属性と同様にカスタムディレクティブは常にコンポーネントのルートノードに適用されます。

<MyComponent v-demo="test" />

<!-- template of MyComponent -->

<div> <!-- v-demo directive will be applied here -->
  <span>My component content</span>
</div>

コンポーネントは潜在的に複数のルートノードを持つ可能性があることに注意してください。複数のルートを持つコンポーネントに適用された場合、ディレクティブは無視され、警告が投げられます。属性とは異なり、ディレクティブは v-bind="$attrs" で別の要素に渡すことができません。一般に、カスタムディレクティブをコンポーネントで使用することはお勧めしません。