`wp_enqueue_script / wp_enqueue_style` în WordPress

Conținut și tipuri de date WordPress 2.1

Adaugă fișiere JavaScript și CSS în pagină, cu dependențe, versiune și încărcare defer/async (din WordPress 6.3).

Sintaxă

wp_enqueue_script( string $handle, string $src = '', string[] $deps = array(), string|bool|null $ver = false, array|bool $args = array() )
wp_enqueue_style( string $handle, string $src = '', string[] $deps = array(), string|bool|null $ver = false, string $media = 'all' )
wp_register_script( string $handle, string|false $src, string[] $deps = array(), string|bool|null $ver = false, array|bool $args = array() ): bool

Ce face `wp_enqueue_script / wp_enqueue_style`

Scripturile și foile de stil nu se pun cu <script> scris de mână în header.php, ci se înscriu cu wp_enqueue_script() (din WordPress 2.1) și wp_enqueue_style() (din WordPress 2.6), pe hook-ul wp_enqueue_scripts. WordPress le tipărește o singură dată, în ordinea dependențelor ($deps), și adaugă ?ver= la adresă ca browserul să ia versiunea nouă după o modificare.

wp_register_script() doar înregistrează scriptul sub un nume ($handle), fără să-l încarce; îl încarci mai târziu cu wp_enqueue_script( 'nume' ) sau automat, când alt script îl are ca dependență. Dacă $ver este false se pune versiunea WordPress; cu null nu se adaugă nicio versiune.

Din WordPress 6.3, ultimul parametru al funcțiilor pentru scripturi poate fi un tablou $args: in_footer (scriptul se tipărește în subsol) și strategy cu valoarea 'defer' sau 'async'. WordPress poate alege altă strategie dacă dependențele o cer. În WordPress 6.9 s-a adăugat cheia fetchpriority, iar în 7.0 module_dependencies. Înainte de 6.3, al cincilea parametru era doar un boolean $in_footer.

Parametri

Parametru	Descriere
`$handle`	Numele unic al scriptului sau stilului (de exemplu `'dex-meniu'`).
`$src`	Adresa completă a fișierului sau calea relativă la rădăcina WordPress. Pentru tema copil: `get_stylesheet_directory_uri() . '/js/meniu.js'`.
`$deps`	Tablou cu numele scripturilor/stilurilor înregistrate de care depinde (de exemplu `array( 'jquery' )`).
`$ver`	Versiunea adăugată ca `?ver=`; `false` = versiunea WordPress, `null` = fără versiune.
`$args`	Scripturi: tablou cu `strategy` (`'defer'` / `'async'`), `in_footer`, `fetchpriority`; sau un boolean pentru subsol.
`$media`	Stiluri: pentru ce media se aplică (`'all'` implicit, `'print'`, `'(max-width: 640px)'`).

Ce returnează

wp_enqueue_script() și wp_enqueue_style() nu întorc nimic. wp_register_script() întoarce true dacă scriptul a fost înregistrat, false altfel.

Exemple

Exemplul 1: Stil și script cu defer în tema copil

Rezultatul este din WordPress 6.9, cu o temă care declară suport HTML5 pentru script și style: stilul apare în <head>, scriptul în subsol, cu atributul defer.

<?php
add_action( 'wp_enqueue_scripts', 'dex_incarca_resurse' );

function dex_incarca_resurse() {
    wp_enqueue_style(
        'dex-stil',
        get_stylesheet_directory_uri() . '/css/stil.css',
        array(),
        '1.0.0'
    );

    wp_enqueue_script(
        'dex-meniu',
        get_stylesheet_directory_uri() . '/js/meniu.js',
        array(),
        '1.2.0',
        array(
            'in_footer' => true,
            'strategy'  => 'defer',
        )
    );
}

Ce afișează pagina

<link rel='stylesheet' id='dex-stil-css' href='https://exemplu.ro/wp-content/themes/dex-copil/css/stil.css?ver=1.0.0' media='all' />
<script src="https://exemplu.ro/wp-content/themes/dex-copil/js/meniu.js?ver=1.2.0" id="dex-meniu-js" defer data-wp-strategy="defer"></script>

Exemplul 2: Script înregistrat, încărcat doar pe pagina de contact

Înregistrarea se face peste tot, dar fișierul se încarcă doar unde e nevoie; filemtime() schimbă versiunea la fiecare modificare a fișierului. Rezultatul apare doar pe pagina de contact, în <head> (WordPress 6.9, temă cu suport HTML5).

<?php
add_action( 'wp_enqueue_scripts', 'dex_script_contact' );

function dex_script_contact() {
    $cale = get_stylesheet_directory() . '/js/harta.js';

    wp_register_script(
        'dex-harta',
        get_stylesheet_directory_uri() . '/js/harta.js',
        array(),
        (string) filemtime( $cale ),
        array( 'strategy' => 'async' )
    );

    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'dex-harta' );
    }
}