Vue.js のカスタムディレクティブを自作してみよう

2025年7月12日

Vue.js

Vue.js のエコシステムの中でも、カスタムディレクティブは特に強力で柔軟な機能の一つです。この記事では、カスタムディレクティブの仕組みを深く理解し、実際に手を動かしながら様々なパターンのディレクティブを作成していきます。理論と実践のバランスを取りながら、確実にスキルアップできる内容をお届けします。

きっとあなたも、Vue.js を使っていて「もっと効率的に DOM 操作ができたらいいのに」と感じた経験があるのではないでしょうか。カスタムディレクティブを習得することで、あなたの Vue.js 開発は劇的に変わります。一緒に学んでいきましょう。

背景

Vue.js のリアクティブシステムとディレクティブの関係

Vue.js の魅力の一つは、データとビューが自動的に同期されるリアクティブシステムです。しかし、実際の開発現場では、このリアクティブシステムだけでは解決できない DOM 操作が数多く存在します。

例えば、フォームの入力フィールドに自動的にフォーカスを当てたり、特定の要素がビューポートに入ったときにアニメーションを実行したりといった操作ですね。これらの処理は、データの変更に直接反応するものではなく、DOM 要素そのものに対する操作が必要になります。

Vue.js のディレクティブは、まさにこのようなケースのために設計されています。v-model、v-show、v-if などの組み込みディレクティブは、Vue.js のリアクティブシステムと DOM 操作を橋渡しする役割を果たしているのです。

カスタムディレクティブが生まれた背景

Web アプリケーションの複雑化に伴い、開発者は様々な UI パターンを実装する必要に迫られました。特に、以下のような課題が頻繁に発生するようになりました：

課題	具体例	従来の解決方法の問題点
DOM 操作の重複	複数箇所でのフォーカス制御	毎回同じコードを書く必要がある
第三者ライブラリの統合	Chart.js や D3.js との連携	コンポーネント内で複雑な処理が必要
条件付きの DOM 操作	権限に基づく要素の表示・非表示	v-if だけでは表現しきれない

これらの課題を解決するため、Vue.js にはカスタムディレクティブという機能が用意されました。カスタムディレクティブを使うことで、再利用可能で保守性の高い DOM 操作を実現できるのです。

モダンフロントエンド開発でのディレクティブの価値

現代のフロントエンド開発では、ユーザー体験の向上が最重要課題の一つです。しかし、優れた UX を実現するためには、細やかな DOM 操作が欠かせません。

カスタムディレクティブの真の価値は、宣言的なアプローチで命令的な DOM 操作を実現できることにあります。これにより、以下のような利点を得られます：

可読性の向上：テンプレート内で何が起こるかが一目瞭然
再利用性の確保：一度作成したディレクティブは様々な場所で使用可能
保守性の向上：ロジックが一箇所に集約されるため、変更が容易
チーム開発の効率化：共通の処理を統一的に実装できる

課題

複雑な DOM 操作をコンポーネント化する難しさ

Vue.js のコンポーネントは、UI の再利用可能な部品を作成するのに適していますが、DOM 操作そのものを再利用する場合には課題があります。

例えば、以下のような状況を考えてみてください：

typescript// 複数のコンポーネントで同じDOM操作が必要な場合
export default {
  mounted() {
    // 要素にフォーカスを当てる処理
    this.$refs.inputElement.focus();

    // スクロール位置を制御する処理
    this.$refs.container.scrollTop = 0;

    // 外部ライブラリの初期化
    this.initializeChart();
  },
};

この approach には以下のような問題があります：

コード重複：同じ処理を複数のコンポーネントで書く必要がある
テストの困難さ：各コンポーネントで個別にテストする必要がある
保守性の低下：処理を変更する際に複数箇所の修正が必要

実際に開発現場で遭遇するエラーの例を見てみましょう：

phpTypeError: Cannot read properties of undefined (reading 'focus')
    at VueComponent.mounted (Component.vue:15:32)
    at callHook (vue.runtime.esm.js:4479:21)
    at Object.insert (vue.runtime.esm.js:3139:7)

