WordPressのenqueue、register、dequeue、deregisterのポイント

WordPressでscriptタグを操作するために、 wp_enqueue_script() 、 wp_register_script() 、 wp_dequeue_script() 、 wp_deregister_script() 、などの関数があります。これらを使う上でのポイントをご説明します。

関数名がちょっと長いので、記事内では wp_enqueue_script()はeuqueueというように、短くして呼ぶ可能性があります。

ちなみに、WordPress6.8.3にて検証しておりますが、多少バージョンが違っても変わらないはずなので、参考にして頂ければと思います。

そんなにシンプルではなく割と複雑な仕様

以下のサイトだと、「登録」、「読み込む」、「解除」といった言葉を使ってこれらの関数を説明していました。

wp_register_scriptとwp_enqueue_scriptの使い方とその違いとは

wp_deregister_scriptとwp_dequeue_scriptの使い方とその違いとは

他の部分はとても参考になったのですが、「登録」、「読み込む」、「解除」といった言葉の定義が曖昧ですし、シンプルに考え過ぎてしまうと、直感と違う挙動をしてしまうと感じました。

ここから直感と違う実際の動作を説明していきます。

一度もregisterされてない$handleはenqueueだけでもOK

registerの引数は以下です。

これはほぼほぼenqueueの引数と同じです。

様々なスクリプトは、$handleで管理されています。

ある$handleで一度もregisterされていない場合、いきなりenqueueするだけでもscriptタグを出力してくれます。つまり、registerの動作も含んでいると言えます。

dequeueだけされた状態でregisterし直しただけだと表示されない

一度registerされた$handleで一度dequeueされた状態で、もう一度registerした場合、もうすでにregisterされているという扱いになり、scriptタグの出力さえしてくれません。

なので、その場合でscriptタグを出力したいならenqueueしましょう。

つまり順番的に

1. enqueue（上述したようにregisterも含んでいる）
2. dequeue
3. register

2で終わると出力されないのは当然として、3までいっても出力してくれません。なので、

1. enqueue（上述したようにregisterも含んでいる）
2. dequeue
3. enqueue

としましょう。

dequeueされてなければregisterだけでも表示される

少し不思議なのですが、

1. enqueue（上述したようにregisterも含んでいる）
2. deregister
3. register

2で終わると出力されませんが、3でregisterすると出力されるようになります。

ここまで説明した挙動から考えると、2種類のリストが存在していると推察されます。register用のリスト、enqueue用のリストです。両方のリストに入ると出力されますが、片方だけだと出力されない、というような挙動が想像されます。

srcのURLを変えるにはderegisterする必要がある

スクリプトのURLを変えたくて$srcを変えたい場合、enqueueで上書きできるのかと思ったらできません。$srcはregister時のもののままです。

なので、ある$handleで既にregisterされたものを別のURLに変えたい場合、deregisterする必要があります。

一度deregisterしたら、registerでもenqueueでも同じように、scriptタグを表示してくれます。

in_footerをfalseに変えるにはderegisterする必要がある

$argsの一つの要素であるin_footerをtrueからfalseにするにはderegisterにする必要があります。なぜか逆にfalseからtrueに変える場合は、deregisterしなくても変更できました。これはバグではないかと疑っています。以下はwp-includes/functions.wp-scripts.phpというファイルです。

プログラマーの意図としては、in_footerに値が入っている場合、本当は376行目を実行させたいはずです。しかし、in_footerに「falseという値」が入っている場合は、375行目の ! empty( $args['in_footer'] ) はfalseを返すので実行されません。

なので、registerされてる場合で、in_footerをtrueからfalseに変更できません。

ちなみに、deregisterした後でさえも、in_footerをfalseに指定しているなら376行目は実行されません。ただ、in_footerのデフォルトがfalseなので、falseが設定されるのです。

その下の、379行目のstrategyの方は、値が入っていればきちんと実行してくれます。

思った挙動をしない場合は一度deregisterすればOK

とまぁ、私がこれまで発見した細かい不思議な挙動についてお伝えしました。

簡単に言ってしまうと、enqueueに指定した引数が思ったように反映されない場合は、一度deregisterしてからenqueue（もしくはregister）すれば反映されるということです。

公式でも引数を変更する場合はderegister推奨とのこと

公式サイトを見ていると、以下を見つけました。

If you try to register or enqueue an already registered handle with different parameters, the new parameters will be ignored. Instead, use wp_deregister_script() and register the script again with the new parameters.

wp_enqueue_script()

和訳すると

既に登録済みのハンドルを異なるパラメータで登録またはキューに追加しようとすると、新しいパラメータは無視されます。代わりに、wp_deregister_script()を使用し、新しいパラメータでスクリプトを再度登録してください。

ということです。

しかし、実際は無視まではされません。例えば、私が実験した結果、deregisterしない状態で、第5引数だけ変更したい場合、

のように、$handleと第5引数以外を指定しなくても正常に動きました。第2〜4引数は以前の値が引き継がれ、第５引数だけ変更されました。

とはいえ、公式のページが上のように推奨しているので、従っておいた方が無難でしょう。今後のアップデートで動かなくなる可能性もあるので。

コード内に複数回、値を記載することになるので冗長になってしまうのが残念ですね。

読み込む順番にも影響する場合

ここはそこまで重要ではないので、しっかり調査していないのですが、どれを使うかで読み込む順番にも影響しそうです。

基本的にはenqueueした順番に上から出力するようです。

ただ、一度enqueueされたものを、dequeueかderegisterのどちらで外して、その後enqueueするかで順番の変動がありました。ただ、この法則性がよくわかりませんでした。

とはいえ、読み込む順番が重要なスクリプトの場合は、引数の$depsを使ってしっかり指定してあげれば問題ないです。

さいごに

enqueue、register、dequeue、deregisterの使い方のポイントをご説明しました。決してシンプルな仕組みではないので、もう少しわかりやすいものにして欲しいと感じました。