WordPressでjQueryを読み込む方法｜functions.phpの書き方と動かない原因を初心者向けに解説

WordPressでjQueryを書いたのに「$ is not a functionと表示される」「main.jsが先に実行されて動かない」と困ることがありますよね。

WordPressでは、header.phpへCDNの<script>タグを直接追加するのではなく、functions.phpからwp_enqueue_script()を使って読み込むのが基本です。

この記事では、WordPressに同梱されたjQueryと自作のmain.jsを正しい順番で読み込み、実際にクリック処理が動くところまで進めます。コードをどのファイルへ書くのかも順番に確認できます。

結論：main.jsの依存関係にjqueryを指定する
WordPressでjQueryを読み込む仕組み
作業前に用意するファイル
functions.phpでjQueryとmain.jsを読み込む
1. コードの引数が表す内容
main.jsにjQueryの処理を書く
固定ページに動作確認用のHTMLを置く
実際の表示と動作を確認する
WordPressで$が使えないときの書き方
読み込めたかをブラウザで確認する
jQueryを二重に読み込まない
WordPressでjQueryが動かない原因と対処法
jQueryの基本構文も確認しておこう
まとめ

結論：main.jsの依存関係にjqueryを指定する

自作のJavaScriptでjQueryを使う場合は、wp_enqueue_script()の第3引数へarray( 'jquery' )を指定します。

これにより、WordPressがjQueryを先に読み込み、そのあとでmain.jsを読み込みます。jQuery本体を別途ダウンロードしたり、CDNを追加したりする必要はありません。

function wp_load_enqueue_scripts() {
    wp_enqueue_script(
        'wp-load-main',
        get_theme_file_uri( '/assets/js/main.js' ),
        array( 'jquery' ),
        wp_get_theme()->get( 'Version' ),
        array( 'in_footer' => true )
    );
}
add_action( 'wp_enqueue_scripts', 'wp_load_enqueue_scripts' );

このコードは、使用中のテーマにあるfunctions.phpの末尾へ追加します。すでにファイル先頭に<?phpがある場合は、PHPの開始タグをもう一度書かないでください。

WordPressでjQueryを読み込む仕組み

WordPressにはjQueryが登録されています。ただし、すべてのページで無条件に出力されるわけではありません。

テーマやプラグインがハンドル名jqueryを必要なスクリプトとして指定すると、WordPressが依存関係を確認して読み込みます。ハンドルとは、WordPressが各スクリプトを管理するための識別名です。

WordPressがjQueryを先に読み込み、その後にmain.jsを読み込む依存関係の図

図のようにmain.jsがjQueryへ依存することを伝えておけば、読み込み順を自分で調整する必要がありません。重複読み込みも避けやすくなります。

WordPress公式のTheme Handbookでも、テーマ内のJavaScriptはHTMLへ直書きせず、wp_enqueue_script()で読み込む方法が案内されています。詳しい引数はIncluding Assetsとwp_enqueue_script()のリファレンスで確認できます。

作業前に用意するファイル

今回は、子テーマまたは自作テーマに次の2ファイルがある想定で進めます。

functions.php：WordPressへスクリプトの情報を登録するファイル
assets/js/main.js：jQueryの処理を書く自作JavaScriptファイル

配布テーマを直接編集すると、テーマ更新時に変更が消える場合があります。市販・公式ディレクトリのテーマを使っている場合は、子テーマを用意してから編集してください。

assets/jsフォルダがない場合は、使用中のテーマフォルダ内に作成します。フォルダ名を変えるときは、後ほどfunctions.phpへ書くパスも同じ名前に合わせます。

functions.phpでjQueryとmain.jsを読み込む

まず、assets/js/main.jsを作成します。中身は空のままで構いません。

次に、使用中のテーマのfunctions.phpを開き、末尾へ次のコードを追加します。