このエラーは、DOM 要素がまだ存在しないタイミングで focus() メソッドを呼び出そうとした際に発生する典型的な問題です。

再利用可能な UI パターンの実現

モダンな Web アプリケーションでは、一貫した UI パターンが求められます。しかし、以下のような UI パターンをコンポーネントだけで実現するのは困難です：

UI パターン	実装の難しさ	理由
ツールチップ	高	位置計算やイベントハンドリングが複雑
無限スクロール	高	スクロール検知とデータ取得の連携
ドラッグ&ドロップ	高	マウス/タッチイベントの管理
フォーカストラップ	中	キーボードナビゲーションの制御

これらのパターンを実装する際によく遭遇するのが、以下のようなエラーです：

vbnetDOMException: Failed to execute 'addEventListener' on 'EventTarget':
The provided callback is not a function.
    at setupEventListeners (directive.js:42:15)
    at bind (directive.js:18:3)

このエラーは、イベントリスナーの設定時に適切な関数が渡されなかった場合に発生します。カスタムディレクティブでは、このような問題を体系的に解決できます。

第三者ライブラリとの統合問題

Vue.js アプリケーションでは、Chart.js、D3.js、Mapbox などの第三者ライブラリを統合する機会が多々あります。しかし、これらのライブラリは Vue.js のライフサイクルを理解していないため、統合時に様々な問題が発生します。

典型的な統合パターンと問題点を見てみましょう：

typescript// 問題のあるアプローチ
export default {
  mounted() {
    // Chart.js の初期化
    this.chart = new Chart(this.$refs.canvas, {
      type: 'bar',
      data: this.chartData,
    });
  },

  beforeDestroy() {
    // クリーンアップを忘れがち
    if (this.chart) {
      this.chart.destroy();
    }
  },
};

このアプローチでは以下の問題が発生します：

メモリリーク：クリーンアップが不十分な場合
再レンダリング問題：Vue.js の更新サイクルとの競合
コード重複：同じ初期化処理を複数箇所で実装

実際に発生するエラーの例：

vbnetError: Canvas is already in use. Chart with ID '0' must be destroyed before the canvas can be reused.
    at Chart.construct (chart.js:3451:15)
    at new Chart (chart.js:3424:20)
    at VueComponent.mounted (ChartComponent.vue:25:18)

解決策

ディレクティブライフサイクルの完全理解

カスタムディレクティブを効果的に活用するためには、まずディレクティブのライフサイクルを完全に理解する必要があります。Vue.js のカスタムディレクティブには、以下の 5 つのライフサイクルフックが用意されています。

フック名	実行タイミング	主な用途
`bind`	要素に初めてバインドされた時	初期設定、イベントリスナーの登録
`inserted`	要素が親ノードに挿入された時	DOM 操作、フォーカス制御
`update`	仮想ノードが更新された時	データ変更に応じた更新処理
`componentUpdated`	子コンポーネントも含めて更新完了時	複雑な更新処理の後処理
`unbind`	要素からバインドが解除された時	クリーンアップ、リソース解放

実際のディレクティブ実装例を見てみましょう：

typescript// 基本的なディレクティブの構造
Vue.directive('example', {
  bind(el, binding, vnode) {
    // 要素に初めてバインドされた時の処理
    console.log('bind:', binding.value);
  },

  inserted(el, binding, vnode) {
    // DOM に挿入された時の処理
    console.log('inserted:', el);
  },

  update(el, binding, vnode, oldVnode) {
    // 更新時の処理
    console.log('update:', binding.value);
  },

  unbind(el, binding, vnode) {
    // バインド解除時のクリーンアップ
    console.log('unbind: cleanup');
  },
});

引数、モディファイアー、値の使い分け

カスタムディレクティブでは、以下の 3 つの要素を使ってディレクティブの動作をカスタマイズできます：

typescript// 使用例：v-example:arg.modifier="value"
// arg: 引数
// modifier: モディファイアー
// value: 値

それぞれの特徴と使い分けを詳しく見てみましょう：

