WordPressでJavaScriptを読み込む際に推奨される方法がwp_enqueue_scriptです。テーマやプラグインで正しくスクリプトを読み込むことで、不要な競合を防ぎ、依存関係を管理しやすくなります。直接header.phpやfooter.phpにscriptタグを記述する方法も可能ですが、WordPressの仕組みを活かすためにはenqueue関数を使うのが基本です。
wp_enqueue_scriptの基本構文
wp_enqueue_scriptは以下のように記述します。主な引数はハンドル名、読み込むファイルのURL、依存スクリプト、バージョン番号、フッターでの読み込み有無です。
wp_enqueue_script( string $handle, string $src = '', array $deps = array(), string|bool|null $ver = false, bool|array $in_footer = false )
WordPress 6.3以降は、第5引数にboolの代わりに配列を渡すことで、フッター読み込みの指定に加えてdefer・asyncの読み込み戦略も同時に指定できます(詳しくは後述)。
基本的な使い方
functions.phpに以下のようなコードを記述します。テーマディレクトリ内のassets/js/common.jsを読み込み、jQueryを依存関係として指定、フッターで読み込む例です。
<?php
add_action('wp_enqueue_scripts', function () {
$rel = '/assets/js/common.js';
$file = get_template_directory() . $rel;
wp_enqueue_script(
'theme-common',
get_template_directory_uri() . $rel,
array('jquery'),
file_exists($file) ? filemtime($file) : null,
true
);
});
filemtime()はファイルの更新日時をバージョン番号として使うことでキャッシュを自動更新するテクニックですが、対象ファイルが存在しない場合にPHPの警告が出るため、必ずfile_exists()で確認してから呼び出してください。
依存関係の管理
依存関係を正しく指定することで、ライブラリやプラグインの競合を防げます。例えば、Slickスライダーを利用する場合は以下のように記述します。
<?php
add_action('wp_enqueue_scripts', function () {
// Slick本体
wp_enqueue_script(
'slick',
get_template_directory_uri() . '/assets/slick/slick.min.js',
array('jquery'),
'1.8.1',
true
);
// 初期化用スクリプト
$rel = '/assets/js/slick-init.js';
$file = get_template_directory() . $rel;
wp_enqueue_script(
'slick-init',
get_template_directory_uri() . $rel,
array('slick'),
file_exists($file) ? filemtime($file) : null,
true
);
});
管理画面での読み込み
wp_enqueue_scriptは管理画面でも利用可能です。管理画面ではフックをadmin_enqueue_scriptsに切り替えます。
<?php
add_action('admin_enqueue_scripts', function ($hook) {
if ($hook === 'post.php' || $hook === 'post-new.php') {
$rel = '/assets/js/admin.js';
$file = get_template_directory() . $rel;
wp_enqueue_script(
'admin-custom',
get_template_directory_uri() . $rel,
array('jquery'),
file_exists($file) ? filemtime($file) : null,
true
);
}
});
CDNスクリプトの読み込み
CDNからスクリプトを読み込む場合も同様にenqueueで管理できます。
<?php
add_action('wp_enqueue_scripts', function () {
wp_enqueue_script(
'axios',
'https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js',
array(),
null,
true
);
});
CDNのURLにバージョン番号を含めない場合、常に最新版が読み込まれるため、本番環境では意図しない更新で動作が変わらないよう、axios@1.6.0のようにバージョンを固定することをおすすめします。
defer・asyncを指定する(WordPress 6.3以降)
WordPress 6.3以降では、第5引数に配列を渡すことで読み込み戦略を指定できます。
<?php
add_action('wp_enqueue_scripts', function () {
$rel = '/assets/js/common.js';
$file = get_template_directory() . $rel;
wp_enqueue_script(
'theme-common',
get_template_directory_uri() . $rel,
array('jquery'),
file_exists($file) ? filemtime($file) : null,
array(
'in_footer' => true,
'strategy' => 'defer', // 'defer' または 'async'
)
);
});
strategyには'defer'または'async'を指定できます。依存関係があるライブラリはdefer、独立した計測タグなどはasyncが安全です。
よくある質問(FAQ)
まとめ
wp_enqueue_scriptを使えばJavaScriptの読み込み順や依存関係をWordPressに管理させることができ、コードの衝突や重複読み込みを防げます。テーマやプラグインを開発する際は必ずこの関数を利用し、必要に応じて依存配列やバージョン番号を適切に指定することが重要です。filemtime()でバージョン管理する場合は、ファイルの存在確認も忘れないようにしましょう。

