wp_enqueue_script i wp_enqueue_style

wp_enqueue_script

wp_enqueue_script() to funkcja w WordPressie służąca do dołączania (ładowania) skryptów JavaScript w sposób zgodny z systemem kolejkowania WordPressa. Dzięki niej masz pełną kontrolę nad tym, kiedy i gdzie dany skrypt zostanie załadowany oraz jakie ma zależności (czyli inne skrypty, które muszą być załadowane przed nim).

function myTheme_scripts() {
    wp_enqueue_script(
        'my-custom-script', 
        get_template_directory_uri() . '/js/my-script.js', 
        array('jquery'), 
        '1.0.0', 
        true
    );
}
add_action('wp_enqueue_scripts', 'myTheme_scripts');

gdzie kolejno mamy:

• $handle – unikalna nazwa identyfikująca skrypt (np. 'my-custom-script’)
• $src – ścieżka do pliku JS (może być URL lub ścieżka względna użyta z get_template_directory_uri() lub get_stylesheet_directory_uri(), więcej zobacz tu)
• $deps – tablica zależności, np. array(’jquery’), tutaj skrypt zależy od jquery – więc jQuery zostanie załadowane wcześniej opcjonalna
• $ver – wersja skryptu (np. '1.0.0′), przydatna do czyszczenia cache, opcjonalna
• $in_footer – true, jeśli skrypt ma być załadowany w footer, false – w head, opcjonalna

ładowanie skryptu na konkretnej stronie

Jeśli potrzebujesz by dany skrypt był użyty tylko na konkretnej stronie, możesz użyć warunków WordPressa, np. is_page(), is_single(), is_front_page(), is_singular(), itd. i zamknąć kod wp_enqueue_script w if()

function my_conditional_script() {
    if (is_page(42)) {
        wp_enqueue_script(
            'custom-page-script',
            get_template_directory_uri() . '/js/page-script.js',
            array(),
            '1.0.0',
            true
        );
    }
}
add_action('wp_enqueue_scripts', 'my_conditional_script');

Rejestracja skryptu bez natychmiastowego ładowania

Gdy chcesz zarejestrować skrypt, ale załadować go dopiero później lub warunkowo, np. przez inną funkcję, wtyczkę, shortcode, AJAX itd użyj wp_register_script()

function my_register_script() {
    wp_register_script(
        'my-registered-script',
        get_template_directory_uri() . '/js/extra.js',
        array('jquery'),
        '1.2.2',
        true
    );
}
add_action('wp_enqueue_scripts', 'my_register_script');

Następnie, np. w innej funkcji używasz:

function load_extra_script_conditionally() {
    if (is_user_logged_in()) {
        wp_enqueue_script('my-registered-script');
    }
}
add_action('wp_enqueue_scripts', 'load_extra_script_conditionally');

Pro tip

• wp_enqueue_scripts – front-end
• admin_enqueue_scripts – panel admina
• enqueue_block_editor_assets – edytor bloków (Gutenberg)

wp_enqueue_style

wp_enqueue_style() to funkcja w WordPressie służąca do dołączania (ładowania) styli CSS w sposób zgodny z systemem kolejkowania WordPressa. Dzięki niej masz pełną kontrolę nad tym, kiedy i gdzie dane style zostaną załadowane oraz jakie mogą mieć zależności (czyli inne style, które muszą być załadowane przed nimi).

function myTheme_style() {
    wp_enqueue_style(
        'my-custom-style', 
        get_template_directory_uri() . '/css/my-style.js', 
        array('bootstrap'), 
        '1.0.0', 
        'all'
    );
}
add_action('wp_enqueue_style', 'myTheme_style');

i tu kolejno mamy:

• $handle – unikalna nazwa identyfikująca styli (np. 'my-custom-style’)
• $src – ścieżka do pliku CSS i tu może być get_stylesheet_uri() -> czyli style.css z motywu głównego lub get_template_directory_uri() . '/css/custom.css’ -> ścieżka do konkretnego pliku css
• $deps – tablica zależności, np. array(’bootstrap’), tutaj styl zależy od bootstrap – więc bootstrap zostanie załadowane wcześniej, opcjonalna
• $ver – wersja styli (np. '1.0.0′), przydatna do czyszczenia cache, opcjonalna
• $media – typ mediów – domyślnie 'all’ (inne: 'screen’, 'print’, itd.), opcjonalna

rejestracja styli i późniejsze uruchomienie, czy załadowanie styli tylko na konkretnej stronie czy szablonie odbywa się dokładnie tak samo jak w przypadku skryptów js.

Ważne!: Do motywów potomnych (child themes) używaj get_stylesheet_directory_uri() zamiast get_template_directory_uri(), żeby mieć poprawną ścieżkę.

Ładowanie CSS tylko w panelu admina

Do tego służy admin_enqueue_scripts

function my_admin_styles() {
    wp_enqueue_style(
        'my-admin-style',
        get_template_directory_uri() . '/admin/css/admin-style.css',
        array(),
        '1.0.0'
    );
}
add_action('admin_enqueue_scripts', 'my_admin_styles');

Ładowanie styli tylko na konkretnej stronie admina

Czasami chcesz załadować style tylko np. na stronie edycji posta, lub na własnej stronie ustawień – żeby nie obciążać całego panelu.
Do sprawdzenia na jakiej stronie jesteś służy zmienna $hook_suffix, którą WordPress przekazuje do hooka, np.:

$hook === 'post.php’
$hook === 'post-new.php’
$hook === 'toplevel_page_my-plugin-settings’ – własna strona admina dodana przez add_menu_page()

Jak znaleźć wartość $hook?

Możesz wykorzystać funkcję error_log($hook); i następnie sprawdzić w pliku debug.log, jaka nazwa się pojawia dla danej strony w panelu.

function my_admin_styles_targeted($hook) {
    if ($hook === 'post.php' || $hook === 'post-new.php') {
        wp_enqueue_style(
            'my-post-admin-style',
            get_template_directory_uri() . '/admin/css/post-edit.css',
            array(),
            '1.0.0'
        );
    }
}
add_action('admin_enqueue_scripts', 'my_admin_styles_targeted');

WAŻNE!: $scr w przypadku własnego plugina: plugin_dir_url(__FILE__) . 'admin/style.css’

Ładowanie strony

Gdy używasz w kodzie wp_enqueue_style(’main-style’, get_stylesheet_uri()); WordPress generuje w head standardowy link do CSS link rel=”stylesheet”, co przy dużych plikach blokuje renderowanie strony, ponieważ przeglądarka renderuje stronę „od góry do dołu”.

Gdy napotka link rel=”stylesheet”, zatrzymuje renderowanie strony i czeka, aż ten plik CSS zostanie pobrany i sparsowany.

Dzieje się tak, bo CSS może zmienić wygląd elementów HTML. Gdyby przeglądarka renderowała stronę dalej bez CSS, użytkownik zobaczyłby „miganie stylów” (FOUT – Flash of Unstyled Text).
Blokowanie renderowania jest świadome — chodzi o to, żeby użytkownik nie zobaczył nieostylowanej strony.