typescriptVue.directive('flexible', {
  bind(el, binding) {
    // 引数の取得
    const arg = binding.arg; // "click" など

    // モディファイアーの確認
    const hasPreventModifier = binding.modifiers.prevent;
    const hasOnceModifier = binding.modifiers.once;

    // 値の取得
    const value = binding.value; // 関数やオブジェクト

    // 引数に基づく処理分岐
    if (arg === 'click') {
      setupClickHandler(el, value, binding.modifiers);
    } else if (arg === 'hover') {
      setupHoverHandler(el, value, binding.modifiers);
    }
  },
});

エラーハンドリングとテスト戦略

カスタムディレクティブでは、予期せぬエラーが発生しやすいため、適切なエラーハンドリングが重要です。以下は、実際のプロジェクトで使用できるエラーハンドリングパターンです：

typescriptVue.directive('safe-operation', {
  bind(el, binding) {
    try {
      // 必要な値の検証
      if (typeof binding.value !== 'function') {
        throw new Error(
          'v-safe-operation expects a function'
        );
      }

      // DOM 要素の存在確認
      if (!el || !el.nodeType) {
        throw new Error('Invalid DOM element');
      }

      // 実際の処理
      setupOperation(el, binding.value);
    } catch (error) {
      // エラーログの出力
      console.error('v-safe-operation error:', error);

      // 開発環境でのみエラーを表示
      if (process.env.NODE_ENV === 'development') {
        console.warn('Element:', el);
        console.warn('Binding:', binding);
      }
    }
  },
});

テスト戦略についても重要です。以下は Jest を使用したディレクティブのテスト例です：

typescript// directive.test.ts
import { mount } from '@vue/test-utils';
import CustomDirective from './custom-directive';

describe('CustomDirective', () => {
  test('should apply directive correctly', () => {
    const wrapper = mount(
      {
        template:
          '<div v-custom-directive="testValue"></div>',
        data() {
          return {
            testValue: 'test',
          };
        },
      },
      {
        directives: {
          'custom-directive': CustomDirective,
        },
      }
    );

    // ディレクティブが適用されているかテスト
    expect(wrapper.find('div').element).toHaveAttribute(
      'data-processed'
    );
  });
});

具体例

段階的なカスタムディレクティブ実装

Level 1：シンプルな DOM 操作ディレクティブ

まずは最もシンプルな例から始めましょう。フォーカス制御ディレクティブです：

typescript// v-focus ディレクティブの実装
Vue.directive('focus', {
  inserted(el) {
    // DOM に挿入されたタイミングでフォーカス
    el.focus();
  },
});

テンプレートでの使用方法：

html<template>
  <div>
    <input
      v-focus
      type="text"
      placeholder="自動的にフォーカスされます"
    />
    <button @click="showModal = true">
      モーダルを開く
    </button>

    <!-- モーダル内の入力欄にもフォーカス -->
    <div v-if="showModal" class="modal">
      <input
        v-focus
        type="text"
        placeholder="モーダル内でも自動フォーカス"
      />
    </div>
  </div>
</template>

この simple な例でも、以下のような問題が発生する可能性があります：

csharpDOMException: Failed to execute 'focus' on 'HTMLElement':
The element is not focusable.
    at HTMLDivElement.inserted (focus-directive.js:3:8)

このエラーを回避するため、改良版を実装してみましょう：

typescript// 改良版 v-focus ディレクティブ
Vue.directive('focus', {
  inserted(el) {
    // フォーカス可能な要素かチェック
    if (el.focus && typeof el.focus === 'function') {
      // 非同期でフォーカス（DOM更新を待つ）
      Vue.nextTick(() => {
        try {
          el.focus();
        } catch (error) {
          console.warn('Focus failed:', error);
        }
      });
    } else {
      // フォーカス可能な子要素を探す
      const focusable = el.querySelector(
        'input, textarea, select, button, [tabindex]:not([tabindex="-1"])'
      );
      if (focusable) {
        Vue.nextTick(() => {
          focusable.focus();
        });
      }
    }
  },
});

Level 2：引数を活用した動的ディレクティブ

