【WordPress】wp_enqueue_scriptの使い方|正しいJS読み込みと依存関係の管理

【WordPress】wp_enqueue_scriptの使い方|正しいJS読み込みと依存関係の管理 WordPress

WordPressでJavaScriptを読み込む際に推奨される方法がwp_enqueue_scriptです。テーマやプラグインで正しくスクリプトを読み込むことで、不要な競合を防ぎ、依存関係を管理しやすくなります。直接header.phpやfooter.phpにscriptタグを記述する方法も可能ですが、WordPressの仕組みを活かすためにはenqueue関数を使うのが基本です。

スポンサーリンク

wp_enqueue_scriptの基本構文

wp_enqueue_scriptは以下のように記述します。主な引数はハンドル名、読み込むファイルのURL、依存スクリプト、バージョン番号、フッターでの読み込み有無です。

wp_enqueue_scriptの基本構文
wp_enqueue_script(
  string $handle,
  string $src = '',
  array $deps = array(),
  string|bool|null $ver = false,
  bool|array $in_footer = false
)

WordPress 6.3以降は、第5引数にboolの代わりに配列を渡すことで、フッター読み込みの指定に加えてdefer・asyncの読み込み戦略も同時に指定できます(詳しくは後述)。

基本的な使い方

functions.phpに以下のようなコードを記述します。テーマディレクトリ内のassets/js/common.jsを読み込み、jQueryを依存関係として指定、フッターで読み込む例です。

functions.php:基本の読み込み
<?php
add_action('wp_enqueue_scripts', function () {
  $rel  = '/assets/js/common.js';
  $file = get_template_directory() . $rel;

  wp_enqueue_script(
    'theme-common',
    get_template_directory_uri() . $rel,
    array('jquery'),
    file_exists($file) ? filemtime($file) : null,
    true
  );
});

filemtime()はファイルの更新日時をバージョン番号として使うことでキャッシュを自動更新するテクニックですが、対象ファイルが存在しない場合にPHPの警告が出るため、必ずfile_exists()で確認してから呼び出してください。

依存関係の管理

依存関係を正しく指定することで、ライブラリやプラグインの競合を防げます。例えば、Slickスライダーを利用する場合は以下のように記述します。

functions.php:Slickスライダーの読み込み
<?php
add_action('wp_enqueue_scripts', function () {
  // Slick本体
  wp_enqueue_script(
    'slick',
    get_template_directory_uri() . '/assets/slick/slick.min.js',
    array('jquery'),
    '1.8.1',
    true
  );

  // 初期化用スクリプト
  $rel  = '/assets/js/slick-init.js';
  $file = get_template_directory() . $rel;

  wp_enqueue_script(
    'slick-init',
    get_template_directory_uri() . $rel,
    array('slick'),
    file_exists($file) ? filemtime($file) : null,
    true
  );
});

管理画面での読み込み

wp_enqueue_scriptは管理画面でも利用可能です。管理画面ではフックをadmin_enqueue_scriptsに切り替えます。

functions.php:管理画面でのスクリプト読み込み
<?php
add_action('admin_enqueue_scripts', function ($hook) {
  if ($hook === 'post.php' || $hook === 'post-new.php') {
    $rel  = '/assets/js/admin.js';
    $file = get_template_directory() . $rel;

    wp_enqueue_script(
      'admin-custom',
      get_template_directory_uri() . $rel,
      array('jquery'),
      file_exists($file) ? filemtime($file) : null,
      true
    );
  }
});

CDNスクリプトの読み込み

CDNからスクリプトを読み込む場合も同様にenqueueで管理できます。

functions.php:CDNスクリプトの読み込み
<?php
add_action('wp_enqueue_scripts', function () {
  wp_enqueue_script(
    'axios',
    'https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js',
    array(),
    null,
    true
  );
});

CDNのURLにバージョン番号を含めない場合、常に最新版が読み込まれるため、本番環境では意図しない更新で動作が変わらないよう、axios@1.6.0のようにバージョンを固定することをおすすめします。

defer・asyncを指定する(WordPress 6.3以降)

WordPress 6.3以降では、第5引数に配列を渡すことで読み込み戦略を指定できます。

functions.php:defer読み込みの指定
<?php
add_action('wp_enqueue_scripts', function () {
  $rel  = '/assets/js/common.js';
  $file = get_template_directory() . $rel;

  wp_enqueue_script(
    'theme-common',
    get_template_directory_uri() . $rel,
    array('jquery'),
    file_exists($file) ? filemtime($file) : null,
    array(
      'in_footer' => true,
      'strategy'  => 'defer', // 'defer' または 'async'
    )
  );
});

strategyには'defer'または'async'を指定できます。依存関係があるライブラリはdefer、独立した計測タグなどはasyncが安全です。

よくある質問(FAQ)

Qwp_enqueue_script()でjQueryに依存するJSを正しく読み込むには?
Awp_enqueue_script(‘my-script’, get_stylesheet_directory_uri() . ‘/js/my-script.js’, array(‘jquery’), ‘1.0’, true)のように第3引数に依存ハンドル配列を渡します。jQueryは自動でno-conflictモードで読み込まれます。
Qスクリプトの読み込み順序を制御するには?
A依存関係配列で読み込み順が自動的に決まります。AがBに依存する場合、A登録時のdepsにBのハンドルを指定するとBが先に読み込まれます。
Q条件付きでスクリプトを読み込む(特定のページのみ)には?
Awp_enqueue_scriptsフックのコールバック内で条件タグを確認し、条件が真の場合のみwp_enqueue_script()を呼び出します。is_page()・is_singular()等を組み合わせます。

まとめ

wp_enqueue_scriptを使えばJavaScriptの読み込み順や依存関係をWordPressに管理させることができ、コードの衝突や重複読み込みを防げます。テーマやプラグインを開発する際は必ずこの関数を利用し、必要に応じて依存配列やバージョン番号を適切に指定することが重要です。filemtime()でバージョン管理する場合は、ファイルの存在確認も忘れないようにしましょう。