function wp_load_enqueue_scripts() {
    wp_enqueue_script(
        'wp-load-main',
        get_theme_file_uri( '/assets/js/main.js' ),
        array( 'jquery' ),
        wp_get_theme()->get( 'Version' ),
        array( 'in_footer' => true )
    );
}
add_action( 'wp_enqueue_scripts', 'wp_load_enqueue_scripts' );

コードの引数が表す内容

引数	今回の指定	役割
ハンドル	`wp-load-main`	自作スクリプトを識別する一意の名前
URL	`get_theme_file_uri()`	使用中のテーマからmain.jsのURLを取得
依存関係	`array( 'jquery' )`	main.jsより先にjQueryを読み込む
バージョン	テーマのバージョン	更新時のキャッシュ管理に使用
読み込み位置	`in_footer`	本文のあとでスクリプトを出力

特に重要なのは第3引数です。ここが空のarray()だと、main.jsがjQueryより先に実行される可能性があります。

get_theme_file_uri()は、子テーマ側にファイルがあれば子テーマのURLを返し、なければ親テーマも確認します。記事と異なる場所へmain.jsを置いた場合は、/assets/js/main.jsを実際の場所に変更してください。

main.jsにjQueryの処理を書く

続いて、先ほど作ったassets/js/main.jsへクリック処理を書きます。

jQuery(function ($) {
    $('.js-toggle-button').on('click', function () {
        const $target = $('.js-toggle-target');
        const isVisible = $target
            .toggleClass('is-visible')
            .hasClass('is-visible');

        $(this).attr('aria-expanded', isVisible);
    });
});

外側のjQuery(function ($) { ... });は、HTMLの準備ができてから処理を実行する書き方です。引数として受け取った$は、この関数の中だけでjQueryとして使えます。

クリックすると、説明文へis-visibleクラスを付け外しします。同時にボタンのaria-expandedも更新するため、支援技術にも開閉状態が伝わります。

固定ページに動作確認用のHTMLを置く

WordPressの固定ページを開き、「カスタムHTML」ブロックへ次のHTMLを追加します。

<button
  class="js-toggle-button"
  type="button"
  aria-expanded="false"
>
  説明を表示する
</button>

<p class="js-toggle-target">
  jQueryが正しい順番で読み込まれ、
  クリックイベントが動きました。
</p>

説明文を最初は非表示にするため、テーマのstyle.cssへ次のCSSを追加します。

.js-toggle-target {
    display: none;
}

.js-toggle-target.is-visible {
    display: block;
}

実際の表示と動作を確認する

上のコードをローカルWordPressで実行しました。ページを開いた直後は、次のようにボタンだけが表示されます。

「説明を表示する」ボタンを押すと、main.jsのクリックイベントが実行され、説明文が表示されました。

ブラウザ上では、WordPress同梱のjQueryが先に読み込まれ、そのあとに確認用のmain.jsが読み込まれていることも確認しています。掲載したJavaScriptと画像の動作は一致しています。

WordPressで$が使えないときの書き方

WordPressのjQueryは、ほかのライブラリと$が衝突しないように扱われます。そのため、ファイルの先頭からいきなり$('.item')と書くと、$ is not a functionや$ is not definedになることがあります。

次のように、jQueryを引数$として受け取る関数で処理全体を囲みます。

jQuery(function ($) {
    // この中では $ をjQueryとして使用できます。
    $('.item').addClass('is-active');
});

jQueryの「Q」は大文字です。jquery(function () {})のように小文字で書くと別の名前として扱われます。

WordPressのJavaScriptコーディング規約でも、jQueryオブジェクトを無名関数へ渡し、その中で$を使う形が案内されています。詳しくはJavaScript Coding Standardsを参照してください。

読み込めたかをブラウザで確認する

コードを保存したら、対象ページを再読み込みします。変化がないときは、次の順番で確認すると原因を切り分けやすくなります。