次に、引数を使ってより柔軟なディレクティブを作成してみましょう。色々な CSS プロパティを動的に変更できるディレクティブです：

typescript// v-style ディレクティブ（動的スタイル適用）
Vue.directive('style', {
  bind(el, binding) {
    updateStyle(el, binding);
  },

  update(el, binding) {
    updateStyle(el, binding);
  },
});

function updateStyle(el, binding) {
  const { arg, value } = binding;

  // 引数がない場合はオブジェクトとして扱う
  if (!arg) {
    if (typeof value === 'object' && value !== null) {
      Object.keys(value).forEach((prop) => {
        el.style[prop] = value[prop];
      });
    }
    return;
  }

  // 引数がある場合は個別プロパティとして扱う
  if (
    typeof value === 'string' ||
    typeof value === 'number'
  ) {
    el.style[arg] = value;
  }
}

使用例：

html<template>
  <div>
    <!-- 個別プロパティの指定 -->
    <div v-style:color="textColor">
      テキストの色が変わります
    </div>
    <div v-style:font-size="fontSize + 'px'">
      フォントサイズが変わります
    </div>

    <!-- オブジェクトでの一括指定 -->
    <div v-style="dynamicStyles">
      複数のスタイルを同時適用
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        textColor: '#ff6b6b',
        fontSize: 18,
        dynamicStyles: {
          backgroundColor: '#f8f9fa',
          padding: '20px',
          borderRadius: '8px',
        },
      };
    },
  };
</script>

Level 3：複雑なイベントハンドリングディレクティブ

より実用的な例として、要素の外側をクリックしたときに処理を実行するディレクティブを作成してみましょう：

typescript// v-click-outside ディレクティブ
Vue.directive('click-outside', {
  bind(el, binding) {
    // イベントハンドラーを要素に保存
    el._clickOutsideHandler = (event) => {
      // クリックされた要素が対象要素内にあるかチェック
      if (
        !(el === event.target || el.contains(event.target))
      ) {
        // 外側がクリックされた場合の処理
        if (typeof binding.value === 'function') {
          binding.value(event);
        }
      }
    };

    // document に click イベントリスナーを追加
    document.addEventListener(
      'click',
      el._clickOutsideHandler
    );
  },

  unbind(el) {
    // クリーンアップ：イベントリスナーを削除
    if (el._clickOutsideHandler) {
      document.removeEventListener(
        'click',
        el._clickOutsideHandler
      );
      delete el._clickOutsideHandler;
    }
  },
});

このディレクティブの使用例：

html<template>
  <div>
    <button @click="isOpen = !isOpen">
      ドロップダウンを開く
    </button>

    <div
      v-if="isOpen"
      v-click-outside="closeDropdown"
      class="dropdown"
    >
      <ul>
        <li @click="selectItem('item1')">アイテム1</li>
        <li @click="selectItem('item2')">アイテム2</li>
        <li @click="selectItem('item3')">アイテム3</li>
      </ul>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        isOpen: false,
      };
    },

    methods: {
      closeDropdown() {
        this.isOpen = false;
      },

      selectItem(item) {
        console.log('選択されたアイテム:', item);
        this.isOpen = false;
      },
    },
  };
</script>

Level 4：外部ライブラリ統合ディレクティブ

最後に、Chart.js を統合したディレクティブを作成してみましょう。これは実際のプロジェクトでよく使われるパターンです：

typescript// v-chart ディレクティブ（Chart.js統合）
import Chart from 'chart.js/auto';

Vue.directive('chart', {
  bind(el, binding) {
    // 初期化フラグを設定
    el._chartInitialized = false;
  },

  inserted(el, binding) {
    initChart(el, binding);
  },

  update(el, binding) {
    updateChart(el, binding);
  },

  unbind(el) {
    destroyChart(el);
  },
});

