Функция wp_localize_script() в WordPress с примерами

Функция wp_localize_script() используется для передачи данных локализации из PHP в JavaScript для скриптов, зарегистрированных и подключённых в WordPress. Основное назначение функции — это добавление переводимых строк, необходимых для локализации JavaScript, однако её часто используют и для передачи любых данных от PHP к JS.

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

Параметры:

• $handle (строка, обязательно) — название скрипта, к которому будут прикреплены данные локализации. Скрипт должен быть зарегистрирован или добавлен в очередь до вызова этой функции.
• $object_name (строка, обязательно) — имя JavaScript объекта, который будет содержать данные локализации. Имя должно быть уникальным и следовать стандартам JavaScript (без тире, только латинские буквы, цифры и подчеркивания).
• $l10n (массив, обязательно) — массив данных для передачи в JavaScript. Массив может быть как одномерным, так и многомерным.

Возвращаемое значение:

• bool — Возвращает true, если данные были успешно локализованы, и false в случае ошибки.

Описание

wp_localize_script() создает JavaScript объект, содержащий данные из PHP, и делает его доступным в JavaScript коде до начала выполнения указанного скрипта. Важно помнить, что функция должна вызываться после того, как скрипт был зарегистрирован с помощью wp_register_script() или добавлен в очередь с wp_enqueue_script().

Пример 1: Локализация строк для скрипта

Этот пример показывает использование wp_localize_script() для передачи переводимых строк в JavaScript.

add_action( 'wp_enqueue_scripts', 'my_enqueue_script' );

function my_enqueue_script() {
    // Регистрируем и подключаем скрипт
    wp_enqueue_script( 'my-script', get_template_directory_uri() . '/js/my-script.js', array(), '1.0.0', true );

    // Подготавливаем строки локализации
    $translation_array = array(
        'greeting' => __( 'Привет, мир!', 'text-domain' ),
        'farewell' => __( 'До свидания!', 'text-domain' )
    );

    // Локализуем скрипт
    wp_localize_script( 'my-script', 'myScriptTranslations', $translation_array );
}

Теперь в my-script.js вы можете получить доступ к строкам локализации:

console.log( myScriptTranslations.greeting );  // Выведет: Привет, мир!
console.log( myScriptTranslations.farewell );  // Выведет: До свидания!

Пример 2: Передача данных для AJAX запросов

В этом примере wp_localize_script() используется для передачи URL для обработки AJAX запросов и других данных.

add_action( 'wp_enqueue_scripts', 'enqueue_ajax_script' );

function enqueue_ajax_script() {
    wp_enqueue_script( 'my-ajax-script', get_template_directory_uri() . '/js/ajax-script.js', array('jquery'), '1.0.0', true );

    $ajax_data = array(
        'ajax_url' => admin_url( 'admin-ajax.php' ),
        'nonce'    => wp_create_nonce( 'my_ajax_nonce' ),
    );

    wp_localize_script( 'my-ajax-script', 'myAjaxData', $ajax_data );
}

В ajax-script.js теперь можно использовать эти данные для AJAX запросов:

jQuery(document).ready(function($) {
    $.ajax({
        url: myAjaxData.ajax_url,
        type: 'POST',
        data: {
            action: 'my_custom_action',
            nonce: myAjaxData.nonce
        },
        success: function(response) {
            console.log(response);
        }
    });
});

Пример 3: Передача глобальных данных

Вы также можете передавать любые глобальные данные через wp_localize_script().

add_action( 'wp_enqueue_scripts', 'enqueue_global_data' );

function enqueue_global_data() {
    wp_enqueue_script( 'my-global-script', get_template_directory_uri() . '/js/global-script.js', array(), '1.0.0', true );

    $global_data = array(
        'site_url' => get_site_url(),
        'theme_url' => get_template_directory_uri(),
        'some_string' => __( 'Переводимая строка', 'text-domain' )
    );

    wp_localize_script( 'my-global-script', 'GlobalData', $global_data );
}

Теперь данные будут доступны в скрипте global-script.js:

console.log( GlobalData.site_url );  // URL сайта
console.log( GlobalData.some_string );  // Переводимая строка

Когда использовать wp_localize_script()

• Для локализации строк — основной сценарий использования.
• Передача данных для AJAX запросов — удобно для передачи URL, nonce и других параметров.
• Передача глобальных данных — если необходимо передать данные PHP в JS.

Важно

Хотя wp_localize_script() раньше часто использовали для передачи любых данных в JavaScript, с появлением функции wp_add_inline_script() в WordPress 4.5 рекомендуется использовать её для передачи данных, не связанных с локализацией, чтобы избежать ошибок преобразования типов данных (например, чисел в строки).

