WordPressにjavascriptを登録するwp_register_script()の解説

2023/08/07 Monday2024/01/02 Tuesday

WordPressにjavascriptを登録したい時に使用する関数です。

似た関数にwp_enqueue_script()があり、何が違うのか？どこで使うのか？を分かりやすくまとめました。

単純にjavascriptだけを出力したいならwp_enqueue_script()を使えば良いのですが、理解せずに使うのと、理解して適材適所に使うのとでは今後の保守性やカスタマイズのやり易さに違いが出てきますので、勉強熱心な方はこちらも覚えておくと良いでしょう。

まとめ記事紹介

javascriptだけでなくcssも追加したい。追加だけでなく削除もしたい。保守性、メンテナンスを考えて適切な処理を行いたい。とお考えの方は、こちらのまとめ記事も併せてご覧ください。

これを読むだけでOK！

【保存版】WordPressでcssやjavascriptを追加・削除する方法まとめワードプレスの軽量化のため特定のページのみcssやjavascriptを表示したい。それ以外のページでは削除したい時に役立つ、追加・削除の関数をまとめた記事です。似た関数が多く、使い所を間違わないよう丁寧に解説していますので是非参考にして下さい。

wp_register_script()

wp_register_script() 初期値

wp_register_script(
    string           $handle,
    string|false     $src,
    string[]         $deps = array(),
    string|bool|null $ver = false,
    bool             $in_footer = false
): bool

wp_register_script() の簡潔コード

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

$handle string 必須

スクリプトの名前。判別するのに使うため一意である必要があります。

$src string|false 必須

スクリプトへの絶対URL。

$srcがfalseに設定されている場合、依存する他のスクリプトのエイリアスになります。

$deps string[]

依存するスクリプトのハンドル名を指定（既に登録されている$handleを指定）

指定したスクリプトの後に、このスクリプトが読み込まれる。

jQueryの後に読み込まなければならいスクリプトがある時に使ったりします。

デフォルト：array()

$ver string|bool|null

スクリプトのバージョン番号を指定する文字列 (存在する場合)

キャッシュ無効化の目的でクエリ文字列として URL に追加されます。

$verがfalseに設定されている場合、現在インストールされているWordPressのバージョンと同じバージョン番号が自動的に追加されます。

nullに設定すると何も追加されません。

デフォルト：false

$in_footer　 bool

スクリプトを<head>内ではなく</body>直前に挿入するかどうかの判定。

サイトの軽量化を考えて読み込みは最後にしたい方はtrueを指定すると良いでしょう。

デフォルト：false

返り値 bool

スクリプトが登録されているか判定。
成功した場合は true失敗した場合は false

wp_enqueue_script()との違い

簡単に説明すると

wp_register_script(): 事前予約。使いたいスクリプトをコアに登録する関数で、これだけではキューに登録されません。
wp_enqueue_script(): wp_register_script()で登録したスクリプトをキューに追加する関数です。登録されていないハンドル名を指定した場合は新規にキューへと追加します。

これだけではwp_register_script()って使う必要あるの？全てwp_enqueue_script()で直接使いたい所でキューにjavascriptを新規追加していけば良いじゃん。と思われるかもしれません。

functions.phpでちょっとしたjavascriptを追加したりするだけならばwp_enqueue_script()で事足りますが、依存関係が深くなりがちなプラグインやテーマを開発したり、保守性を高めたり、コードの可読性を上げたいと考えた場合はwp_register_script()を使った方が良いのです。

キューって何？

WordPressではフロントエンドに出力する前に、バックエンドで一度出力するスクリプト群を溜める保管場所をqueue(キュー)と呼び、キューに登録する作業をenqueue(エンキュー)と呼びます。エンキューの工程が終了後、適切な順序に並び替えてフロントエンドにスクリプトが出力されます。

依存関係の簡略化

あるスクリプトを読み込む前に必ず読み込んでおかなければならないスクリプトをwp_register_script()の$depsに登録しておけばwp_enqueue_script()でキューに追加する際、自動的に必要なスクリプトも全て追加されます。

これにより、スクリプトに必要な依存関係が適切に処理されているか等の確認作業がなくなり、保守性の高いコードを書くことが出来ます。

jQuery後に子テーマのスクリプトをコアに登録する例

add_action('wp_enqueue_scripts', function () {
    // 必須のスクリプトを登録
    wp_register_script(
        'jquery-min',
        'https://code.jquery.com/jquery-3.7.0.min.js',
        [],
        null
    );
    
    // 登録したいスクリプト 依存関係にjquery-minを指定
    wp_register_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js',
        ['jquery-min'],
        null
    );
});

get_stylesheet_directory_uri()は現在有効化しているテーマのディレクトリURLを取得する関数です。子テーマのパスを取得したい場合はこの関数を必ず使います。

上記のコードだけではコアに登録されるだけで、キューに登録はされていないためフロントエンド側のどこにも出力されません。

登録したスクリプトを出力したい場合は、以下のコードを記載すると依存関係を保持したまま出力されます。

使いたい場所でハンドル名を呼び出すだけでOK

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('custom-script');
});

上記のコードを記載するとHTMLのソースには以下のタグが挿入されます。

jQueryが挿入された箇所の後にcustom-script.jsが読み込まれています。

<script type='text/javascript' src='https://code.jquery.com/jquery-3.7.0.min.js' id='jquery-min-js'></script>
<script type='text/javascript' src='https://it-manabi.com/wp-content/themes/swell_child/custom-script.js' id='custom-script-js'></script>