function initChart(el, binding) {
  try {
    // canvas要素の確認
    if (el.tagName !== 'CANVAS') {
      throw new Error(
        'v-chart directive can only be used on canvas elements'
      );
    }

    // 設定の検証
    if (
      !binding.value ||
      typeof binding.value !== 'object'
    ) {
      throw new Error(
        'v-chart requires configuration object'
      );
    }

    // チャートの初期化
    el._chart = new Chart(el, binding.value);
    el._chartInitialized = true;
  } catch (error) {
    console.error('Chart initialization failed:', error);

    // エラー時の代替表示
    el.style.display = 'flex';
    el.style.alignItems = 'center';
    el.style.justifyContent = 'center';
    el.style.backgroundColor = '#f8f9fa';
    el.style.color = '#6c757d';

    // エラーメッセージを表示
    const errorMsg = el.getContext('2d');
    errorMsg.font = '14px Arial';
    errorMsg.fillText(
      'チャートの読み込みに失敗しました',
      10,
      30
    );
  }
}

function updateChart(el, binding) {
  if (el._chart && el._chartInitialized) {
    try {
      // データの更新
      el._chart.data = binding.value.data;
      el._chart.options = binding.value.options;
      el._chart.update();
    } catch (error) {
      console.error('Chart update failed:', error);
    }
  }
}

function destroyChart(el) {
  if (el._chart) {
    try {
      el._chart.destroy();
    } catch (error) {
      console.error('Chart destruction failed:', error);
    }
    delete el._chart;
    el._chartInitialized = false;
  }
}

使用例：

html<template>
  <div>
    <h2>売上データ</h2>
    <canvas
      v-chart="chartConfig"
      width="400"
      height="200"
    ></canvas>

    <button @click="updateData">データを更新</button>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        chartConfig: {
          type: 'bar',
          data: {
            labels: ['1月', '2月', '3月', '4月', '5月'],
            datasets: [
              {
                label: '売上',
                data: [12, 19, 3, 5, 2],
                backgroundColor: 'rgba(54, 162, 235, 0.2)',
                borderColor: 'rgba(54, 162, 235, 1)',
                borderWidth: 1,
              },
            ],
          },
          options: {
            responsive: true,
            scales: {
              y: {
                beginAtZero: true,
              },
            },
          },
        },
      };
    },

    methods: {
      updateData() {
        // ランダムなデータで更新
        this.chartConfig.data.datasets[0].data = [
          Math.floor(Math.random() * 20),
          Math.floor(Math.random() * 20),
          Math.floor(Math.random() * 20),
          Math.floor(Math.random() * 20),
          Math.floor(Math.random() * 20),
        ];

        // リアクティブな更新をトリガー
        this.$forceUpdate();
      },
    },
  };
</script>

実際のプロジェクトへの適用例

これまで学んだことを組み合わせて、実際のプロジェクトで使える統合的なディレクティブを作成してみましょう。権限管理システムと連携した表示制御ディレクティブです：

typescript// v-permission ディレクティブ（権限ベースの表示制御）
Vue.directive('permission', {
  bind(el, binding, vnode) {
    checkPermission(el, binding, vnode);
  },

  update(el, binding, vnode) {
    checkPermission(el, binding, vnode);
  },
});

function checkPermission(el, binding, vnode) {
  // Vue インスタンスから現在のユーザー情報を取得
  const vm = vnode.context;
  const currentUser = vm.$store?.state?.auth?.user;

  if (!currentUser) {
    handleNoPermission(el, binding);
    return;
  }

  // 権限チェック
  const requiredPermission = binding.value;
  const hasPermission = checkUserPermission(
    currentUser,
    requiredPermission
  );

  if (!hasPermission) {
    handleNoPermission(el, binding);
  } else {
    // 権限がある場合は要素を表示
    el.style.display = '';
    el.style.opacity = '1';
  }
}

function checkUserPermission(user, permission) {
  // 配列形式の権限チェック
  if (Array.isArray(permission)) {
    return permission.some((p) =>
      user.permissions.includes(p)
    );
  }

  // 文字列形式の権限チェック
  return user.permissions.includes(permission);
}

function handleNoPermission(el, binding) {
  // モディファイアーに応じた処理
  if (binding.modifiers.hide) {
    el.style.display = 'none';
  } else if (binding.modifiers.disable) {
    el.disabled = true;
    el.style.opacity = '0.5';
  } else {
    // デフォルトは非表示
    el.style.display = 'none';
  }
}

