WordPressのスクリプトハンドル名の調べ方

WordPressのカスタマイズ記事やトラブル解決の手順で、「対象のスクリプトハンドル名を指定してください」という説明を見かけることがあります。

wp_dequeue_script()などで特定のJavaScriptを止めたいときに必要になるものですが、「そもそもハンドル名って何？どこで分かるの？」とつまずく方は少なくありません。

この記事では、スクリプトハンドル名とは何かをやさしく整理したうえで、ソースコードから探す方法・プラグインを使って一覧で確認する方法・子テーマで実際に読み込みを止めるコード例まで、順番に解説します。

専門的な知識がなくても進められるよう、画面のどこを見ればよいかから説明します。

スクリプトハンドル名とは

WordPressでは、テーマやプラグインが読み込むJavaScript（やCSS）の一つひとつに、区別するための名前（ハンドル名）が付けられています。料理に例えるなら、棚に並んだ調味料に貼られたラベルのようなものです。後から「この調味料だけ抜きたい」と思ったとき、ラベル名が分かっていれば正確に指定できます。

このハンドル名は、開発者がwp_enqueue_script()という関数でスクリプトを登録するときに、第1引数として付けています。たとえば次のコードでは、my-sliderがハンドル名です。

<?php
// 第1引数 'my-slider' がハンドル名
wp_enqueue_script( 'my-slider', '.../slider.js', array( 'jquery' ), '1.0', true );

このハンドル名が分かると、そのスクリプトだけを狙って読み込みを止めたり、読み込む順番を変えたりといった細かい制御ができるようになります。プラグイン同士のJavaScript競合を解消したいときに、まず必要になる情報です。

WordPressが出力するHTMLでは、ハンドル名の末尾に自動的に-js（CSSの場合は-css）が付きます。実際のハンドル名は、この末尾を取り除いた部分です。

方法1：ページのソースコードから探す

追加のプラグインを入れずに確認できる、もっとも手軽な方法です。ブラウザでサイトを開き、ソースコードを表示して<script>タグのid属性を見ます。

対象ページをブラウザで開く

問題のスクリプトが読み込まれているページを、PCのブラウザ（Chrome、Edge、Firefoxなど）で開きます。
ページのソースを表示する

ページ上で右クリックし、「ページのソースを表示」を選びます（ショートカットはCtrl + U / Macは⌘ + U）。HTMLのソースコードが新しいタブで開きます。
script タグを検索する

ページ内検索（Ctrl + F / ⌘ + F）で、競合していそうなプラグイン名やファイル名（例：slider）を検索します。該当する<script>タグが見つかったら、そのid属性を確認します。
id から -js を除いた部分がハンドル名

たとえばid="my-slider-js"と書かれていれば、ハンドル名は末尾の-jsを除いたmy-sliderです。これがコードに指定する名前になります。

実際のソースコードでは、次のように表示されます。

<!-- id の "my-slider-js" のうち、末尾 -js を除いた "my-slider" がハンドル名 -->
<script src="https://example.com/wp-content/plugins/my-slider/slider.js?ver=1.0" id="my-slider-js"></script>

キャッシュ系や高速化系プラグインを使っていると、JavaScriptがまとめて圧縮（結合）され、id属性が消えていたり別名になっていたりすることがあります。その場合は、一度それらのプラグインの最適化機能をオフにしてから確認すると、本来のハンドル名が見つけやすくなります。

方法2：Query Monitorプラグインで一覧から確認する

ソースコードを追うのが難しい場合や、読み込まれているスクリプトを一覧でまとめて確認したい場合は、開発者にも広く使われている無料プラグインQuery Monitorが便利です。読み込まれているスクリプトのハンドル名・ファイルのパス・依存関係を、管理画面から一覧で確認できます。

Query Monitor をインストール・有効化する

「プラグイン → 新規追加」でQuery Monitorを検索し、インストールして有効化します。調査が終わったら停止・削除して問題ありません。
管理バーのメニューを開く

有効化すると、画面上部の管理バーに数値（ページの処理情報）が表示されます。確認したいページを開いた状態で、この表示にカーソルを合わせます。
Scripts の項目を確認する

メニューから「Scripts」（または「Scripts & Styles」）を選ぶと、そのページで読み込まれているスクリプトの一覧が表示されます。「Handle」列に並んでいるのがハンドル名です。ファイルのパスから、どのプラグインのスクリプトかも判断できます。

Query Monitorは「Dependencies（依存関係）」も表示してくれるため、あるスクリプトがjqueryなどに依存していることも分かります。競合の原因を切り分けるうえでも役立つツールです。

調べたハンドル名で読み込みを止める

ハンドル名が分かったら、子テーマのfunctions.phpに次のように記述することで、そのスクリプトの読み込みを止められます。conflicting-plugin-scriptの部分を、実際に調べたハンドル名に置き換えてください。

<?php
/**
 * 指定したハンドル名のスクリプトの読み込みを停止する。
 * 'conflicting-plugin-script' は実際に調べたハンドル名に置き換える。
 */
function apura_dequeue_conflicting_script() {
	if ( ! is_admin() ) {
		wp_dequeue_script( 'conflicting-plugin-script' );
	}
}
add_action( 'wp_enqueue_scripts', 'apura_dequeue_conflicting_script', 100 );

特定のページだけで止めたい場合は、is_page()などの条件分岐と組み合わせます。たとえば、IDが10の固定ページ以外で読み込みを止めるには、次のように書きます。

<?php
function apura_dequeue_conflicting_script() {
	// ID 10 の固定ページではスクリプトを残し、それ以外で停止する
	if ( ! is_admin() && ! is_page( 10 ) ) {
		wp_dequeue_script( 'conflicting-plugin-script' );
	}
}
add_action( 'wp_enqueue_scripts', 'apura_dequeue_conflicting_script', 100 );

functions.phpの編集はサイトの表示に直接影響します。必ず子テーマで作業し、編集前にバックアップを取ってください。記述ミスがあると画面が真っ白になることもあるため、可能であれば検証環境（ステージング）で試してから本番に反映するのが安全です。

なお、wp_dequeue_script()でスクリプトを止めると、そのスクリプトが提供していた機能（スライダーやポップアップなど）も動かなくなります。

あくまで競合を回避するための暫定対応と考え、恒久的にはプラグインの開発元へ競合を報告するか、競合しない別のプラグインへの乗り換えも検討しましょう。

まとめ

スクリプトハンドル名は、WordPressが読み込む個々のJavaScriptに付けられた識別名です。ソースコードの<script>タグのid属性から末尾の-jsを除いた部分を確認するか、Query Monitorプラグインの一覧から確認できます。

ハンドル名さえ分かれば、子テーマのfunctions.phpで特定のスクリプトだけを狙って制御できます。プラグイン同士のJavaScript競合に悩んでいる場合は、まずこの記事の手順でハンドル名を特定するところから始めてみてください。