ワードプレスのwp_localize_script関数の使用方法・解説

概要

wp_localize_script関数は、JavaScriptファイルをWordPressに追加する際に、スクリプト向けの変数を追加するための関数です。これを利用することで、サーバーサイドのデータをクライアントサイドのJavaScriptに渡すことができます。これにより、WordPressの環境設定やユーザーの情報などをJavaScriptコードで利用できるようになります。

この関数は以下のような状況でよく使われます。

1. Ajaxリクエスト時に必要なURLをJavaScriptに渡す。
2. テーマやプラグインの設定値をJavaScriptで扱う。
3. 現在のユーザーの情報（IDや権限）をJavaScriptで取得する。
4. REST APIのエンドポイントをJavaScriptに提供する。
5. WordPressの翻訳文字列をJavaScriptに渡す。
6. JavaScriptで利用するための動的な設定情報を提供する。
7. メディアライブラリへのパスをJavaScriptに渡す。
8. イベントやカスタムメッセージをJavaScriptで処理する。

構文

wp_localize_script( $handle, $object_name, $l10n );

パラメータ

• $handle (string): 対象となるスクリプトのハンドル名。
• $object_name (string): JavaScript側で利用する変数名。
• $l10n (array): 渡すデータを含む連想配列。

戻り値

この関数は値を返しません。

関連する関数

• wp_enqueue_script

使用可能なバージョン

この関数はWordPress 2.8.0以降で使用可能です。

コアファイルパス

この関数は wp-includes/script-loader.php に含まれています。

サンプルコード

サンプル1: Ajax URLを取得する

以下のコードは、Ajaxリクエストに必要なURLをJavaScriptに渡します。

function my_enqueue_scripts() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery') );
    wp_localize_script( 'my-script', 'myAjax', array( 'ajaxurl' => admin_url( 'admin-ajax.php' ) ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

このサンプルコードは、Ajax呼び出しに使用するURLをJavaScriptで利用するために渡しています。

サンプル2: 翻訳文字列をJavaScriptに渡す

以下のコードは、翻訳したい文字列をJavaScriptに渡します。

function my_enqueue_scripts() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery') );
    wp_localize_script( 'my-script', 'localizedStrings', array( 'welcome' => __('Welcome', 'text-domain') ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

このサンプルコードは、翻訳された文字列をJavaScriptで使用可能にしています。

サンプル3: ユーザー情報を渡す

以下のコードは、現在のユーザーの情報をJavaScriptに渡します。

function my_enqueue_scripts() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery') );
    wp_localize_script( 'my-script', 'userData', array( 'userID' => get_current_user_id() ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

このサンプルコードでは、現在のユーザーのIDをJavaScriptで利用できるように渡しています。

サンプル4: REST API エンドポイントを渡す

以下のコードは、REST APIのエンドポイントをJavaScriptに渡します。

function my_enqueue_scripts() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery') );
    wp_localize_script( 'my-script', 'apiData', array( 'endpoint' => esc_url(rest_url('my-route/v1/')) ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

このサンプルコードは、REST APIのエンドポイントをJavaScript用に渡しています。

サンプル5: 設定データを渡す

以下のコードは、特定の設定データをJavaScriptに渡します。

function my_enqueue_scripts() {
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array('jquery') );
    wp_localize_script( 'my-script', 'siteSettings', array( 'themeColor' => 'blue', 'layout' => 'grid' ) );
}
add_action( 'wp_enqueue_scripts', 'my_enqueue_scripts' );

このサンプルコードでは、テーマのカラースキームやレイアウト設定をJavaScriptに渡しています。

この関数のアクションでの使用可能性

アクション名	使用可能
mu_plugin_loaded
registered_post_type
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query
pre_get_posts
wp
template_redirect
get_header
wp_head

非推奨または削除されたバージョン

この関数は、これまでのところ特定のWordPressバージョンで非推奨または削除されたことはありません。