WordPressでJavaScriptを外部ファイルで読み込む方法

Webサイトに何かしら動きをつけたい時にJavaScriptが必要になります。しかし、WordPress開発に慣れていないと、JavaScriptをどう読み込むべきか分からないですよね。

当記事では、WordPressでJavaScriptを外部ファイルとして読み込む基本的な方法をご紹介します。この方法は、開発者向けの内容になりますので、手軽にJavaScriptを扱いたい方は、以下の記事をご覧ください。

2022.10.30

2023.11.20

WordPressの記事上でJavaScriptを使うには少し工夫が必要です。そのままJavaScriptのコードを書いても動作しないからです。原因はWordPressのエディターの自動改行機能により、文中に挿入された<script>～</script> 内に含まれる...

WordPressではscriptタグを直接書いて読み込まない

一般的なWebサイト制作では、以下のようにhead内やbodyの閉じタグの直前にscriptタグを書いてJavaScriptファイルを読み込むことが多いですよね。

<!-- 例）bodyの閉じタグの前にscriptタグを書いて読み込み -->
  <script type="text/javascript" src="スクリプトのパス"></script>
</body>

WordPessには、テーマディレクトリのパスを取得できる関数「get_template_directory_uri()」が用意されているので、以下の記述でスクリプトを読み込むことができます。

// 例）テーマフォルダ内の「my-script.js」を読み込む場合
  <script type="text/javascript" src="<?php echo get_template_directory_uri() . '/my-script.js'; ?>"></script>
</body>

これでも問題なく読み込めますが、WordPress開発では非推奨の方法になります。理由としては、後述するwp_enqueue_script()を使った方法のほうが安全かつ確実にファイルの読み込みを管理できるからです。

wp_enqueue_script()とは？

WordPressで推奨されているJavaScriptの読み込みに使用する関数です。scriptタグを直接書き込む方法と実現できることは大きく変わりませんが、以下の利点があります。

ファイルの重複読み込みを防ぐ
ファイルの読み込み順序を制御しやすい
functions.phpにて一元管理が可能

WordPress開発では、wp_enqueue_script()を使うデメリットが特にないので、JavaScriptの読み込みは、この関数を使うものだと覚えておきましょう。

公式ページ：WordPress Developer Resources | Function| wp_enqueue_script

wp_enqueue_script()の使い方

それではwp_enqueue_script()の使い方をご紹介します。まずは、wp_enqueue_script()の最も基本的な書き方をみていきましょう。

<?php
// テーマフォルダ内の「my-script.js」を読み込む場合
add_action( 'wp_enqueue_scripts', function(){
  wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
} );

// 出力結果
?>
<script type="text/javascript" src="テーマディレクトリまでのパス/my-script.js?ver=6.4.1" id="my-script-js"></script>

上記は、テーマフォルダ内の「my-script.js」ファイルを読み込むサンプルです。こちらが今回のゴールになりますので、それぞれ分解してみていきましょう。

wp_enqueue_script()は単体で使わない

WordPress開発では、wp_enqueue_script()を単体で扱いません。サンプルで使われている関数（add_action〜）とセットで使うものだと覚えておいてください。

WordPressでは、様々なフック（処理を実行できるタイミングのようなもの）が用意されています。その中の1つに「wp_enqueue_scripts」と呼ばれるアクションフックが存在します。

公式ページ：WordPress Developer Resources | Hook | wp_enqueue_scripts

「wp_enqueue_scripts」は、フロントのファイルの読み込みに最も最適なフックなため、wp_enqueue_script()はこのフックの中で実行します。（実行されるタイミングは、WordPressにheadタグが生成される直前くらい）

// NG例（単体で使っている）
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );

// OK例（適切なフックの中で実行されている）
add_action( 'wp_enqueue_scripts', function(){
  wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
} );

wp_enqueue_script()で使えるパラメータ

wp_enqueue_script()は、以下のように5つまで引数を指定できます。このパラメータを変更することで、読み込みの順番や場所などをコントロールできます。各パラメータについて順番に解説していきます。

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

ただ単にファイルを読み込むだけであれば、$handleと$srcだけの記入でも大丈夫です。

$handle：ハンドル名の指定

読み込むスクリプトのハンドル名を記入します。この名前は、スクリプトを判別して重複読み込みを防ぐために使われますので、必ず固有の名称にしてください。

// 同じハンドル名のスクリプトは1度しか読み込まない
// 以下のように3つ処理を書いても、読み込まれるのは1つだけ
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );

$src：スクリプトのパス

