閉じる

WordPressでJSを正しく読み込む「wp_enqueue_script」の使い方：依存関係や読込位置の制御

広告

WordPressのテーマ開発やカスタマイズにおいて、JavaScriptファイルを読み込む作業は避けて通れません。

しかし、HTMLの<head>タグ内に直接<script>タグを記述する方法は、WordPressの作法としては推奨されていません。

WordPressにはスクリプトを適切に管理するための専用関数であるwp_enqueue_scriptが用意されています。

この関数を正しく使いこなすことで、スクリプトの重複読み込みを防ぎ、サイトの表示速度や動作の安定性を向上させることができます。

本記事では、wp_enqueue_scriptの基本的な使い方から、依存関係の解決、読み込みタイミングの制御といった応用的な手法まで詳しく解説します。

目次 [ close ]
  1. なぜwp_enqueue_scriptを使用する必要があるのか
  2. wp_enqueue_scriptの基本構文
    1. 引数の詳細解説
  3. 実践的なスクリプトの読み込み方法
  4. 依存関係（$deps）の管理と制御
    1. jQueryに依存するスクリプトの例
  5. 読み込み位置と戦略の最適化
    1. footerへの配置（in_footer）
    2. asyncとdeferの使い分け
  6. wp_register_scriptとの違い
  7. PHPからJavaScriptへデータを渡す方法
  8. 条件分岐による読み込みの最適化
  9. まとめ

なぜwp_enqueue_scriptを使用する必要があるのか

WordPressサイトでは、テーマだけでなく多くのプラグインが独自のJavaScriptを使用しています。

もし各プラグインが自由に<script>タグを出力してしまうと、同じライブラリが何度も読み込まれる原因になります。

例えば、複数のプラグインが個別にjQueryを読み込んだ場合、スクリプトの競合が発生し、サイトの一部が正常に動作しなくなる恐れがあります。

wp_enqueue_scriptは、こうしたスクリプトの管理をWordPress本体に一元化するための仕組みです。

この関数を通じて登録されたスクリプトは、WordPressのキュー（待ち行列）に追加され、依存関係に基づいて最適な順番で出力されます。

また、同じハンドル名を持つスクリプトは一度しか読み込まれないため、二重読み込みによるエラーを未然に防ぐことができます。

モダンなWeb開発において、パフォーマンス最適化は欠かせない要素の一つです。

公式の推奨ルールに従うことは、メンテナンス性の高いサイトを構築するための第一歩と言えます。

wp_enqueue_scriptの基本構文

まずは、wp_enqueue_script関数の基本的な書き方を確認しましょう。

この関数は、主にテーマのfunctions.php内で使用されます。

PHP
wp_enqueue_script( $handle, $src, $deps, $ver, $args );

各引数の役割を理解することが、適切なスクリプト管理への近道です。

引数の詳細解説

wp_enqueue_scriptには5つの引数が用意されています。

それぞれの設定内容によって、スクリプトの挙動が大きく変わります。

引数型説明
$handlestringスクリプトを識別するための独自の名前（ハンドル名）。
$srcstringファイルのURL。フルパスで指定します。
$depsarrayこのスクリプトより先に読み込む必要があるスクリプトのハンドル名。
$verstring|boolスクリプトのバージョン番号。キャッシュ対策に使用されます。
$argsbool|array読み込み位置や戦略（async/defer）を指定するための設定。

最近のWordPress（バージョン6.3以降）では、第5引数が単なる真偽値（フッターに置くかどうか）から、より詳細な配列指定が可能になりました。

これにより、async（非同期読み込み）やdefer（遅延読み込み）を簡単に制御できるようになっています。

実践的なスクリプトの読み込み方法

実際に関数を使用する際は、WordPressのwp_enqueue_scriptsというアクションフックを利用します。

以下のコード例では、テーマ内のjsフォルダにあるmain.jsを読み込む方法を示しています。

PHP
/**
 * スクリプトを読み込むための関数
 */
