CSSやJSファイルなどをfunctions.phpで読み込んで一元管理する

通常WebサイトでCSSやJSなどのファイルを読み込みたいときはheadタグのところに直接記述しますが、WordPressでは functions.php から読み込ませることが推奨されています。

そこでこの記事では、functions.php からファイルの読み込みを行う場合の書き方をメモしていきます。

この方法はファイルの重複読み込みやバッティングを回避し、読み込みファイルを一つのファイルで一元管理できるメリットがあります。

wp_enqueue_script や wp_enqueue_styleを使って読み込む

functions.php から外部ファイルを読み込むときは、wp_enqueue_script() や wp_enqueue_style() といった関数を使用します。

書き方は以下のような形になります。

function my_assets() {
  wp_enqueue_style($handle, $src, $deps, $ver, $media);
  // wp_enqueue_style(識別名（ハンドル名）, 読み込むファイルのパス, 依存するスクリプト, スクリプトのバージョン, スタイルシートのメディア);
  wp_enqueue_script($handle, $src, $deps, $ver, $in_footer);
  // wp_enqueue_script(識別名（ハンドル名）, 読み込むファイルのパス, 依存するスクリプト, スクリプトのバージョン, 読み込む場所);
}
add_action('wp_enqueue_scripts', 'my_assets');

wp_enqueue_script() や wp_enqueue_style() で読み込むファイルとその設定を登録し、wp_enqueue_scripts フックを使ってその内容を追加出力させています。
どちらも同じフックを使って出力させるのでまとめて記述できますが、登録するファイルが多くて分けた方が管理しやすいならそれぞれ関数を作成しても大丈夫です。

// ここにはCSS
function my_assets_css() {
  wp_enqueue_style($handle, $src, $deps, $ver, $media);
}
add_action('wp_enqueue_scripts', 'my_assets_css');

// ここにはJS
function my_assets_js() {
  wp_enqueue_script($handle, $src, $deps, $ver, $in_footer);
}
add_action('wp_enqueue_scripts', 'my_assets_js');

wp_enqueue_script と wp_enqueue_style のパラメーター詳細

$handle はスクリプトのハンドル名です。任意の名称を付けるのですが「jquery」などすでに登録されている名前を入れてもキューに追加されません。

$src には読み込むファイルのパス（絶対パス）が入ります。

$deps には、ここで指定するファイルより前に読み込む必要のある（依存する）スクリプトのハンドル名を配列形式で指定します。必要なければ空の配列を渡します。
例えばjQueryでJavaScriptのコードを記述するなら、jQueryを先に読み込む必要があります。もし依存先がキューになければここで指定したファイルも読み込まれません。
どのスクリプトより後に読み込むか、という指定ができるので依存関係を考慮して設定することができます。

$ver にスクリプトのバージョンを指定できます。ここで指定したテキストはファイル名にクエリパラメータとして追加されます。任意の数字や日時などを指定してキャッシュ対策としても利用できます。
初期値は使用しているWordPressのバージョンで、?ver=6.2 といった形で出力されます。

$media にはスタイルシートのメディアを指定します。

$in_footer は wp_footer() の部分で表示させるかどうかを指定します。真偽値（true or false）での指定で、true なら </body> の直前、false なら </head> の前で読み込まれます。初期値はfalseでheadタグ内で読み込まれるようになっています。

WordPress本体にあるjQueryとは違うものを使用したい場合

WordPressの本体にはjQueryのコードファイルも含まれています。
このファイルのハンドル名は ‘jquery’ です。 wp_enqueue_scripts でJSファイルを追加する際に依存するスクリプトに ‘jquery’ を指定すればWordPress本体にある jQuery が読み込まれます。

function my_assets() {
  wp_enqueue_script('my-script', get_template_directory_uri() . '/script.js', array('jquery'), '', true );
}

