WordPressでは、ヘッダーに単に追加するのではなく、エンキューというメソッドを使用する必要があります。これは、アセットを処理するための標準化された方法で、依存関係の管理という利点もあります。wp_enqueue_scriptsの使用方法を以下にご紹介します。

エンキューの仕組み

スクリプトまたはスタイルをエンキューするには、2つのステップがあります。最初にそれを登録（そこにあることをWordPressに伝える作業です）、次に実際にエンキューします。これにより、最終的にヘッダー、またはbodyの終了タグの直前に出力されます。

2つのステップがある理由は、モジュールに関係しています。WordPressにアセットについて知らせつつも、すべてのページで使用したくないこともあります。例えば、JavaScriptを用いたカスタムギャラリーショートコードを作成する場合が挙げられます。実際には、ショートコードが使用された時にだけJSを読み込む必要があります。すべてのページで必要になる訳ではないでしょう。

これを実現するには、最初にスクリプトを登録し、ショートコードが表示されたときにのみ、それをキューに入れるようにします（関連記事： WordPressショートコード徹底解説ガイド）。

wp_enqueue_scriptsを使ったエンキューの基本

スクリプトとスタイルをフロントエンドでエンキューするには、 wp_enqueue_scriptsフックを使用する必要があります。フックされた関数内で、wp_register_script()、wp_enqueue_script()、 wp_register_style()、wp_enqueue_style()関数が使用できます。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_register_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );

    wp_enqueue_style( 'custom-gallery' );
    wp_enqueue_script( 'custom-gallery' );
}

上の例では、同じ関数内でアセットを登録・エンキューしましたが、これは少し冗長です。実際、register関数の場合と同じ引数を使用することにより、enqueue関数を使用してすぐに登録とエンキューを行うことができます。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );
}

2つの関数を分離することも可能です。その場合は、別々のフックを使用できます。実際の例では、wp_enqueue_scriptsフックを使用してアセットを登録し、ショートコードの関数を使用してそれをエンキューできます。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery', plugins_url( '/css/gallery.css' , __FILE__ ) );
    wp_register_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ) );

}

add_shortcode( 'custom_gallery', 'custom_gallery' );

function custom_gallery( $atts ){

    wp_enqueue_style( 'custom-gallery' );
    wp_enqueue_script( 'custom-gallery' );

    // Gallery code here
}

依存関係の管理

WordPressのエンキューメカニズムには、 wp_register_style()関数と wp_register_script()関数両方の3番目の引数を使用する依存関係管理の仕組みが組み込まれています。これらを分離する必要がない場合は、エンキュー機能をすぐに使用することもできます。

この3番目のパラメータは、現在のアセットがエンキューされる前に読み込む必要がある登録済みのスクリプト/スタイルの配列となります。上記の例はともするとjQueryに依存するので、ここでそれを指定しましょう。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ) );
}

jQueryはすでにWordPressの一部であるため、これを自分で登録またはエンキューする必要はありません。詳細については、CodexのWordPressで利用可能なスクリプトとスタイル一覧をご覧ください。

独自の依存関係がある場合は、それを登録する必要があります。これを怠ると、スクリプトが読み込まれなくなります。次に例を示します。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ) );
    wp_enqueue_script( 'custom-gallery-lightbox', plugins_url( '/js/gallery-lightbox.js' , __FILE__ ), array( 'custom-gallery' ) );
}

最初のスクリプトがギャラリーであると仮定します。2番目は、ライトボックスで画像を開くための、スクリプトの拡張です。2番目のスクリプトはjQueryに依存しますが、最初のスクリプトで既にjQueryを読み込んでいるため、これを指定する必要はありません。とは言え、依存関係を含めることを忘れた時であっても何も崩れないように、すべての依存関係を指定しておくのが得策です。

これでWordPressは、必要なスクリプトを認識し、ページに追加する順序を計算できるようになりました。

スクリプトをフッターで読み込むことで問題を回避できる場合は、普通そうするべきです。これにより、見かけのページの読み込み時間が長くなり（特にAJAX呼び出しが含まれている場合は）スクリプトの読み込み中にウェブサイトが待機状態になるのを防ぐことができます。

エンキューメカニズムでは、5番目のパラメーター（4番目は任意のバージョン番号）を使用してフッターにスクリプトを追加できます。上の例では、スクリプトを少し変更すると、スクリプトがフッターで読み込まれます。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_enqueue_script( 'custom-gallery', plugins_url( '/js/gallery.js' , __FILE__ ), array( 'jquery' ), '1.0', true );
    wp_enqueue_script( 'custom-gallery-lightbox', plugins_url( '/js/gallery-lightbox.js' , __FILE__ ), array( 'custom-gallery', 'jquery' ), '1.0', true );
}

5番目のパラメータとしてtrueを指定すると、スクリプトがフッターに配置されます。falseを使用するか、パラメータを省略すると、ヘッダーで読み込まれます。前述のように、可能な限りフッターでスクリプトを読み込んでください。

スタイルのメディアを指定する

スタイルのregister/enqueue関数の5番目のパラメータを使用して、スクリプトが定義されているメディアタイプ（print、screen、handfeldなど）を制御できます。このパラメータを使用することで、スタイルの読み込みを特定のメディアタイプに制限できます。これは、便利に活用できるちょっとした最適化のテクニックです。

add_action( 'wp_enqueue_scripts', 'my_plugin_assets' );
function my_plugin_assets() {
    wp_register_style( 'custom-gallery-print', plugins_url( '/css/gallery.css' , __FILE__ ), array(), '1.0', 'print' );

}

利用できるメディアタイプの一覧については、CSSの仕様 をご覧ください。

まとめ

アセットのエンキューは、アセットを処理するための強力なメソッドです。これによりあなたも他のプラグイン/テーマ作成者もシステム全体をより詳細に制御し、依存関係の管理を任せることもできます。

それに加え、この手法はそもそもアセットを追加するためのものです。この方法を使用しないと、多くのテーママーケットプレイスやWordPressリポジトリがあなたの作品を承認してくれません。

Daniel Pataki

KinstaのCTO。Smashing Magazine、WPMU Dev、Tuts+などのWordPressおよび開発関連プラットフォームで記事を執筆。WordPressとPHPに加えて、Node、React、GraphQL、その他のJavaScript分野の技術にも注力。宇宙一のホスティングソリューションの開発を目指し仕事をしている以外には、ボードゲームを集めたり、オフィスでテーブルサッカーをしたり、旅行に行ったり、ギタリストとしてアマチュアバンドで演奏したりしている。