function my_theme_enqueue_scripts() {
    // テーマのディレクトリURLを取得し、パスを完成させる
    $script_url = get_template_directory_uri() . '/assets/js/main.js';

    // スクリプトの登録とキューへの追加
    wp_enqueue_script(
        'my-main-script',        // ハンドル名
        $script_url,             // ファイルURL
        array(),                 // 依存関係（なし）
        '1.0.0',                 // バージョン
        array(
            'in_footer' => true, // フッターで読み込む
            'strategy'  => 'defer' // 遅延読み込みを指定
        )
    );
}
// アクションフックへの登録
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_scripts' );

このコードをfunctions.phpに記述すると、HTMLソースの終了ボディタグの直前にスクリプトが出力されます。

実行結果として出力されるHTMLは以下のようになります。

実行結果
<script src="https://example.com/wp-content/themes/my-theme/assets/js/main.js?ver=1.0.0" id="my-main-script-js" defer></script>

注目すべき点は、自動的に?ver=1.0.0というクエリパラメータが付与されていることです。

これにより、ファイルを更新した際にバージョン番号を変更すれば、ブラウザのキャッシュを強制的に更新させることができます。

依存関係（$deps）の管理と制御

JavaScriptの開発では、特定のライブラリに依存したコードを書くことがよくあります。

例えば、jQueryを使用するスクリプトの場合、jQuery本体よりも先に読み込まれなければエラーが発生します。

wp_enqueue_scriptの第3引数を使用すれば、この順番をWordPressが自動的に調整してくれます。

jQueryに依存するスクリプトの例

以下の例では、自作のスクリプトがjQueryを必要としている場合の指定方法を解説します。

PHP
function my_custom_jquery_script() {
    wp_enqueue_script(
        'custom-interaction',
        get_template_directory_uri() . '/js/interaction.js',
        array( 'jquery' ), // jQueryのハンドル名を指定
        null,              // バージョンを指定しない場合はnull
        true               // フッター読み込み（旧形式の指定）
    );
}
add_action( 'wp_enqueue_scripts', 'my_custom_jquery_script' );

このようにarray( 'jquery' )と記述するだけで、WordPressは自動的に標準搭載されているjQueryを先に読み込んでくれます。

開発者が読み込み順序を気にしてHTMLを手書きする必要は一切ありません。

依存関係には複数のハンドルを指定することも可能です。

例えば、jQueryと特定のプラグインの両方を必要とする場合は、array( 'jquery', 'another-plugin' )のように記述します。

読み込み位置と戦略の最適化

ページの読み込み速度（Core Web Vitals）を向上させるためには、スクリプトの読み込みタイミングが非常に重要です。

デフォルトではスクリプトは<head>内で読み込まれますが、これはレンダリングブロック（描画の遅延）の原因となります。

特別な理由がない限り、ビジュアルに影響しないスクリプトはフッターで読み込むことが推奨されます。

第5引数の配列で'in_footer' => trueを指定することで、ページのコンテンツがすべて読み込まれた後にスクリプトが実行されるようになります。

asyncとdeferの使い分け

WordPress 6.3以降では、strategyというキーを用いて、より高度な読み込み制御が可能になりました。

  • defer（推奨）：HTMLの解析を邪魔せず、解析完了後に実行されます。実行順序が維持されるため、依存関係がある場合に適しています。
  • async：HTMLの解析と並行してダウンロードされ、準備ができ次第実行されます。実行順序が保証されないため、独立したスクリプトに適しています。
PHP
wp_enqueue_script(
    'optimized-script',
    get_template_directory_uri() . '/js/optimized.js',
    array(),
    filemtime( get_template_directory() . '/js/optimized.js' ), // ファイルの更新日時をバージョンにする
    array(
        'strategy'  => 'defer',
        'in_footer' => true
    )
);

上記のコードでは、filemtime関数を使用して、ファイルが更新されるたびに自動でバージョンが切り替わるように工夫しています。

これにより、開発中にキャッシュに悩まされることがなくなります。

wp_register_scriptとの違い

wp_enqueue_scriptに似た関数として、wp_register_scriptがあります。

この2つの関数の違いを正しく理解しておくことは、大規模な開発において非常に役立ちます。

wp_register_scriptは、スクリプトを「登録」するだけで、すぐには出力しません。

一方でwp_enqueue_scriptは、スクリプトを「キューに追加」し、実際に出力する準備を整えます。

