wp_localize_script() の使い方｜説明・引数・注意点

説明

基本構文

wp_localize_script( string $handle, string $object_name, array $l10n ): bool

引数

• $handle：対象のスクリプト識別名
• $object_name：JavaScript側のオブジェクト名
• $l10n：渡す値の配列

戻り値

成功すれば true。

使い方（サンプル）

wp_enqueue_script( 'my-script', get_theme_file_uri( 'js/app.js' ), array(), '1.0', true );
wp_localize_script( 'my-script', 'MyData', array(
	'ajaxUrl' => admin_url( 'admin-ajax.php' ),
	'nonce'   => wp_create_nonce( 'my_action' ),
) );

注意点

• 先に wp_enqueue_script() か wp_register_script() で登録しておく必要があります。
• 値は文字列に変換されます。数値や真偽値は、JS側で型変換が必要です。
• 型を保ったまま渡したい場合は、wp_add_inline_script() と wp_json_encode() を使います。

実務での使いどころ

• PHPの値（Ajaxの送信先URL、nonceなど）を、JavaScriptへ渡すとき。
• 翻訳した文字列を、JavaScriptへ渡すとき。

よくあるミスと対処

• スクリプトを登録・読み込みする前に呼び、何も渡らない。対象のハンドルを、先に登録する。
• 配列のトップレベルにある、数値や真偽値は、文字列に変換される（ネストした配列の中は、型が保たれる）。型を保ちたいときは、wp_add_inline_script() と wp_json_encode() を使う。
• $object_name が、JavaScriptのグローバル変数になる。他と重ならない名前にする。

NG例

wp_localize_script( 'my-script', 'myData', array( 'limit' => 10 ) ); // JavaScript側では、"10" の文字列になる

OK例

wp_add_inline_script(
	'my-script',
	'const myData = ' . wp_json_encode( array( 'limit' => 10 ) ) . ';',
	'before'
);

使い分け早見表

関連項目

wp_add_inline_script()、wp_enqueue_script()、wp_create_nonce()

公式リファレンス：wp_localize_script() | Function | WordPress Developer Resources