WordPress wp_localize_script - jak przekazać dane do JavaScriptu

`wp_localize_script()` tworzy obiekt JavaScript z danych PHP i przypisuje go do zarejestrowanego skryptu. Funkcja zwraca `true`, gdy lokalizacja się powiedzie, albo `false`, gdy się nie powiedzie; `undefined` może natomiast oznaczać, że kod JavaScript odwołuje się do obiektu, którego nie wypisano lub używa innej nazwy.

Podstawowym zastosowaniem funkcji są tłumaczone teksty interfejsu, takie jak komunikaty walidacji czy etykiety. Pobieraj je przez funkcje tłumaczeń WordPressa z domeną motywu lub wtyczki.

Do ogólnej konfiguracji, na przykład adresu endpointu albo ustawień widoku, użyj `wp_add_inline_script()`. Nazwa obiektu lokalizowanego powinna być unikalna, poprawnym identyfikatorem JavaScript i bez dywizu, na przykład `kcNoticeText`.

Najpierw zarejestruj skrypt, dodaj go do kolejki, a następnie wywołaj `wp_localize_script()` z tym samym uchwytem. Dokumentacja WordPressa potwierdza, że funkcja lokalizująca działa tylko dla wcześniej zarejestrowanego skryptu.

add_action( 'wp_enqueue_scripts', 'kc_enqueue_notice_assets' );

function kc_enqueue_notice_assets() {
    $handle = 'kc-notice';

    wp_register_script(
        $handle,
        get_stylesheet_directory_uri() . '/assets/js/notice.js',
        array(),
        '1.0.0',
        true
    );

    wp_enqueue_script( $handle );

    wp_localize_script(
        $handle,
        'kcNoticeText',
        array(
            'saved' => __( 'Zmiany zapisane', 'kc-theme' ),
        )
    );
}

`wp_register_script()` definiuje plik i zależności, a `wp_enqueue_script()` dodaje go do kolejki. Można też użyć samego `wp_enqueue_script()` z adresem pliku, ponieważ ta funkcja może zarejestrować i zakolejkować skrypt w jednym wywołaniu.

Uchwyt przekazany do lokalizacji musi odpowiadać uchwytowi skryptu. Zasoby frontendu zwykle dodajemy w `wp_enqueue_scripts`, a zasoby panelu administracyjnego w `admin_enqueue_scripts`. Skrypt ładowany w stopce wymaga, by motyw wywoływał `wp_footer()`.

Minimalny przykład PHP rejestruje i ładuje plik, a następnie tworzy obiekt, którego nazwy używa JavaScript. W motywie potomnym umieść callback w `functions.php`, a wtyczce przypisz własny adres pliku przez `plugins_url()`.

add_action( 'wp_enqueue_scripts', 'kc_enqueue_notice_script' );

function kc_enqueue_notice_script() {
    $handle = 'kc-notice';

    wp_enqueue_script(
        $handle,
        get_stylesheet_directory_uri() . '/assets/js/notice.js',
        array(),
        '1.0.0',
        true
    );

    wp_localize_script(
        $handle,
        'kcNoticeText',
        array(
            'saved' => __( 'Zmiany zapisane', 'kc-theme' ),
        )
    );
}

const notice = document.querySelector('[data-save-notice]');

if (notice && window.kcNoticeText) {
    notice.textContent = window.kcNoticeText.saved;
}

PHP tworzy obiekt `kcNoticeText`, a JavaScript odczytuje go pod tą samą nazwą. Przetestuj zmianę na kopii witryny; konfiguracja Local WP pozwala sprawdzić motyw lub wtyczkę przed wdrożeniem. Jeśli prace obejmują rozwój motywu albo funkcji witryny, strony firmowe oparte na WordPressie mogą być właściwym zakresem wsparcia.

Przekazuj adres AJAX i nonce jako konfigurację przez `wp_add_inline_script()`, a tłumaczone komunikaty przez `wp_localize_script()`. Nonce to wartość WordPressa używana do weryfikacji żądania; nie przyznaje użytkownikowi uprawnienia do edycji wpisu.

add_action( 'wp_enqueue_scripts', 'kc_enqueue_save_script' );

function kc_enqueue_save_script() {
    $handle = 'kc-save';

    wp_enqueue_script(
        $handle,
        plugins_url( 'assets/js/save.js', __FILE__ ),
        array(),
        '1.0.0',
        true
    );

    $config = array(
        'ajaxUrl' => admin_url( 'admin-ajax.php' ),
        'nonce'   => wp_create_nonce( 'kc_save_item' ),
    );

    wp_add_inline_script(
        $handle,
        'window.kcSaveConfig = ' . wp_json_encode( $config ) . ';',
        'before'
    );

    wp_localize_script(
        $handle,
        'kcSaveText',
        array(
            'error' => __( 'Nie udało się zapisać zmian', 'kc-plugin' ),
        )
    );
}

add_action( 'wp_ajax_kc_save_item', 'kc_save_item' );

function kc_save_item() {
    check_ajax_referer( 'kc_save_item', 'nonce' );

    $item_id = isset( $_POST['item_id'] )
        ? absint( wp_unslash( $_POST['item_id'] ) )
        : 0;

    if ( ! $item_id || ! get_post( $item_id ) ) {
        wp_send_json_error( array( 'message' => 'Nieprawidłowy identyfikator' ), 400 );
    }

    if ( ! current_user_can( 'edit_post', $item_id ) ) {
        wp_send_json_error( array( 'message' => 'Brak uprawnień do edycji wpisu' ), 403 );
    }

    // W tym miejscu dodaj walidację wartości i właściwy zapis pola.
    wp_send_json_success( array( 'itemId' => $item_id ) );
}

