WordPressでJavascriptのスクリプトファイルをロードする場合には、WordPressの関数を使用します。

通常のHTMLのように<script>タグを書き込んでも、きちんと動作してくれる場合もありますが、WordPressの仕様やプラグインとの関連で不具合を起こす原因になりますので、スクリプトファイルをロードする関数wp_enqueue_scriptを必ず使用しましょう。

wp_enqueue_script関数

wp_enqueue_script関数は、使用するスクリプトをあらかじめ予約しておく（キューに入れる）関数です。
WordPressは、テンプレートファイル内のwp_head関数の箇所で、キューに入れたスクリプトをロードする<script>タグを一括生成します。

使用するスクリプトをキューに入れておく

<script>タグが生成される

※wp_head関数の部分では、実際にはもっといろいろなタグが生成されますが、ここでは説明のために省略してあります

つまり、テンプレートファイルにwp_head関数がきちんと記述されていないと、キューに入れたスクリプトもロードされません。
wp_head関数はWordPressでは必須の関数なので、head要素の閉じタグ</head>の前に必ず記述しておきましょう。

wp_enqueue_script関数の詳細

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

$handle — スクリプトのハンドル名
$src — スクリプトのURL（オプション）
$deps — このスクリプトに関連するスクリプトのハンドル名（オプション）
$ver — スクリプトのバージョン（オプション）
$in_footer — trueの場合、フッターで読み込む（デフォルトはfalse）（オプション）

$handleでは、スクリプトを区別する任意の名前を付けます。この引数は必須です。

$handleに設定する名前は自由ですが、使用できない物がいくつかあります。
利用頻度の高いものでは'common'が使用できません。
これはWordPressがシステム側で、既に'common'というスクリプトを使用しているためです。
もし、テーマファイルのほうでcommon.jsというスクリプトを使用する場合には、ハンドル名を'theme-common'などにするか、ファイル名自体をsite.jsなどに変更してください。

▼これはNG

▼これならOK

$depsでは、このスクリプトよりも前にロードするスクリプトを、ハンドル名の配列で指定します。
この引数を指定する事により、<script>タグが自動的に並び替えられて生成されます。

$verには、任意のバージョンを記述します。これは省略も可能ですが、できるだけ記述しましょう。
バージョンを記載することで、スクリプトのURLにパラメータverが追加され、ブラウザキャッシュ対策になります。

オリジナルのスクリプトの場合は、テーマのバージョンを返す関数を使用すると便利です。（記事: テーマのバージョンを取得）

wp_enqueue_script関数の使用例

例1: オリジナルのスクリプトを読み込む

テーマ用に作成したスクリプトファイルsite.jsをロードします。

まず、テーマディレクトリにjsディレクトリを作成し、その配下にsite.jsを設置します。

site_js

そして、以下のコードを、テンプレートファイル（index.php, header.phpなど）の<head>要素内の、wp_head()より前の行に記述します。

第2引数では、テーマファイルのディレクトリを取得するget_template_directory_uri関数を使用します。

第3引数では、ここでは'jquery'を指定しています。
WordPressでは、jQueryライブラリはデフォルトでロードされ、ハンドル名は'jquery'になります。
site.jsでjQueryライブラリを使用している場合には、site.jsはjQueryよりも後にロードされる必要があるので、第3引数は上記のようになります。
jQueryなどのライブラリを使用しない場合は、第3引数を空の配列array()にしても構いません。

例2: jQueryプラグインを使用する場合

jQueryプラグインのColorboxを使用する例です。
以下のようにファイルを配置し、コードを記述します。

colorbox

前述の通り、jQueryライブラリはデフォルトでロードされます。
ColorboxはjQueryよりも後に、site.jsはjQueryとColorboxよりも後に読み込まれる必要があるので、それぞれの第3引数は上記のようになります。

例3: head要素以外に記述する場合

wp_enqueue_script関数で設定した（キューに追加した）スクリプトは、実際にはテンプレートファイルのwp_head関数の場所で、<script>タグが生成されます。
上記の例ではwp_enqueue_script関数を<head>要素内に記述しましたが、それ以外の場所にも記述できます。

テンプレートファイルでget_header関数を使用している場合、get_header関数より前に記述します。

functions.phpで呼び出す場合は、wp_enqueue_scriptsアクションフックを使用します。

wp_enqueue_script関数は、wp_head関数より前、wp_enqueue_scriptsフックよりも後で使用します。
※正確にはwp_enqueue_script関数をwp_head関数より後で使用した場合は、wp_footer関数より前であれば、wp_footer関数の位置で<script>タグが生成されます。また、第5引数の$in_footerをtrueにする事で、wp_footer関数の位置での生成にできます。

関数名はwp_enqueue_scriptですが、アクションフックはwp_enqueue_scriptsと複数形になっているので注意しましょう。

jQueryライブラリを使用する場合の注意

jQueryライブラリを使用してスクリプトを記述する場合には、上記以外にも注意点があります。
詳しくは、記事:WordPressでjQueryを使うための3つのポイントをご覧ください。

まとめ

  • スクリプトのロードには、<script>タグを直接書き込まずに、wp_enqueue_script関数を使用する
  • スクリプトがロードされる順番が重要なので、第3引数をきちんと指定する
  • wp_enqueue_script関数は、通常はwp_head関数より前、wp_enqueue_scriptsフックよりも後になるように記述する