WordPressにJavaScriptを追加する方法

WordPressにJavaScriptを追加すると、クリックに応じた表示切り替え、入力フォームの補助、独自のアニメーションなど、テーマの標準機能だけでは足りない動きを実装できます。ただし、テーマファイルへ<script>タグを直接貼り付ける方法は、依存関係や読み込み順、テーマ更新の影響を管理しにくくなります。

継続して管理するコードなら、WordPressが用意するスクリプト管理の仕組みを使うのが基本です。この記事では、wp_enqueue_script()を中心に、子テーマ内のJavaScriptを安全に読み込み、必要なページだけへ限定し、反映されないときに原因を切り分ける流れを解説します。

WordPressにJavaScriptを追加する主な方法

JavaScriptを置く場所は、変更の規模と保守期間で選びます。数行の一時的な検証と、サイトで長期運用する独自スクリプトを同じ方法で管理する必要はありません。

方法	向いている用途	注意点
テーマ・プラグインの専用機能	製品側が用意したカスタムJS欄で完結する小規模な追加	保存場所・読み込み位置・権限制御は製品仕様に従う
子テーマのJSファイルをenqueue	継続運用する独自処理、複数ページで使うコード	ファイルと読み込み処理をセットで管理する
プラグインでコード管理	テーマから独立させたい小～中規模の追加	停止時の影響、実行範囲、更新状況を確認する
HTML内へ直接記述	限定的な埋め込みコードなど、提供元がその形式を要求する場合	重複読込や権限、CSP、更新時の管理に注意する

本格的なカスタマイズでは、JavaScriptファイルを子テーマや専用プラグイン側に置き、WordPressから読み込む形が追跡しやすくなります。サイト全体のカスタマイズ方法を整理したい場合は、カスタマイズのハブ記事から変更内容に合う方法を選ぶのが安全です。

wp_enqueue_scriptでJavaScriptを安全に読み込む

WordPress公式は、フロント側のJavaScriptをページへ追加する標準手段としてwp_enqueue_script()を用意しています。ハンドル名、ファイルURL、依存スクリプト、バージョン、読み込み方法をWordPressへ登録できるため、同じスクリプトの二重読込や依存関係を管理しやすいのが利点です。

フロント側ではwp_enqueue_scriptsフックから呼び出します。次は、子テーマのassets/js/site.jsを読み込む最小例です。

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'site-custom',
        get_stylesheet_directory_uri() . '/assets/js/site.js',
        array(),
        '1.0.0',
        array(
            'strategy'  => 'defer',
            'in_footer' => true,
        )
    );
} );

get_stylesheet_directory_uri()は、子テーマを有効にしている場合は子テーマ側のURLを返します。strategyにはdeferまたはasyncを指定できますが、どちらを使うかはスクリプトの依存関係で決めます。DOM構築後に順序を保って実行したい処理ではdeferが扱いやすく、読み込み順を保証できないasyncは独立した処理向けです。

既存のjQueryへ依存するコードなら依存配列をarray( 'jquery' )にするなど、必要なハンドルを明示します。functions.phpの編集方法そのものは、functions.phpでの実装で扱っています。

バージョン番号はキャッシュ更新にも使われる

wp_enqueue_script()のバージョン値はURLのクエリ文字列に使われるため、JavaScriptを更新したのに古いファイルが残る問題を減らせます。手動で1.0.0から1.0.1へ変える方法でも十分ですが、開発中だけfilemtime()でファイル更新時刻を使う方法もあります。

$path = get_stylesheet_directory() . '/assets/js/site.js';

wp_enqueue_script(
    'site-custom',
    get_stylesheet_directory_uri() . '/assets/js/site.js',
    array(),
    file_exists( $path ) ? (string) filemtime( $path ) : null,
    array( 'in_footer' => true )
);

本番運用では、デプロイ方法に合わせて固定バージョンを管理する方が履歴を追いやすい場合もあります。キャッシュ対策だけを目的に毎回ランダムな値を付けると、ブラウザーキャッシュを活かせなくなるため避けます。