Identyfikator wpisu jest najpierw oczyszczany i sprawdzany pod kątem istnienia, a dopiero potem WordPress sprawdza uprawnienie obiektowe `edit_post` dla tego rekordu. Kontrola `current_user_can( 'edit_posts' )` sprawdzałaby ogólną zdolność edycji wpisów, nie dostęp do wskazanego obiektu.

Powyższy callback nie zapisuje pola, ponieważ trzeba dopasować operację do konkretnego typu danych i wymagań wtyczki. Przykład żądania musi przekazać identyfikator i nonce:

fetch(window.kcSaveConfig.ajaxUrl, {
    method: 'POST',
    credentials: 'same-origin',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8' },
    body: new URLSearchParams({
        action: 'kc_save_item',
        nonce: window.kcSaveConfig.nonce,
        item_id: '123'
    })
});

`check_ajax_referer()` weryfikuje nonce, ale nie zastępuje sprawdzenia uprawnień ani walidacji treści. Nie przekazuj sekretów API do przeglądarki, ponieważ odwiedzający może odczytać wartości wysłane w HTML i JavaScript.

`wp_add_inline_script()` lepiej pasuje do ogólnej konfiguracji JavaScript, a `wp_localize_script()` do tłumaczonych tekstów. Funkcja inline dołącza kod przed wskazanym skryptem (`before`) albo po nim (`after`).

$config = array(
    'endpoint' => rest_url( 'kc/v1/search' ),
    'limit'    => 8,
);

wp_add_inline_script(
    'kc-search',
    'window.kcSearchConfig = ' . wp_json_encode( $config ) . ';',
    'before'
);

Kod zadziała, jeśli `kc-search` został wcześniej zarejestrowany i dodany do kolejki. Atrybuty `data-*` są wygodne dla ustawienia przypisanego do jednego elementu, lecz nie umieszczaj w nich haseł ani prywatnych kluczy.

Wartości wysłane do przeglądarki są dostępne dla użytkownika, więc przekazuj tylko dane potrzebne na danym widoku. Nie wysyłaj haseł, prywatnych kluczy API ani informacji, których odbiorca nie powinien zobaczyć.

Waliduj format i zakres danych wejściowych przed użyciem ich w operacji. Przy wypisywaniu do HTML dobieraj escaping do kontekstu, na przykład `esc_attr()` dla atrybutu i `esc_html()` dla treści, a tablice konfiguracji koduj przez `wp_json_encode()`.

Endpoint zmieniający dane powinien sprawdzać nonce, uprawnienie użytkownika do konkretnego obiektu i poprawność parametrów. Nonce ogranicza ryzyko sfałszowania żądania, ale nie jest mechanizmem autoryzacji.

Brak obiektu JavaScript zwykle oznacza, że WordPress nie wypisał lokalizacji albo kod odwołuje się do innej nazwy. W narzędziach deweloperskich wyszukaj nazwę obiektu w panelu Elements, sprawdź `typeof window.kcNoticeText` w Console i potwierdź odpowiedź 200 dla pliku w Network.

Tabela wskazuje kolejność pierwszej diagnostyki: od nazwy obiektu i kolejki skryptów do cache oraz callbacku AJAX. Funkcja `wp_localize_script()` zwraca `true` lub `false`, nie wartość `undefined`; dokumentacja WordPressa potwierdza też wymóg wcześniejszej rejestracji skryptu.

Jeśli problem występuje wyłącznie na środowisku lokalnym, porównaj warunki ładowania i konfigurację hosta. Przygotowanie testowego środowiska opisuje poradnik o WordPress localhost, Local i wp-env.

Używaj unikalnych prefiksów zarówno dla uchwytów skryptów, jak i obiektów JavaScript, na przykład `kc-save` i `kcSaveConfig`. Unikaj ogólnych nazw typu `data`, które łatwo kolidują z kodem innych wtyczek.

Zbuduj jeden obiekt konfiguracji zamiast wielokrotnie lokalizować ten sam uchwyt i nazwę. Przy wielu komponentach przypisz ustawienia do właściwych elementów DOM albo utwórz nazwane obiekty dla odrębnych skryptów.

Po zmianie WordPressa, motywu lub wtyczki sprawdź docelowy widok, obiekt w konsoli, odpowiedź endpointu i uprawnienia do edytowanego wpisu. Jeśli błąd dotyczy działającego motywu lub wtyczki, wsparcie przy stronach WordPress może obejmować diagnostykę i naprawę.

Perspektywa KC Mobile

Z naszych wdrożeń wynika, że błąd `undefined` często wiąże się z różnicą między uchwytem użytym przy enqueue a tym przekazanym do lokalizacji albo z warunkiem, który ładuje plik tylko na wybranych widokach. Dlatego diagnozujemy konkretny HTML, kolejkę WordPressa i callback PHP, zamiast zakładać, że sam plik na serwerze jest już dostępny w przeglądarce.

Jeśli potrzebujesz wykonawcy do pracy nad motywem lub funkcją, rozwój stron firmowych w WordPressie obejmuje wdrożenia i poprawki dopasowane do działania witryny.

• WordPress localization: lokalizacja motywu i wtyczek krok po kroku
• Jak przenieść WordPressa z komputera localhost na serwer krok po kroku
• Ajax Search Lite w WordPress: konfiguracja, wyniki i typowe problemy
• LocalWP Live Link: jak udostępnić lokalną stronę WordPress