読み込むスクリプトのパスを記入します。冒頭でもご紹介したようにテーマディレクトリまでのパスを取得できる関数と合わせて使うことが多いです。

wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );

$deps：依存関係を指定

先に読み込んでほしいスクリプトがあれば、そのスクリプトのハンドル名を記入することで依存関係を示せます。例えば「A-script.js」の読み込みを「B-script.js」の読み込み後に実行したい場合などに使います。（依存関係が特に必要なければ、array()を記入）

// 以下の読み込み順は、A-script -> B-script
wp_enqueue_script( 'A-script', 'パス' );
wp_enqueue_script( 'B-script', 'パス' );

// 以下の読み込み順は、B-script -> A-script
wp_enqueue_script( 'A-script', 'パス', array( 'B-script' ) );  // B-scriptの後に実行される
wp_enqueue_script( 'B-script', 'パス' );

この依存関係は、WordPressで既に登録されているスクリプトに対しても行えます。特にWordPress内蔵の「jQuery」を使う際に指定することが多いです。

// 以下のスクリプトは、jQueryの読み込み後に読み込まれる
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js', array( 'jquery' ) );

$ver：スクリプトのバージョンを指定

ファイル名の末尾にクエリパラメータとして追加する文字列を記入します。以下はバージョンを1.2に指定した例です。何も指定しなければWordPressのバージョンが反映されます。

// 例）バージョンを1.2に指定すると
wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js', array(), '1.2' );

// 出力結果（ファイル名の末尾にver=XXが付与される）
<script type="text/javascript" src="テーマディレクトリまでのパス/my-script.js?ver=1.2" id="my-script-js"></script>

このバージョンはキャッシュ対策に使われます。一般的には、ファイルの更新日時をバージョンに指定することが多いです。これでファイルを更新する度にキャッシュを更新できます。

// バージョン番号にjsファイルの更新日を指定
wp_enqueue_script(
  'my-script',
  get_template_directory_uri() . '/my-script.js',
  array(),
  filemtime( get_template_directory() . '/my-script.js' )
);

// 出力結果（ファイルが更新される度に番号が変わる）
<script type="text/javascript" src="テーマディレクトリまでのパス/my-script.js?ver=1699424961" id="my-script-js"></script>

$args：出力タイミングや場所を操作

この引数は連想配列になっており、以下の2つのパラメータを指定できます。それぞれ指定することで、読み込み方や場所を変更することができます。

strategy	‘defer’ か ‘async’ のどちらかを指定 ‘defer’ならdefer属性、’async’ならasync属性をscriptタグに付与
in_footer	true か false のどちらかを指定 trueならスクリプトをwp_footerに出力、falseならスクリプトをwp_headに出力

実際に記入してみると以下になります。

wp_enqueue_script(
  'my-script',
  get_template_directory_uri() . '/my-script.js',
  array(),
  false,
  array(
    'strategy' => 'defer', // defer属性付与
    'in_footer' => true // wp_footerで出力
  )
);

特定のページだけJavaScriptを読み込む

JavaScriptファイルによっては、トップページなど特定のページでのみ読み込みたいケースがありますよね。そんな時は「wp_enqueue_scripts」フック内でWordPressの条件分岐タグを使うことで、読み込むページを制限できます。

add_action( 'wp_enqueue_scripts', function(){
  // トップページだけ「my-script.js」を読み込む
  if( is_front_page() ){
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
  }
} );

このようにJavaScriptの読み込みを制限することで、エラーの発生やページ表示速度の向上が期待できますので、ぜひ試してみてください。

管理画面でJavaScriptを読み込む方法

ここまで紹介したのは、フロントでJavaScriptを読み込む方法です。管理画面でJavaScriptを読み込み、動的なUIを構築したい方は、以下のアクションフック内でwp_enqueue_script()を実行してください。

// my-script.jsを管理画面で読み込む
add_action( 'admin_enqueue_scripts', function(){
  wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
} );

公式ページ：WordPress Developer Resources | Hook |admin_enqueue_scripts

管理画面のソースコード上に、JavaScriptファイルを読み込むscriptタグが出力されていればOKです。

また、このアクションフックは、現在表示されている管理画面のページの識別名を引数として利用できます。この引数を利用すれば、管理画面の特定のページに限定してJavaScriptを読み込めます。

// 外観 > ウィジェットの画面でのみmy-script.jsを読み込む
add_action( 'admin_enqueue_scripts', function( $hook_suffix ){
  if( $hook_suffix == 'widgets.php' ){
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/my-script.js' );
  }
} );