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つのパラメータを受け取ります。

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

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

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に読み込みを管理させれば、スクリプトはテーマとプラグイン全体で確実に動作します。

よくある質問

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.