しかしこの本体にあるjQueryではなく別のバージョンのjQueryを読み込みたい場合は、別のjQueryファイルを登録し、識別名を ‘jquery’ 以外にして依存するスクリプトに指定します。
例として、下記コードではjQuery公式サイトのCDNのURLを指定しています。

function my_assets() {
  // 使用したいjQuery
  wp_enqueue_script('my_jquery', '//code.jquery.com/jquery-3.5.1.min.js', '', '', false);
  // テーマのJSファイル
  wp_enqueue_script('my_script', get_template_directory_uri() . '/script.js', array('my_jquery'), '', true );
}

もし別のjQueryファイルの識別名に ‘jquery’ を使用したいならWordPress標準のjQueryを削除する必要があります。wp_deregister_script() を使ってデフォルトのjQueryを削除できます。

function my_assets() {
  // デフォルトのjQueryを削除
  wp_deregister_script('jquery');
  // 使用したいjQuery
  wp_enqueue_script('jquery', '//code.jquery.com/jquery-3.5.1.min.js', '', '', false);
  // テーマのJSファイル
  wp_enqueue_script('my-script', get_template_directory_uri() . '/script.js', array('jquery'), '', true );
}

ちなみにWordPressにあるjQueryを使用した際に、以下のような書き方をしている場合 'Uncaught TypeError: $ is not a function' といったエラーが表示されるので、書き方を変える必要があります。

【エラーが出る書き方】

$(function() {
  // 何かしらの処理
});

【正しい書き方】

jQuery(document).ready(function() {
  // 何かしらの処理
});

// もしくは以下のような書き方

(function($) {
  // 何かしらの処理
})(jQuery);

WordPress本体に含まれるjQueryを削除すると思わぬ弊害も…

私はWordPress本体に含まれるjQueryの書き方が慣れていないので、wp_deregister_script('jquery') を使ってデフォルトのjQueryを削除することが多いです。

ただWordPressではそのjQueryを使用することを基本としているため、どこかしらでエラーが出てしまうこともあります。私が遭遇したのが「メニューの【カスタマイズ > ウィジェット】で「このページでは表示していません」が表示される」です。

この時以外では本体のjQueryを除外して不具合が出たことはありませんが、管理画面などで予期せぬエラーが出てしまう可能性があることは覚えておきたいところです。

functions.php に書いたCSSやJSが読み込まれない

wp_enqueue_script() や wp_enqueue_style() を使ってコードを記載したものの、指定したファイルが読み込まれないこともあるかもしれません。コードの確認をしていきましょう。

まず header.php に wp_head() 、footer.php に wp_footer() の記述があるか確認します。これらのテンプレートタグが正しく記載されていない場合、読み込まれません。コードがなかったら記載しましょう。

上記に問題がなければ、functions.php に書いたコードをしっかり見直していきます。

関数名は正しいものでしょうか。CSS なら wp_enqueue_style() 、 JS なら wp_enqueue_script() です。

ファイルのURLが間違いないかもう一度チェックしましょう。

私はコピペして別のスクリプトを追加した際に、ハンドル名を変更するのを忘れて、コピー元のスクリプトが読み込まれない、ということが何度かありました。複数のスクリプトを登録しているならハンドル名が被っていないかもチェックしてみてください。

アクションフックで登録されていますか。こちらのコードも読み込みには必須です。

add_action('wp_enqueue_scripts', '作成した関数名');

原因は他にもさまざまあると思うので、コードを見直して突き止めていきましょう。

管理画面やログイン画面のスクリプト指定

上記で記したコードは管理画面やログイン画面では読み込まれません。これらの画面で適用したいスクリプトがある場合は add_action() の部分を以下のように変更します。

function my_admin_script() {
  wp_enqueue_style($handle, $src, $deps, $ver, $media);
  wp_enqueue_script($handle, $src, $deps, $ver, $in_footer);
}
// 管理画面で適用したい場合
add_action('admin_enqueue_scripts', 'my_admin_script');
// ログイン画面で適用したい場合
add_action('login_enqueue_scripts', 'my_admin_script');