【WordPress】jQueryを読み込む方法｜子テーマ対応とfilemtime()でのキャッシュ管理

2024.08.16

WordPressの開発を進める中で、jQueryを活用したいと考えることがあるでしょう。WordPressにはデフォルトでjQueryが含まれていますが、適切な方法で読み込む必要があります。この記事では、jQueryと依存スクリプトを正しく読み込む方法を解説します。

この記事でわかること

  • wp_enqueue_script('jquery')でWordPress内蔵のjQueryを読み込む方法
  • 子テーマで正しく動作する依存スクリプトの登録方法
  • キャッシュを正しく更新するfilemtime()の使い方
  • noConflictモードへの対応
スポンサーリンク

wp_enqueue_scriptを使用してjQueryを読み込む

WordPressテーマやプラグインでjQueryを読み込む最も基本的な方法は、wp_enqueue_script関数を使用することです。この関数を使うことで、WordPressに同梱されているjQueryを適切に読み込むことができます。

functions.php：WordPress内蔵のjQueryを読み込む
function my_theme_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );
}
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_scripts' );

このコードにより、WordPressにデフォルトで含まれているjQueryが確実に読み込まれます。

jQueryに依存するスクリプトを登録する方法

jQueryを使用するカスタムスクリプトがある場合、その依存関係を指定して読み込む必要があります。依存関係を正しく指定することで、スクリプトの実行順序が保たれ、エラーを防ぐことができます。

functions.php：jQueryに依存するカスタムスクリプトを登録
function my_theme_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );

    $script_path = get_stylesheet_directory() . '/js/custom-script.js';
    $script_url  = get_stylesheet_directory_uri() . '/js/custom-script.js';

    wp_enqueue_script(
        'custom-script',
        $script_url,
        array( 'jquery' ),
        filemtime( $script_path ), // ファイル更新のたびに自動でキャッシュを更新
        true
    );
}
add_action( 'wp_enqueue_scripts', 'my_theme_enqueue_scripts' );
get_template_directory_uri()は親テーマのパスを返す
get_template_directory_uri() / get_template_directory() は親テーマのパスを返します。子テーマ（cocoon-child-masterなど）の /js/ にカスタムスクリプトを置いた場合、これらの関数を使うと親テーマ側のパスを探しに行ってしまい404になります。子テーマのファイルには get_stylesheet_directory()（サーバーパス）／get_stylesheet_directory_uri()（URL）を使ってください。
バージョン引数にnullを渡すとキャッシュが更新されない
本番WPコア（WP_Scripts::do_item()）を確認したところ、第4引数（バージョン）に明示的にnullを渡すとバージョンのクエリ文字列（?ver=...）自体が付与されなくなります（省略時の既定値falseならWordPressコアのバージョンにフォールバックしますが、nullは「バージョンなし」を意味します）。その結果、スクリプトファイルを更新しても、ブラウザやCDN側のキャッシュが自動的には切り替わらない可能性があります。filemtime()でファイルの更新日時を渡すことで、ファイルを更新するたびに確実にキャッシュが更新されるようになります。CSSでの同様の実装はCSSファイルの更新日時を取得してキャッシュを自動更新する方法でも解説しています。

jQueryのnoConflictモードへの対応方法

WordPressでは、jQueryが「noConflict」モードで動作します。このため、$シンボルを直接使用するとエラーが発生することがあります。これを防ぐために、jQueryを明示的に使用するか、即時関数でスコープを限定します。

jQueryコード内で$を安全に使う
jQuery( document ).ready( function ( $ ) {
    $( '#element' ).hide();
} );

もしくは、以下のように即時関数を使うことで、$を使えるようにスコープを限定することも可能です。

即時関数でスコープを限定
( function ( $ ) {
    $( '#element' ).hide();
} )( jQuery );

よくある質問（FAQ）

QWordPressでjQueryを正しく読み込む方法は？
Awp_enqueue_script(‘jquery’)でWordPressが内蔵するjQueryをエンキューします。scriptタグでCDNを直接読み込むのではなく、wp_enqueue_script経由が推奨です。依存関係も自動管理されます。
QjQueryのno-conflict問題でエラーが出る場合の対処法は？
AWordPressのjQueryはno-conflictモードで動作するため、$ではなくjQueryを使うか、(function($){ /* コード */ })(jQuery)のようにラップします。
Q外部CDNのjQueryとWordPress内蔵jQueryを併用するとどうなりますか？
A二重読み込みとなり競合が発生します。wp_deregister_script(‘jquery’)で内蔵を無効にして外部CDNに置き換えるか、wp_enqueue_scriptの依存関係機能を活用して一方を使うよう統一してください。

まとめ

  • 基本：wp_enqueue_script('jquery')で内蔵jQueryを読み込む
  • 子テーマ：get_stylesheet_directory(_uri)を使う（get_template_directory系は親テーマ用）
  • キャッシュ：バージョン引数はfilemtime()で自動更新する（nullは不可）
  • noConflict：$の代わりにjQueryを使うか即時関数でスコープを限定

これらの手順を踏むことで、子テーマ環境でもキャッシュの問題なくjQueryを活用できます。