特定ページだけにJavaScriptを読み込む

サイト全体で使わない処理は、必要な画面だけへ限定すると読み込むファイルを減らせます。固定ページならis_page()などの条件分岐をwp_enqueue_scripts内で使えます。

add_action( 'wp_enqueue_scripts', function () {
    if ( ! is_page( 'contact' ) ) {
        return;
    }

    wp_enqueue_script(
        'contact-helper',
        get_stylesheet_directory_uri() . '/assets/js/contact.js',
        array(),
        '1.0.0',
        array( 'in_footer' => true )
    );
} );

上の例では、スラッグがcontactの固定ページだけで読み込みます。投稿タイプ、カテゴリ、テンプレートなどで条件を変える場合も、まず「どのページで本当に必要か」を決めてから条件を追加してください。条件分岐を複雑にしすぎると、ページ追加時に読み込み漏れが起きやすくなります。

子テーマでJavaScriptを管理する

親テーマへsite.jsや読み込みコードを直接追加すると、テーマ更新で上書きされる可能性があります。独自コードをテーマ側に持たせるなら、親テーマから分離できる子テーマでの管理を使います。

子テーマでは、たとえばassets/js/のように用途別のディレクトリを作り、ファイル名もmenu.js、contact.jsのように役割が分かる名前にします。複数の小さな処理を無制限に1ファイルへ集約するより、読み込み対象と責任範囲をそろえる方が後から修正しやすくなります。

• 変更前にファイルとデータベースのバックアップを取る
• 本番へ直接書かず、可能なら検証環境で動作を確認する
• 親テーマのJavaScriptをコピーして改造する前に、テーマのフックや公式拡張方法を確認する
• 外部ライブラリを追加する場合はライセンス、更新状況、配信元を確認する
• 不要になったスクリプトはenqueue処理ごと削除し、用途不明のコードを残さない

JavaScriptが反映されないときの確認順

コードを保存しても動かないときは、JavaScriptの内容だけを疑うのではなく、「ファイルが読み込まれているか」「読み込まれた後にエラーが出ていないか」を分けて確認します。

1. ブラウザーの開発者ツールでNetworkを開き、目的のJSファイルが200で取得されているか確認する
2. Consoleを開き、構文エラーやReferenceErrorなどが出ていないか確認する
3. ソースURLが子テーマの正しい場所を指しているか確認する
4. ページ限定条件が意図したページでtrueになっているか確認する
5. ブラウザー、キャッシュプラグイン、サーバー側のキャッシュを必要に応じて削除する
6. 依存するライブラリの読み込み順とハンドル名を確認する
7. 最適化プラグインのJS遅延・結合を一時的に切り分ける

Networkにファイル自体が出てこないなら、enqueue処理や条件分岐の問題を先に調べます。ファイルは読まれているのに動かないなら、ConsoleのエラーとDOMのセレクタを確認します。この順序なら、PHP側とJavaScript側を混同しにくくなります。

JavaScript追加時のセキュリティと保守の注意点

外部からコピーしたJavaScriptは、内容を理解せず本番へ貼り付けないでください。フォーム入力やURLパラメータを扱う処理では、ブラウザー側のチェックだけを安全対策にせず、サーバー側でも入力検証・権限確認を行う必要があります。

また、外部CDNのURLを固定して読み込む場合は、提供元の信頼性、バージョン固定、障害時の影響、プライバシーへの影響を確認します。WordPress本体が登録済みのライブラリを使える場合は、同じライブラリを別CDNから重ねて読み込まない方が競合を避けやすくなります。

よくある質問

まとめ

WordPressにJavaScriptを追加するなら、長期運用するコードはwp_enqueue_script()で読み込み、必要なページだけに限定し、子テーマや専用プラグイン側へ管理場所を分けるのが基本です。反映されないときは、Networkでファイルの取得、Consoleで実行エラー、条件分岐、キャッシュの順に切り分けると原因を特定しやすくなります。