Пример 4: Локализация с динамическими данными

Иногда нужно передавать данные, которые зависят от условий, например, от текущего пользователя или страницы. Этот пример покажет, как локализовать данные, основанные на текущей сессии или контексте.

add_action( 'wp_enqueue_scripts', 'enqueue_dynamic_data_script' );

function enqueue_dynamic_data_script() {
    wp_enqueue_script( 'dynamic-script', get_template_directory_uri() . '/js/dynamic-script.js', array(), '1.0.0', true );

    $user_data = array(
        'is_logged_in' => is_user_logged_in() ? 'true' : 'false',
        'user_name' => is_user_logged_in() ? wp_get_current_user()->display_name : '',
        'current_page' => get_the_title(),
    );

    wp_localize_script( 'dynamic-script', 'DynamicData', $user_data );
}

В JavaScript это можно использовать так:

if ( DynamicData.is_logged_in === 'true' ) {
    console.log( 'Привет, ' + DynamicData.user_name );
} else {
    console.log( 'Вы не авторизованы.' );
}

console.log( 'Вы находитесь на странице: ' + DynamicData.current_page );

Пример 5: Передача массивов и объектов

Этот пример демонстрирует передачу многомерных массивов и объектов через wp_localize_script(). Это полезно, если в JavaScript нужно передать более сложные структуры данных.

add_action( 'wp_enqueue_scripts', 'enqueue_complex_data_script' );

function enqueue_complex_data_script() {
    wp_enqueue_script( 'complex-data-script', get_template_directory_uri() . '/js/complex-data.js', array(), '1.0.0', true );

    $complex_data = array(
        'user_info' => array(
            'name' => 'Иван',
            'age' => 30,
            'roles' => array( 'subscriber', 'author' )
        ),
        'settings' => array(
            'theme_color' => 'blue',
            'font_size' => 16
        ),
        'messages' => array(
            'welcome' => __( 'Добро пожаловать на сайт!', 'text-domain' ),
            'goodbye' => __( 'До свидания!', 'text-domain' )
        )
    );

    wp_localize_script( 'complex-data-script', 'ComplexData', $complex_data );
}

Использование в JavaScript:

console.log( ComplexData.user_info.name );  // Иван
console.log( ComplexData.settings.theme_color );  // blue
console.log( ComplexData.messages.welcome );  // Добро пожаловать на сайт!

Пример 6: Передача boolean значений и их обработка

Этот пример показывает, как передавать и использовать boolean значения, которые могут быть интерпретированы как строки в JavaScript.

add_action( 'wp_enqueue_scripts', 'enqueue_boolean_data_script' );

function enqueue_boolean_data_script() {
    wp_enqueue_script( 'boolean-data-script', get_template_directory_uri() . '/js/boolean-data.js', array(), '1.0.0', true );

    $boolean_data = array(
        'feature_enabled' => true,
        'user_is_admin' => current_user_can( 'administrator' )
    );

    wp_localize_script( 'boolean-data-script', 'BooleanData', $boolean_data );
}

В JavaScript:

if ( Boolean(BooleanData.feature_enabled) ) {
    console.log( 'Функция включена' );
}

if ( Boolean(BooleanData.user_is_admin) ) {
    console.log( 'Пользователь является администратором' );
}

Пример 7: Локализация в админке

wp_localize_script() можно использовать не только на фронтенде, но и в административной панели. Этот пример демонстрирует добавление данных для использования в скрипте админки.

add_action( 'admin_enqueue_scripts', 'admin_localize_script' );

function admin_localize_script() {
    wp_enqueue_script( 'admin-script', get_template_directory_uri() . '/js/admin-script.js', array(), '1.0.0', true );

    $admin_data = array(
        'admin_url' => admin_url(),
        'screen' => get_current_screen()->id,
        'welcome_message' => __( 'Добро пожаловать в админку!', 'text-domain' )
    );

    wp_localize_script( 'admin-script', 'AdminData', $admin_data );
}

В admin-script.js:

console.log( 'Админ URL: ' + AdminData.admin_url );
console.log( 'Текущий экран: ' + AdminData.screen );
console.log( AdminData.welcome_message );  // Добро пожаловать в админку!

Заключение

Функция wp_localize_script() — это мощный инструмент для локализации строк и передачи данных из PHP в JavaScript в WordPress. Она облегчает работу с переводами в JavaScript и позволяет легко передавать данные для использования в скриптах, связанных с фронтендом или админкой.