必須スクリプトにはwp_enqueue_scriptを使わない理由

wp_enqueue_script()でも依存関係を指定出来る引数が用意されています。

しかし依存関係にて指定される必須スクリプトはwp_register_script()をなるべく使いましょう。という説明を誰もがしています。

なぜwp_enqueue_script()で必須スクリプトの登録は推奨されないのか？その理由はスクリプト

の依存関係を適切に処理するためです。

必須スクリプトに関してはwp_register_script()を使って事前に全てコア登録をしておけば、依存関係が正しく認識され、正しい順序でスクリプトが読み込まれwp_enqueue_script()を使用した際に、良きせぬエラーに遭遇する確率も減るためwp_register_script()が推奨されているのです。

スクリプトの一元管理と処理の分離

wp_register_script()を使う最大のメリットはこれでしょう。

スクリプトの記述を全て一箇所にまとめ、使いたい所でwp_enqueue_script()にて呼び出す。

もしスクリプトのファイル名やURLが変わったとしても、wp_register_script()の$srcを変更するだけで済む保守性の高さが魅力的です。

悪い例

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js'
    );
});

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js'
    );
});

page.phpとsingle.php内にcustom-script.jsを追加している例です。

上記の書き方だとcustom-script.jsをnew-script.jsに変更したいと思った時、page.phpとsingle.php、どちらの記述も書き直さなければなりません。

例では二つのファイルだけにしか記述していないので、手直しが簡単に思えるかもしれませんが、これが何十個ものファイルに記載されていたとすれば修正作業が大変なのは一目瞭然ですよね。

良い例

add_action('wp_enqueue_scripts', function () {
    wp_register_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js'
    );
});

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('custom-script');
});

add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script('custom-script');
});

script.phpというスクリプトを一元管理(事前登録)するファイルを作成し、 page.phpとsingle.php内では登録スクリプトを呼び出しているだけの例です。

上記の書き方だとスクリプトのパスcustom-script.jsをnew-script.jsに変更したいと思った時、script.phpのファイルパス記述を修正するだけです。

複数呼び出す可能性があるスクリプトは、この様な使い方をすると保守性の高いコードが書けるようになります。

呼び出すアクションフック名一覧

javascriptを挿入したい場所によって、指定するアクションフック名が変わります。

適切な場所を指定してカスタマイズを行いましょう。

アクションフック名

フロントエンド: wp_enqueue_scripts
管理画面: admin_enqueue_scripts
ログイン画面: login_enqueue_scripts

フロントエンドにjQueryを登録する例

add_action('wp_enqueue_scripts', function () {
    wp_register_script(
        'jquery-min',
        'https://code.jquery.com/jquery-3.7.0.min.js',
        [],
        '3.7.0'
    );
});

適切なバージョン管理とフッターで読み込む例

ファイルの最終更新時刻を利用

add_action('wp_enqueue_scripts', function () {
    wp_register_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js',
        [],
        filemtime(get_stylesheet_directory() . '/custom-script.js'),
        true
    );
});

filemtimeを利用してバージョン管理をしています。

var指定ではget_stylesheet_directory_uri()ではなくget_stylesheet_directory()を使用している点に気を付けてください。

custom-script.jsファイルが更新されると適切なタイムスタンプに更新されます。

タイムスタンプをdate関数で整形した場合のコード例

add_action('wp_enqueue_scripts', function () {
    wp_register_script(
        'custom-script',
        get_stylesheet_directory_uri() . '/custom-script.js',
        [],
        date('YmdHis', filemtime(get_stylesheet_directory() . '/custom-script.js')),
        true
    );
});

こちらの方がカスタマイズする際にソースを確認した時に分かりやすいのでオススメです。

出力するwp_enqueue_script()を忘れずに

wp_register_script()はあくまでスクリプトをコア登録(事前予約)するだけの関数です。

ソースコードに吐き出したい時はwp_enqueue_script()を必ず使う必要があります。

出力し忘れが無いように、セットで使う必要があると覚えておきましょう。

スクリプトを出力する関数

WordPressでjavascriptを追加するwp_enqueue_script()の解説コピペOK！様々な状況で使えるコード例を複数掲載しています。wp_enqueue_script()はWordPressに独自のjavascriptを追加したい時に使用する関数です。引数の紹介もしているので自分なりにカスタマイズしてお使い下さい。

まとめ記事

WordPressにCSSやJSを追加・削除する方法を全て網羅し、分かりやすく整理したまとめ記事も作成しておりますので、より理解を深めるためにお読み下さい。

これを読むだけでOK！

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！

WordPressにjavascriptを登録するwp_register_script()の解説

wp_register_script()

wp_enqueue_script()との違い

依存関係の簡略化

スクリプトの一元管理と処理の分離

呼び出すアクションフック名一覧

適切なバージョン管理とフッターで読み込む例

出力するwp_enqueue_script()を忘れずに

まとめ記事

コメント

コメントするコメントをキャンセル

WordPressにjavascriptを登録するwp_register_script()の解説

wp_register_script()

wp_enqueue_script()との違い

依存関係の簡略化

スクリプトの一元管理と処理の分離

呼び出すアクションフック名一覧

適切なバージョン管理とフッターで読み込む例

出力するwp_enqueue_script()を忘れずに

まとめ記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル