WordPressの管理画面に独自のスクリプトやスタイルを読み込ませる方法まとめ

WordPressでテーマやプラグインを開発していると、管理画面に独自のスクリプトやCSSを適用したいケースがでてきます。

ここではその方法をまとめました。

管理画面の全ページに読み込ませたい場合

admin_enqueue_scriptsというフックを使います。管理画面に読み込ませる最も基本的な方法になります。

function my_admin_enqueue() {
	// スクリプト
	wp_enqueue_script(
		'admin-custom',
		get_template_directory_uri() . '/js/ admin-custom.js',
		array('jquery'),
  );
	// CSS
	wp_enqueue_style(
		'custom_css',
		get_template_directory_uri() . '/inc/css/custom.css'
	);
}

add_action( 'admin_enqueue_scripts', 'my_admin_enqueue' );

このフックを使うと管理画面の全ページに読み込まれるので、用途としては例えば管理画面全体のデザインを変えたい場合に使うことができます。

この方法は簡単ですが特定のページでのみ使うスタイルやスクリプトの場合、トラブルを避けるためにも後述する方法でページ毎に出し分けたましょう。

特定のページにのみ読み込ませたい場合

WordPressでは管理画面の各ページには$hook_suffixと呼ばれるユニークな接尾辞が設定されています。それを利用することで特定のページにのみスクリプトやスタイルを読み込ませることができます。

実装方法としては次の2つがあます。

• フック名に$hook_suffixを使う
• 読み込み関数内で分岐させる

どちらを使うかはケースバイケースです。メンテナンスしやすい方を選びましょう。

フック名に$hook_suffixを使う

WordPressではadmin_head-$hook_suffixのような形式でフックを指定すると特定のページでのみスクリプトやスタイルを読み込ませることができます。

また、ファイルの読み込みではなくページ内に直接出力したい場合はadmin_print_styles-$hook_suffixやadmin_print_scripts-$hook_suffixを使います。こちらでもwp_enqueue_srciptなどを使ってファイルを読み込ませることは可能ですが推奨ではないようです。

// ファイルを読み込む
add_action("admin_head-$hook_suffix", 'my_admin_script');
function my_admin_srcipt() {
	// スクリプト
	wp_enqueue_script( 'admin-custom', get_template_directory_uri() . '/js/ admin-custom.js', array('jquery') );
	// CSS
	wp_enqueue_style( 'custom_css', get_template_directory_uri() . '/inc/css/custom.css' );
}
 
// スタイルを出力
add_action("admin_print_styles-$hook_suffix", 'my_admin_css');
function my_admin_css() {
  echo '<style>
	出力したいCSS
  </style>' . PHP_EOL
}
 
// スクリプトを出力
add_action("admin_print_scripts-$hook_suffix", 'my_admin_script');
function my_admin_css() {
  echo '<script>
	出力したいスクリプト
  </script>' . PHP_EOL
}

例えば投稿編集ページの$hook_suffixはpost.phpなので次のように書くと投稿編集ページでのみ読み込まれるようになります。

add_action( 'admin_head-post.php', 'my_admin_scripts' );

ちなみに、これだと同じ投稿編集ページでも新規追加したときのページでは読み込まれません。同じ画面に見えますが、新規追加の$hook_suffixはpost-new.phpなのです。そのため新規・既存の両方の編集画面で読み込ませたい場合、次のようにadd_action()を2つ書く必要があります。

add_action( 'admin_head-post.php', 'my_admin_post_scripts' );
add_action( 'admin_head-post-new.php', 'my_admin_post_scripts' );

さらに投稿も固定ページも（ついでにカスタム投稿タイプやメディアの編集画面も）$hook_suffixは全て同じになるため、分けたい場合はフックする関数の中でポストタイプ毎に分岐させる処理が必要になります。

この方法はadd_action()を並べて書くので分かりやすいですが複雑な条件分岐をさせたい場合は次に説明するadmin_enqueue_scriptsを使い関数内で分岐させる方法を使いましょう。Codexを見てもそちらの方が推奨のようです。

admin_enqueue_scripts | Hook | WordPress Developer Resources

関数内で$hook_suffixをつかって分岐させる

admin_enqueue_scriptsフックを使うと引数に$hook_suffixが渡されるので、それを利用して出し分けることができます。この場合add_action()は1つ書くだけで済みます。

先ほど書いた新規と既存の投稿編集画面に読み込ませたい場合は次のようなコードになります。投稿タイプごとに分けるなど複雑な条件分岐をさせたい場合、こちらの書き方が便利です。基本的にはこちらを使いましょう。

function my_admin_enqueue( $hook_suffix ) {
  if ( 'post.php' === $hook_suffix || 'post-new.php' === $hook_suffix ) { 
	    // 投稿の編集と新規投稿画面でのみ読み込むスクリプト
	    wp_enqueue_script(
		    'admin-custom',
		    get_template_directory_uri() . '/js/ admin-custom.js',
		    array('jquery'),
      );
	    // CSS
	    wp_enqueue_style(
		    'custom_css',
		    get_template_directory_uri() . '/inc/css/custom.css'
	    );
   }
}

add_action( 'admin_enqueue_scripts', 'my_admin_enqueue' );

$hook_suffixの調べ方

URLから調べる

一番簡単な調べ方はURLを見ることです。WordPress標準のページでは$hook_suffixの値はページのURLのwp-adimin/と?=・・・の間の文字列になります。例えば投稿編集画面では下図のようになります。

この場合、$hook_suffixはpost.phpなので例えば次のように書くと投稿編集ページでのみ読み込まれるようになります。

add_action( 'admin_head-post.php', 'my_admin_scripts' );

ただ、これはWordPress標準のページではよいですが、プラグインや自分で追加したページの場合には使えません。例えばrevision-controlというプラグインの管理画面のURLは次のようになりますが、options-general.phpではありません。

$hook_suffixを表示させて調べる

自分やプラグインが追加したページの$hook_suffixを確実に調べたい場合は下記のコードをfunctions.phpに追加して管理画面に表示させて調べましょう。

function current_pagehook(){
	global $hook_suffix;
	if( !current_user_can( 'manage_options') ) return;
	echo '<div class="updated"><p>hook_suffix : ' . $hook_suffix . '</p></div>';
}
add_action('admin_notices', 'current_pagehook');

このコードは次のサイトから引用させていただきました。
特定のWordPress管理画面でのみ独自のCSSやJavaScriptを読み込む方法 | WordPress テーマ DigiPress

このコードで調べると、先ほどのrevision-controlプラグインの管理画面の$hook_suffixはsettings_page_revision-controlとなります。

WordPress標準の$hook_suffix一覧

WordPress標準の管理画面における各ページの$hook_suffixは次のようになります。

プラグインなどで追加したページの$hook_suffix

標準以外のページの$hook_suffixは次のようなルールで設定されます。

サブメニューの場合が少しわかりにくいですね。
例えばプラグインでは独自の設定画面を「設定」メニューのサブメニューへ追加することが多いですが、その場合の$hook_suffixはsettings_page_{メニュースラッグ}となります。

自作テーマなどで「外観」メニューに設定画面を追加した場合は、appearance_page_{メニュースラッグ}です。

メニュー名のサニタイズしたタイトルというのは推測しにくいので、自分で追加したページについては先ほどのコードで$hook_suffixを調べるの良さそうです。

カスタマイザーで読み込ませたい場合

カスタマイザーのページでは、customize_controls_enqueue_scriptsという専用のフックが用意されています。$hook_suffixを使ってもできるとは思いますが通常は専用フックを使った方が良いと思います。

ちなみにファイルの読み込みではなく直接スクリプトやCSSを出力させたい場合は次のフックを使います。

customize_controls_print_scripts
customize_controls_print_styles

//カスタマイザーページでファイルを読み込む
add_action( 'customize_controls_enqueue_scripts', 'my_customize_enqueue' );
//カスタマイザーページ内にスクリプトを出力
add_action( 'customize_controls_print_scripts', 'my_customize_script_enqueue' );
//カスタマイザーページ内にスタイルを出力
add_action( 'customize_controls_print_styles', 'my_customize_style_enqueue' );

ちなみにカスタマイザーのライブプレビューに関連するスクリプトはcustomize_preview_initフックを使うことが推奨されています。

Plugin API/Action Reference/customize preview init « WordPress Codex

これで管理画面に独自のスクリプトやスタイルを読み込ませるには迷わないと思います。便利な管理画面をどんどん作っていきましょう。