WordPressテーマにカスタムJavaScriptを追加する方法

WordPressテーマにカスタムJavaScriptを追加したい場合があります。スクロールエフェクト、サードパーティのトラッキングスニペット、またはインタラクティブな機能などです。コードをテンプレートファイルに貼り付けても何も動作しない、あるいはさらに悪いことに、PHPとJavaScriptを混在させてすべてを壊してしまうことがあります。

これは頻繁に起こります。解決策は簡単です。<script>タグをハードコーディングする代わりに、WordPressの組み込みスクリプト管理システムを使用してください。

WordPressでスクリプトをエンキューすべき理由

WordPressはテーマとプラグインの複雑なエコシステム上で動作します。JavaScriptをテンプレートに直接挿入すると、以下のような問題が発生します。

• 重複読み込み: 複数のプラグインが同じライブラリを読み込む可能性があります。
• 依存関係の失敗: 依存関係が読み込まれる前にスクリプトが実行されます。
• キャッシュの問題: ブラウザがインラインスクリプトを適切にキャッシュできません。
• 競合: スクリプトが調整なしに互いに干渉します。

wp_enqueue_script関数は、WordPressがスクリプトの読み込み順序、依存関係、出力場所を管理できるようにすることで、これらの問題を解決します。

WordPressにJavaScriptを追加する正しい方法

ステップ1: JavaScriptファイルを作成する

JavaScriptをテーマのディレクトリに配置します。一般的な構造は次のとおりです。

your-theme/
├── js/
│   └── custom.js
├── functions.php
└── style.css

PHPを混在させずにクリーンなJavaScriptを記述します。

document.addEventListener('DOMContentLoaded', function() {
    // Your code here
});

ステップ2: functions.phpでスクリプトをエンキューする

テーマのfunctions.phpに以下を追加します。

function mytheme_enqueue_scripts() {
    wp_enqueue_script(
        'mytheme-custom',                              // Handle
        get_template_directory_uri() . '/js/custom.js', // Source
        array(),                                        // Dependencies
        '1.0.0',                                        // Version
        array( 'in_footer' => true )                   // Load in footer
    );
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

子テーマの場合は、get_template_directory_uri()の代わりにget_stylesheet_directory_uri()を使用してください。

wp_enqueue_scriptのパラメータを理解する

この関数は5つのパラメータを受け取ります。

パラメータ	目的	例
$handle	一意の識別子	'mytheme-custom'
$src	ファイルURL	get_template_directory_uri() . '/js/file.js'
$deps	先に読み込む必要がある必須スクリプト	array( 'jquery' )
$ver	キャッシュバスティング用のバージョン文字列	'1.0.0'
$args	読み込み戦略と場所	array( 'in_footer' => true, 'strategy' => 'defer' )

条件付きスクリプト読み込み

特定のページでのみ必要な場合は、すべての場所でスクリプトを読み込まないでください。

function mytheme_enqueue_scripts() {
    if ( is_singular( 'post' ) ) {
        wp_enqueue_script( 'mytheme-post-scripts', /* ... */ );
    }

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'mytheme-contact-form', /* ... */ );
    }
}
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

パフォーマンスを考慮した読み込み戦略

WordPress 6.3では、deferおよびasync読み込みのネイティブサポートが導入されました。

wp_enqueue_script(
    'mytheme-analytics',
    get_template_directory_uri() . '/js/analytics.js',
    array(),
    '1.0.0',
    array(
        'in_footer' => true,
        'strategy'  => 'defer'
    )
);

Deferは、宣言された順序を維持しながら、DOM解析後にスクリプトを実行します。Asyncは、ダウンロードが完了次第すぐにスクリプトを実行し、順序は保証されません。ほとんどの場合はdeferを使用し、アナリティクスのような独立したスクリプトにはasyncを使用してください。

モダンなWordPress: スクリプトモジュールとブロック統合

WordPressはJavaScript処理を進化させ続けています。注目すべき2つの開発があります。

Script Modules API: WordPress 6.5では、ネイティブESモジュール用のwp_enqueue_script_module()が導入されました。これにより、適切なモジュールインポートを使用したモダンなJavaScriptパターンが可能になります。

ブロックベーステーマ: ブロックを構築している場合は、手動でエンキューするのではなく、block.jsonでviewScriptまたはviewScriptModuleフィールドを使用してスクリプトを宣言してください。ブロックがレンダリングされると、WordPressが自動的に読み込みを処理します。

これらのアプローチは従来のエンキューと並行して機能します。プロジェクトのニーズに基づいて選択してください。

まとめ

WordPressテーマにカスタムJavaScriptを追加するには、ハードコーディングされたスクリプトタグではなく、エンキューシステムを使用する必要があります。別々のJavaScriptファイルを作成し、wp_enqueue_scriptで登録し、依存関係を適切に宣言し、不要なリクエストを避けるために条件付き読み込みを使用してください。パフォーマンスを向上させるには、WordPress 6.3以降で利用可能なdeferおよびasync戦略を活用してください。

パターンはシンプルです。PHPとJavaScriptを分離し、WordPressに読み込みを管理させれば、スクリプトはテーマとプラグイン全体で確実に動作します。

よくある質問

wp_enqueue_scriptを使用してCDNから外部スクリプトを読み込むことはできますか?

はい。ソースとしてローカルファイルパスを渡す代わりに、外部スクリプトの完全なURLを指定してください。たとえば、2番目のパラメータとしてhttps://cdn.example.com/library.min.jsを使用します。WordPressはそのURLでスクリプトタグを出力します。通常どおり、依存関係、バージョン管理、読み込み戦略を設定できます。

同じスクリプトハンドルを2回エンキューするとどうなりますか?

WordPressは重複登録を無視します。ハンドルが一度エンキューされると、同じハンドルを使用した後続の呼び出しはスキップされます。これにより、同じスクリプトが複数回読み込まれることを防ぎます。これは、テンプレートに手動でスクリプトタグを追加する方法に対するエンキューシステムの主な利点の1つです。

エンキューされたJavaScriptファイルにPHPデータを渡すにはどうすればよいですか?

wp_localize_script関数または新しいwp_add_inline_script関数を使用してください。wp_localize_scriptは、PHPデータを含むJavaScriptオブジェクトを作成し、特定のスクリプトハンドルに添付します。これにより、2つの言語を混在させることなく、AJAX URL、nonceトークン、テーマ設定などの値をPHPからJavaScriptに渡すことができます。

WordPressでjQueryを使用し続けるべきですか、それともバニラJavaScriptに切り替えるべきですか?

WordPressは、ブロックベーステーマではデフォルトでjQueryをバンドルしなくなりました。新しいプロジェクトでは、一般的にバニラJavaScriptまたはモダンなフレームワークが推奨されます。テーマまたはそのプラグインがまだjQueryに依存している場合は、依存関係としてjqueryをリストすることでエンキューできます。それ以外の場合、依存関係のないバニラJavaScriptを記述することで、テーマを軽量かつ高速に保つことができます。