WordPressのCSS・JS読み込み｜基本編

WordPressでは、CSSやJSはfunctions.phpから読み込むのが推奨の方法です。この記事では、CSSとJSを1つずつ読み込む、基本の書き方を紹介します。

ハコマル

最初は基本の書き方だけ覚えれば大丈夫だよ！慣れてきたら少しずつ応用していこうね

CSS・JSの読み込みで押さえること

やりたいことが決まっている場合は、次の表から使う関数と、解説しているSTEPを探してください。

各STEPのコードは、前のSTEPのコードに書き足していきます。コピーして使いたい場合は、完成形のコードを先に確認できます。

ハコマル

STEPを順番に読んでいくと、最後に完成形のコードが組み上がるよ！

STEP1：CSSを読み込む

wp_enqueue_scriptsフックの中でCSSを読み込む

CSSはwp_enqueue_style、JSはwp_enqueue_scriptで読み込みます。どちらも、wp_enqueue_scriptsというフックの中で呼び出すのが決まりです。フックの外で呼ぶと、予期しない動きになることがあります。

function mytheme_enqueue_assets() {              /* ① */
  wp_enqueue_style(
    'mytheme-style',                             /* ② */
    get_parent_theme_file_uri('css/style.css'),  /* ③ */
    [],                                          /* ④ */
    '1.0.0'                                      /* ⑤ */
  );
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets'); /* ⑥ */

※1：ハンドル名…読み込むCSS・JSを識別するための名前。この記事では「mytheme-style」のように、接頭辞とファイル名を組み合わせて付けています。

同じハンドル名なら二重に読み込まれない

1つ目の引数のハンドル名が同じなら、何度呼び出しても読み込まれるのは1回だけです。ハンドル名を「テーマの接頭辞-ファイル名」に統一しておくと、二重読み込みを防げます。

ただし、同じハンドル名で別のパラメータを渡しても、2回目以降の値は無視されます。別のCSSには、必ず別のハンドル名を付けましょう。

テーマ内のファイルのパスとURLを取得する

テーマ内のファイルを扱うときは、次の関数を使います。名前が_pathで終わる関数はサーバー上の場所を返します。_uriで終わる関数は、ブラウザが読み込むURLを返します。

URLは読み込み関数に渡します。パスは、STEP2で使うfile_existsやfilemtimeに渡します。子テーマで上書きさせたい場合は、get_theme_file_で始まる関数を使いましょう。

ハコマル

「path」はサーバーの中の住所、「uri」はブラウザから見た住所、と覚えるといいよ！

これらの関数は、WordPress 4.7で追加されたとされています。古いバージョンのWordPressで使う場合は、公式リファレンスで確認してください。

STEP2：キャッシュ対策をする

バージョンを付けてキャッシュ対策をする

CSSを更新したのに、ブラウザに古いキャッシュが残って反映されないことがあります。これを防ぐのが、4つ目の引数に指定するバージョンです。バージョンは、URLの末尾に?ver=値として付きます。

出力されるHTML（例）

<link
  rel="stylesheet"
  href="https://example.com/css/style.css?ver=1.0.0"
>

値が変わるとURLも変わるため、ブラウザは新しいファイルを読み込みます。バージョンには、次の値を指定できます。

更新日時を自動でバージョンにする

filemtimeは、ファイルの更新日時を取得する関数です。バージョンに使えば、CSSを更新するたびに自動でURLが変わります。STEP1の関数の中身を、次のように書き換えます。

function mytheme_enqueue_assets() {
  $path = get_parent_theme_file_path('css/style.css');  /* ① */

  if (file_exists($path)) {                             /* ② */
    wp_enqueue_style(
      'mytheme-style',
      get_parent_theme_file_uri('css/style.css'),
      [],
      filemtime($path)                                  /* ③ */
    );
  }
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');

ハコマル

テーマのCSSやJSは、filemtimeでバージョンを付けると覚えておいてね！キャッシュで悩まなくなるよ

STEP3：JSを読み込む

JSをフッターで読み込む

JSはwp_enqueue_scriptで読み込みます。5つ目の引数に配列を渡すと、出力する場所や実行するタイミングを指定できます。この配列の書き方は、WordPress 6.3以降で使えます。

次のコードを、mytheme_enqueue_assets関数の中の、CSSを読み込む処理の下に書き足します。

$main_js = get_parent_theme_file_path('js/main.js');

if (file_exists($main_js)) {
  wp_enqueue_script(
    'mytheme-main',                                   /* ① */
    get_parent_theme_file_uri('js/main.js'),
    [],
    filemtime($main_js),
    ['in_footer' => true]                             /* ② */
  );
}

ハコマル

CSSと形はほとんど同じだよ！違うのは、関数の名前と5つ目の引数だけだね

実行するタイミングの指定は、よくある質問で紹介しています。詳しい仕様はWordPress公式リファレンス（wp_enqueue_script）で確認できます。

完成形のコード

STEP1〜3のコードを、1つにまとめました。functions.phpに貼り付けて使えます。

function mytheme_enqueue_assets() {                     /* ① */
  $path = get_parent_theme_file_path('css/style.css');
  if (file_exists($path)) {                             /* ② */
    wp_enqueue_style(
      'mytheme-style',
      get_parent_theme_file_uri('css/style.css'),
      [],
      filemtime($path)
    );
  }

  $main_js = get_parent_theme_file_path('js/main.js');
  if (file_exists($main_js)) {                          /* ③ */
    wp_enqueue_script(
      'mytheme-main',
      get_parent_theme_file_uri('js/main.js'),
      [],
      filemtime($main_js),
      ['in_footer' => true]
    );
  }
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_assets');

使うときは、接頭辞（mytheme）と、CSS・JSのファイルの場所を、自分のサイトに合わせて書き換えてください。

さいごに

まとめ

functions.phpでのCSS・JSの読み込みは、フックに登録した関数の中に書くのが基本です。

CSSやJSが増えてきたら、ページごとの出し分けにも挑戦してみてください。

よくある質問

参考にした公式情報

どのページも英語ですが、ブラウザの翻訳機能を使えば日本語で読めます。