WordPress で CSS、JavaScript ファイルを読み込む正しい方法

誤った方法で行っている方を多く見かけますので説明します。

読み込むエリアにあわせて適切なフックを使用する

上記フックは xxx_scripts という名前ですが、スクリプトだけでなくスタイルシートの読み込みにも使用されます。誤解を招き易い点なので注意してください。また、wp_print_scripts フック、wp_print_styles フックを使用している例を見かけますがこれらを使用することは誤りです。適切なフックを用いずにスタイルシートやスクリプトを読み込むことは不整合の原因となりますので、明確な意図がない限り行うべきではありません。

関数を使ってファイルを登録・読み込みキューに追加する

スタイルシートの場合

wp_enqueue_style() を使います。パラメーターは以下となります:

wp_enqueue_style( $handle, $src, $deps, $ver, $media );

  • $handle: スタイルシートの識別名、ハンドル。
  • $src: スタイルシートの URL(オプション)
  • $deps: 依存スタイルシート識別名の配列(オプション)
  • $ver: バージョン文字列。クエリーストリングに付加される。(オプション)
  • $media: スタイルシートのメディア指定(オプション)

スクリプトの場合

wp_enqueue_script() を使います。パラメーターは以下となります:

wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );

  • $handle: スクリプトの識別名、ハンドル。
  • $src: スクリプトの URL(オプション)
  • $deps: 依存スクリプト識別名の配列(オプション)
  • $ver: バージョン文字列。クエリーストリングに付加される。(オプション)
  • $in_footer: true とすることでスクリプトは </body> の前のエリアで読み込まれる。デフォルトは false で </head> の前のエリアで読み込まれる。(オプション)

具体例

以下、Twenty Fourteen テーマの functions.php から抜粋したコードです。説明はコメントを読んでください。

// スタイルシートとスクリプトの読み込みコードを関数にまとめる
function twentyfourteen_scripts() {
	/*
	 * wp_enqueue_style() を使って style.css を登録・読み込みキューに追加。
	 * genericons という登録済みスタイルシートを依存指定し
	 * 自動的に style.css より先に読み込ませる。
	 */
	wp_enqueue_style( 'twentyfourteen-style', get_stylesheet_uri(), array( 'genericons' ) );

	/*
	 * wp_enqueue_script() を使って functions.js を登録・読み込みキューに追加。
	 * jquery を依存指定し自動的に先に読み込ませる。
	 * 20140319 というバージョン文字列を URL のクエリーストリングに付加し
	 * バージョンの異なるファイルキャッシュがある場合は更新されるようにする。
	 * スクリプトをフッターエリアで読み込ませる(多くの場合この設定が望ましい)。
	 */
	wp_enqueue_script( 'twentyfourteen-script', get_template_directory_uri() . '/js/functions.js', array( 'jquery' ), '20140319', true );
}
// twentyfourteen_scripts() をサイト公開側で呼び出す。
add_action( 'wp_enqueue_scripts', 'twentyfourteen_scripts' );

上記は Twenty Fourteen の例ですが、子テーマのスタイルシートのあるディレクトリの URL を取得する場合は、get_template_directory_uri() ではなく、get_stylesheet_directory_uri() を使用する点に注意してください。

WordPress で jQuery を使う時の注意点の記事にも wp_enqueue_script() の使用例がありますので参考にしてください。

wp_register_style() と wp_register_script() について

wp_register_style() はスタイルシート、wp_register_script() はスクリプトの登録を行う単機能の関数で、これらだけではファイルは読み込みキューには追加されません。対して、wp_enqueue_style() はスタイルシート、wp_enqueue_script() はスクリプトの登録と読み込みキューへの追加を行うマルチ機能の関数で

  • wp_enqueue_style()、wp_enqueue_script() で登録に必要なパラメーター($handle、$src)を設定している場合は、wp_register_style()、wp_register_script() は不要。
  • wp_register_style()、wp_register_script() で事前に登録済みのファイルは、wp_enqueue_style()、wp_enqueue_script() においてハンドルのみで読み込みキューに追加可能。

という仕様になっています。

WordPress 本体には多くのスクリプトが含まれており、初期状態で登録済みの状態になっています。これらはハンドルだけで wp_enqueue_script() から扱うことができます。

読み込み順序のコントロール

以下が組合わさった結果が最終的なページ出力内での順序となります。

  • ファイルは、wp_enqueue_style()、wp_enqueue_script() の実行順にキューに追加される。
  • wp_register_style()、wp_register_script()、wp_enqueue_style()、wp_enqueue_script() の $deps パラメーターにあるファイルは先に読み込まれる。
  • wp_register_script()、wp_enqueue_script() で $in_footer が true の場合は </body> の前のエリアで、そうでない場合は </head> の前のエリアで読み込まれる。
  • フックで呼ばれる関数の実行順序は add_action() の $priority で決まる。

まとめ

クローズドなサイト開発などでは独自の方法で行っていても問題とならないケースはあるでしょう。しかしながら、プラグインやテーマを開発公開している場合は WordPress 流のコードの書き方に従うしかありません。WordPress は多くの開発者のコードが行き交う大通りの交差点です。交通ルールを守らなければ誰かから叱られることがあるかもしれません。

WordPress で jQuery を使う時の注意点

慣れていない方には解りにくいところがあるようですので、いまさらですが要点をまとめます。

特別な理由がない限り WordPress に含まれている jQuery を使う

WordPress には外部スクリプトを読み込むための独自の仕組みがあります。また、WordPress インストールには初期状態で jQuery が含まれており jquery というスクリプトハンドルですぐに呼び出せる状態となっています。コンフリクトや依存関係の問題を引き起こさないように考えられていますので、特別な理由がない限りこれらを利用します。

コード例

テーマの functions.php に以下のように記述するとサイトの公開側に jQuery が読み込まれるようになります。

function my_scripts() {
	wp_enqueue_script( 'jquery' );
}
add_action( 'wp_enqueue_scripts', 'my_scripts' );

例えば custom-script.js というファイルに jQuery を使ったコードを書きたい場合は、以下のような記述となります。

function my_scripts() {
	wp_enqueue_script( 'custom-script', get_template_directory_uri() . '/js/custom-script.js', array( 'jquery' ) );
}
add_action( 'wp_enqueue_scripts', 'my_scripts' );

2番目の例では、custom-script の依存ファイルとして jquery ハンドルをパラメーターで指定しています。このように書けば、わざわざ wp_enqueue_script() で呼び出すことなく、jQuery が custom-script.js の前に読み込まれるようになります。

WordPress 版 jQuery はそのままでは $ が使えない

WordPress 版 jQuery では、コンフリクトを避けるため、グローバルな $ ショートカットが使えなくなっています。なじみの $ を使った記述を行いたい場合は以下のようにします。

jQuery(function($) {

// ここに $ を使ったコードを書く

});

シンプルですがこれだけで、$(document).ready() 効果とローカル内だけの安全な $ の利用を可能にしています。