ブラウザの開発者ツールを開く
「Network」タブでページを再読み込みする
検索欄へjqueryと入力し、jQueryのファイルが成功しているか確認する
続けてmain.jsを探し、ステータスが404になっていないか確認する
「Console」タブに赤いエラーがないか確認する

jQueryだけが表示され、main.jsがない場合はファイルパスを確認します。両方あるのに動かない場合は、コンソールの最初のエラーから直していきましょう。

jQueryを二重に読み込まない

WordPress同梱のjQueryを使う設定に加えて、header.phpへCDNのjQueryを直書きすると、同じライブラリが二重に読み込まれることがあります。

二重読み込みは、プラグインのイベントが複数回動く、想定と違うバージョンを参照するなどの原因になります。特別な理由がなければ、wp_deregister_script( 'jquery' )でWordPress標準のjQueryを解除する方法も避けてください。

通常のHTMLサイトでCDNを使う方法を知りたい場合は、次の記事でscriptタグの位置や読み込み確認を詳しく解説しています。WordPressの記事では、ここまで説明したwp_enqueue_script()を優先します。

jQueryをCDNで読み込む方法｜scriptタグの設置場所と動かない原因を初心者向けに解説

WordPressでjQueryが動かない原因と対処法

jQuery is not definedと表示される

main.jsの依存関係にjqueryが指定されているか確認します。array()ではなく、array( 'jquery' )です。

$ is not a functionと表示される

main.jsの処理をjQuery(function ($) { ... });で囲みます。CDNを追加して解決しようとすると、二重読み込みになるので注意してください。

main.jsが404になる

get_theme_file_uri( '/assets/js/main.js' )のパスと、実際のフォルダ名・ファイル名を照らし合わせます。サーバーでは大文字と小文字が区別される場合があるため、Main.jsとmain.jsの違いも確認します。

コードを直しても古い動作のままになる

ブラウザキャッシュやキャッシュ系プラグインが古いmain.jsを返している可能性があります。まずブラウザの強制再読み込みを試し、続いてWordPress側や配信サービスのキャッシュを削除します。

開発中にファイル更新を確実に反映したい場合は、先ほどのfunctions.phpのコードを次の内容へ置き換え、バージョン引数へ更新時刻を使う方法もあります。

function wp_load_enqueue_scripts() {
    $script_path = get_theme_file_path( '/assets/js/main.js' );

    wp_enqueue_script(
        'wp-load-main',
        get_theme_file_uri( '/assets/js/main.js' ),
        array( 'jquery' ),
        filemtime( $script_path ),
        array( 'in_footer' => true )
    );
}
add_action( 'wp_enqueue_scripts', 'wp_load_enqueue_scripts' );

このコードはmain.jsが実在する前提です。ファイルを作成してから追加してください。本番公開後はテーマのバージョン番号で管理する方法でも構いません。

テーマにwp_footer()がない

in_footerをtrueにしたスクリプトは、テーマのwp_footer()を利用して出力されます。自作テーマの場合は、footer.phpの</body>直前に<?php wp_footer(); ?>があるか確認してください。

jQueryの基本構文も確認しておこう

読み込みに成功しても、セレクターやイベントの書き方が違うと処理は動きません。jQueryの基本構文から確認したい方は、次の記事もあわせてご覧ください。

jQueryの書き方｜基本構文・セレクター・メソッド・イベントを初心者向けに解説

まとめ

WordPressでjQueryを使うときは、header.phpへCDNを直書きせず、functions.phpからwp_enqueue_script()で読み込みます。

自作のmain.jsへarray( 'jquery' )の依存関係を指定する
main.jsではjQuery(function ($) { ... });の中で$を使う
NetworkでjQueryとmain.js、ConsoleでJavaScriptエラーを確認する
WordPress標準のjQueryとCDN版を二重に読み込まない

まずは掲載したボタンの例をそのまま試し、jQueryが正しい順番で読み込まれるところから確認してみてください。