wp_enqueue_script()は依存関係、version、footer位置を指定してscriptを読み込む

WordPressのフロント画面でJavaScriptを読み込むときは、wp_enqueue_scripts hookからwp_enqueue_script()を呼びます。scriptのURLだけでなく、識別用のhandle、先に必要なscript、version、headかfooterかをWordPressへ渡します。

script要素をテーマへ直接書くと、プラグインと同じファイルを二重に読み込む、依存するライブラリより先に実行する、不要なページにも出力するといった問題を分けにくくなります。wp_enqueue_script()を使えば、WordPressがhandleを基準に登録と出力順を管理します。

フロント画面ではwp_enqueue_scripts hookから呼ぶ

次は説明用の仮例です。テーマのnavigation.jsがjQueryに依存し、footerで読み込む場合を示します。

function satolab_enqueue_scripts() {
	wp_enqueue_script(
		'satolab-navigation',
		get_stylesheet_directory_uri() . '/js/navigation.js',
		array( 'jquery' ),
		'1.0.0',
		true
	);
}
add_action( 'wp_enqueue_scripts', 'satolab_enqueue_scripts' );

wp_enqueue_scripts hookは、フロント画面のscriptをキューへ追加する入口です。管理画面やログイン画面では入口が異なるため、すべての画面へ同じhookを流用しません。

コールバック内では、必要なページかどうかも判断できます。条件を付ける場合は、scriptを使うページだけを対象にします。登録したことではなく、必要な画面で必要な処理が動くことを目的にします。

五つの引数はscriptの識別、URL、順序、版、位置を表す

WordPress 3.8のwp_enqueue_script()は、次の五つの引数を取ります。

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

$depsには、ファイル名ではなく登録済みのhandleを書きます。WordPressは依存先を先に処理し、その後で対象scriptを出力します。依存先のhandleが登録されていなければ、依存するscriptも出力できません。

$verをfalseにすると、WordPressはインストール中のWordPressのversionを付けます。nullならversionを付けません。独自scriptに版がある場合は、その版を文字列で指定します。ファイルを変更したときに版も変えれば、ブラウザーが古いURLを使い続ける問題を確認しやすくなります。

handleをそろえると重複と順序を管理できる

WordPressは、同じhandleをキューへ重ねて追加しません。一つのscriptファイルには、テーマとプラグインを通して同じhandleを使います。同じファイルを別々のhandleで登録すれば、WordPressは同じscriptだと判断できません。

すでに登録済みのhandleへ、別のURLや依存関係を付けてwp_enqueue_script()を呼んでも、新しい引数は既存登録を上書きしません。別の内容へ変更する必要がある場合は、どこで登録されたhandleかを確認してから、登録解除と再登録を検討します。知らない登録をその場で上書きしようとすると、読み込み元と責任が見えなくなります。

依存関係もhandleで表します。たとえばnavigation.jsがjQueryの関数を使うなら、array( 'jquery' )を指定します。PHPの記述順だけに頼らず、必要なscriptを依存関係として残します。

登録と読込みを分けると条件ごとに使える

一つの場所で登録と読込みを済ませるなら、$srcを付けたwp_enqueue_script()だけで足ります。この関数は、未登録ならscriptを登録し、そのhandleをキューへ追加します。

複数の条件から同じscriptを使う場合は、登録と読込みを分けられます。

function satolab_register_scripts() {
	wp_register_script(
		'satolab-navigation',
		get_stylesheet_directory_uri() . '/js/navigation.js',
		array( 'jquery' ),
		'1.0.0',
		true
	);

	if ( is_page() ) {
		wp_enqueue_script( 'satolab-navigation' );
	}
}
add_action( 'wp_enqueue_scripts', 'satolab_register_scripts' );

wp_register_script()は定義だけを登録し、wp_enqueue_script()は登録済みhandleを読込み対象へ加えます。登録しただけでは出力されません。すべてのページで使うなら、分ける必要もありません。

footerへ出すにはtrueとwp_footer()の両方が必要になる

第五引数をtrueにすると、WordPressは対象scriptをheadで出力せず、footerの処理まで保留します。WordPress 3.8のWP_Scriptsは、footer groupのhandleをhead処理から分けています。

ただし、テーマにwp_footer()がなければ、footerへ回したscriptを出力できません。trueを指定したあとでscriptが見つからない場合は、キューだけでなく、footer.phpのwp_footer()と生成されたHTMLを確認します。

footer指定は、すべてのscriptを機械的に下へ移すための値ではありません。headで必要なscript、依存先との位置関係、ページ表示後に動けばよいscriptを分けます。最初の一手は、テーマ内のscript要素とwp_enqueue_script()をhandleごとに一覧にし、同じファイルの重複、依存関係、version、出力位置を一つずつ確かめることです。