例えば、特定の固定ページでのみ使用するスクリプトがある場合、あらかじめfunctions.phpで登録だけしておき、必要なページ内でのみ呼び出すという使い方が可能です。

PHP
// 1. まずは登録だけしておく（functions.php）
function my_register_assets() {
    wp_register_script(
        'special-library',
        'https://cdn.example.com/special.js',
        array(),
        '2.5.0',
        true
    );
}
add_action( 'wp_enqueue_scripts', 'my_register_assets' );

// 2. 必要な時だけ呼び出す（page-contact.phpなどのテンプレート内）
if ( is_page( 'contact' ) ) {
    wp_enqueue_script( 'special-library' );
}

このように使い分けることで、コードの管理が整理され、不要なページで余計なスクリプトが読み込まれるのを防ぐことができます。

PHPからJavaScriptへデータを渡す方法

JavaScript側で、WordPressのサイトURLや、投稿のタイトル、AJAX用のエンドポイントURLなどが必要になることがあります。

スクリプトファイル内に直接PHPを書くことはできないため、wp_localize_scriptという関数を使用します。

PHP
function my_pass_data_to_js() {
    // まずスクリプトをキューに入れる
    wp_enqueue_script( 'data-receiver', get_template_directory_uri() . '/js/receiver.js', array(), '1.0', true );

    // JSに渡すデータの準備
    $data_array = array(
        'ajax_url' => admin_url( 'admin-ajax.php' ),
        'site_name' => get_bloginfo( 'name' ),
        'user_id'   => get_current_user_id()
    );

    // スクリプトにデータを紐付ける
    wp_localize_script( 'data-receiver', 'mySiteData', $data_array );
}
add_action( 'wp_enqueue_scripts', 'my_pass_data_to_js' );

この設定を行うと、JavaScript側でmySiteDataというグローバルオブジェクトとしてデータにアクセスできるようになります。

JavaScript
// receiver.js 内での使用例
console.log(mySiteData.site_name);
console.log(mySiteData.ajax_url);

この手法は、動的な値をフロントエンドに安全に受け渡すための最もクリーンな方法です。

条件分岐による読み込みの最適化

すべてのページで同じJavaScriptを読み込むのは、パフォーマンスの観点から非効率です。

WordPressの条件分岐タグを活用して、必要な場所でのみ読み込む設定を行いましょう。

条件分岐タグ説明
is_front_page()サイトのフロントページ（トップページ）のみ。
is_single()個別の投稿ページのみ。
is_page( ‘slug’ )特定のページスラッグを持つ固定ページのみ。
is_archive()一覧ページ（カテゴリーやタグ）のみ。

具体的なコードの実装例を以下に示します。

PHP
function my_conditional_enqueue() {
    // お問い合わせページのみでGoogle Maps APIなどを読み込む
    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'google-maps', 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY', array(), null, true );
    }

    // フロントページのみでスライダーのスクリプトを読み込む
    if ( is_front_page() ) {
        wp_enqueue_script( 'hero-slider', get_template_directory_uri() . '/js/slider.js', array( 'jquery' ), '1.2', true );
    }
}
add_action( 'wp_enqueue_scripts', 'my_conditional_enqueue' );

このように条件を絞ることで、ページ全体の軽量化を図り、ユーザー体験を向上させることができます。

まとめ

WordPressにおけるJavaScriptの読み込みは、単にファイルを表示させるだけではなく、システム全体との整合性を保つための重要な工程です。

wp_enqueue_scriptを正しく活用することで、スクリプトの競合回避、読み込み順序の適正化、そしてパフォーマンスの向上が実現します。

特に、第3引数による依存関係の指定や、第5引数でのstrategy（defer/async）の設定は、現代の高速なWebサイト制作において欠かせないテクニックです。

また、wp_localize_scriptを使ったPHPとJavaScriptの連携や、条件分岐タグによる読み込みの最適化も積極的に取り入れていきましょう。

WordPressのルールに則った正しい実装を行うことで、プラグインとの競合に強い、堅牢なサイトを構築することができます。

今回紹介した基本原則を忘れずに、今後のテーマ開発やカスタマイズに役立ててください。

URLをコピーしました！