このディレクティブの使用例：

html<template>
  <div>
    <!-- 管理者のみ表示 -->
    <button v-permission="'admin'" @click="deleteUser">
      ユーザーを削除
    </button>

    <!-- 編集権限がない場合は無効化 -->
    <input
      v-permission:edit.disable="'edit_posts'"
      v-model="postTitle"
      placeholder="記事タイトル"
    />

    <!-- 複数の権限のいずれかがあれば表示 -->
    <div v-permission="['admin', 'moderator']">
      <h3>管理者・モデレーター用パネル</h3>
      <!-- 管理機能 -->
    </div>
  </div>
</template>

まとめ

カスタムディレクティブ設計のベストプラクティス

この記事を通じて、Vue.js のカスタムディレクティブの威力を実感していただけたでしょうか。最後に、実際のプロジェクトで活用する際の重要なポイントをまとめておきます。

ポイント	説明	実装例
単一責任の原則	一つのディレクティブは一つの機能のみ	`v-focus`、`v-click-outside`
エラーハンドリング	予期せぬ状況に対する適切な処理	try-catch、型チェック
メモリリーク対策	イベントリスナーの適切な削除	`unbind`フックでのクリーンアップ
パフォーマンス考慮	不要な処理を避ける	条件分岐、`nextTick`の活用

カスタムディレクティブを設計する際の心構えとして、「シンプルで理解しやすく、かつ再利用可能」 を常に意識してください。複雑すぎるディレクティブは、かえってコードの保守性を損なう可能性があります。

typescript// 良い例：シンプルで明確な責任
Vue.directive('tooltip', {
  bind(el, binding) {
    // ツールチップの表示のみに特化
    setupTooltip(el, binding.value);
  },
});

// 避けるべき例：複数の責任を持つディレクティブ
Vue.directive('super-directive', {
  bind(el, binding) {
    // ツールチップ、バリデーション、アニメーションなど
    // 複数の機能を詰め込むのは避ける
  },
});

避けるべきアンチパターン

長年の開発経験から見えてきた、カスタムディレクティブでやってはいけないアンチパターンをご紹介します：

1. DOM 操作と状態管理の混在

typescript// ❌ 避けるべきパターン
Vue.directive('bad-example', {
  bind(el, binding, vnode) {
    // ディレクティブ内でストアを直接操作
    vnode.context.$store.commit('SET_USER_DATA', data);

    // DOM 操作と状態管理が混在
    el.textContent = vnode.context.$store.state.user.name;
  },
});

// ✅ 推奨パターン
Vue.directive('good-example', {
  bind(el, binding) {
    // DOM 操作のみに集中
    el.textContent = binding.value;
  },
});

2. 過度な抽象化

typescript// ❌ 複雑すぎる抽象化
Vue.directive('over-engineered', {
  bind(el, binding) {
    const config = parseComplexConfig(binding.value);
    const strategy = createStrategy(config);
    const processor = new ElementProcessor(strategy);
    // ...複雑な処理
  },
});

// ✅ 適切なレベルの抽象化
Vue.directive('simple-tooltip', {
  bind(el, binding) {
    el.title = binding.value;
  },
});

3. エラーハンドリングの不備

よく見る問題のあるパターンとして、以下のようなエラーが発生することがあります：

phpTypeError: Cannot read properties of null (reading 'addEventListener')
    at bind (custom-directive.js:15:8)
    at VueComponent.directive (vue.runtime.esm.js:7851:9)

これを防ぐための適切なエラーハンドリング：

typescriptVue.directive('safe-listener', {
  bind(el, binding) {
    // 要素の存在確認
    if (!el || !el.addEventListener) {
      console.warn('Invalid element for v-safe-listener');
      return;
    }

    // ハンドラーの型確認
    if (typeof binding.value !== 'function') {
      console.warn('v-safe-listener expects a function');
      return;
    }

    try {
      el.addEventListener('click', binding.value);
    } catch (error) {
      console.error('Failed to add event listener:', error);
    }
  },
});