🛠 Wp_enqueue_script: miten lisätä JavaScript WordPress-teemaan oikein, ilman ristiriitoja

Q: Miten wp_register_script eroaa wp_enqueue_scriptistä?

wp_register_script ainoastaan rekisteröi skriptin järjestelmään (asettaa kahvan, polun, riippuvuudet), mutta ei tulosta tagia sivulle. wp_enqueue_script rekisteröi JA asettaa välittömästi jonoon tulostusta varten. Erottelu on hyödyllinen, kun skriptiä ei aina tarvita: rekisteröi kerran functions.php-tiedostossa ja kutsu wp_enqueue_script('my-handle') vain tarvittavilla sivuilla.

Q: Mitä teen, jos skriptit lakkaavat toimimasta teemapäivityksen jälkeen?

Todennäköisesti päivitys ylikirjoitti functions.php-tiedostosi. Ratkaisu on lapsiteema: luo sellainen, siirrä funktiosi sinne ja aktivoi se. Tämän jälkeen ylätason teeman päivitykset jättävät koodisi koskemattomaksi.

Q: Mitä virhe "$ is not defined" tarkoittaa jQueryä käytettäessä?

WordPress lataa jQueryn noConflict-tilassa, $-muuttujaa ei ole varattu jQuerylle ristiriitojen välttämiseksi muiden kirjastojen kanssa. Käytä täyttä nimeä jQuery $-merkin sijaan tai kääri koodi itsekutsuvaksi funktioksi: (function($) { ... })(jQuery);.

WordPressisi WordPress-galleria lakkasi toimimasta päivityksen jälkeen. Kuulostaako tutulta?

Lähes aina syynä on JavaScript, joka on linkitetty suoraan header.php-tiedostoon ilman koukkuja, ilman riippuvuuksia ja huomioimatta sitä, että välimuistilisäosa voi sekoittaa latausjärjestyksen. Yksi lisäosa lataa jQueryn, toinen lataa oman versionsa jQuerystä, ja skriptisi jää niiden väliin ja kaatuu virheeseen $ is not defined.

Käytännössä yksi wp_enqueue_script-kutsu oikeassa paikassa riittää, jotta konfliktit voi unohtaa lopullisesti. Alla on täydellinen erittely: aloittelijan virheistä defer/async-strategioihin ja hienosäätömahdollisuuksiin, jotka ilmestyivät WordPress 6.6:ssa.

💡 Pikaopas:

Älä lisää script-tageja suoraan header.php- tai footer.php-tiedostoon: tämä aiheuttaa ristiriitoja lisäosien kanssa ja rikkoo lapsiteemat
Lisää JavaScript jonoon wp_enqueue_script-funktiolla functions.php-tiedostossa wp_enqueue_scripts-koukun avulla: WordPress sijoittaa tagit head-osioon tai ennen /body-elementtiä itse
Lyhyelle inline-koodille käytä wp_add_inline_script-funktiota, älä paljasta script-tagia: säilyttää suoritusjärjestyksen ja antaa lisäosille mahdollisuuden käsitellä koodia
WordPress 6.3+:ssa määritä defer- tai async-strategia suoraan kutsun parametreissa, ja 6.6:sta alkaen myös fetchpriority
Poista kolmannen osapuolen skriptejä jonosta wp_dequeue_script-funktiolla, jos lisäosa hidastaa sivustoasi: koukun prioriteetti ratkaisee

Miten JavaScript lisätään väärin WordPressiin

Tyypillinen skenaario: sinun täytyy ladata custom.js-tiedostosi, ja kehittäjä lisää tämän rivin header.php-tiedostoon:

1 <script src="<?php echo get_template_directory_uri(); ?>/js/custom.js"></script>

Vaikuttaa toimivan. Mutta tämä lähestymistapa luo kolme ongelmaa.

Ristiriidat lisäosien kanssa. Välimuistilisäosa yhdistää skriptejä eri järjestyksessä, minifiointilisäosa nimeää tiedoston uudelleen ja rikkoo polun. Jos toinen lisäosa on jo ladannut jQueryn ja sinä lataat sen uudelleen, seurauksena on kaksoislataus ja konsolivirheet.

Ei voi ohittaa lapsiteeman kautta. Lapsiteemaa käytettäessä header.php-tiedostoa kopioidaan harvoin. Jos skripti on kovakoodattu ylätason header.php-tiedostoon, lapsiteema ei voi poistaa sitä jonosta tai korvata sitä kopioimatta koko tiedostoa, ja tämä tarkoittaa, että muokkaukset katoavat, kun ylätason teema päivittyy.

Ei riippuvuuksia. Selain lataa skriptisi ennen jQueryä, ja saat virheen $ is not defined. Skripti latautuu kaikilla sivuilla, myös siellä missä sitä ei tarvita, ja ylimääräiset pyynnöt hidastavat sivustoa.

Oikea tapa: wp_enqueue_script

WordPress tarjoaa jonotusjärjestelmän skripteille ja tyyleille. Et lisää <script>-elementtiä manuaalisesti, vaan rekisteröit skriptin PHP:n kautta, määrität riippuvuudet ja latauspaikan. WordPress sijoittaa tagit <head>-osioon tai ennen </body>-elementtiä itse.

Minimaalinen toimiva esimerkki teemasi functions.php-tiedostoon:

1 /**
2  * Enqueue the main theme script.
3  */
4 function mytheme_enqueue_scripts() {
5     wp_enqueue_script(
6         'mytheme-main',                                     // $handle — unique name
7         get_template_directory_uri() . '/js/main.js',       // $src — file path
8         array( 'jquery' ),                                  // $deps — dependencies
9         '1.0.0',                                            // $ver — version for cache busting
10         true                                                // $in_footer — load in footer
11     );
12 }
13 add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

wp_enqueue_script-funktio hyväksyy viisi parametria. $handle, yksilöllinen tunniste: jos toinen lisäosa on jo rekisteröinyt skriptin samalla kahvalla, päällekkäistä latausta ei tapahdu. $deps, taulukko kahvan riippuvuuksista: WordPress lataa vaaditut skriptit ennen omaasi. $in_footer arvolla true sijoittaa <script>-tagin ennen </body>-elementtiä, mikä nopeuttaa sivun renderöintiä.

Huom: get_template_directory_uri() osoittaa ylätason teemakansioon. Lapsiteemassa käytä get_stylesheet_directory_uri()-funktiota, URL osoittaa lapsikansioon, eikä skriptisi katoa, kun ylätason teema päivittyy.

Latausstrategiat: defer, async ja fetchpriority

WordPress 6.3:sta alkaen $args-parametri hyväksyy taulukon lisäasetuksilla:

1 wp_enqueue_script(
2     'mytheme-main',
3     get_template_directory_uri() . '/js/main.js',
4     array( 'jquery' ),
5     '1.0.0',
6     array(
7         'in_footer' => true,
8         'strategy'  => 'defer',
9     )
10 );

defer-strategia kertoo selaimelle: "lataa skripti rinnakkain, suorita DOM-rakenteen valmistuttua". Suoritusjärjestys on taattu, defer-skriptit suoritetaan siinä järjestyksessä kuin ne lisättiin DOMiin. async-strategia tarkoittaa "suorita heti kun ladattu", järjestystä ei taata. Teemaskripteille, jotka riippuvat DOMista, valitse defer.

WordPress 6.6:sta alkaen $args-taulukko sai kaksi parametria lisää. fetchpriority ohjaa latauksen prioriteettia ('high' tai 'low'), hyödyllinen kriittisille skripteille, joiden tulisi latautua ennen muita. module_dependencies hyväksyy taulukon moduulitunnisteita dynaamista importia varten, tämä on edistyneitä skenaarioita varten ES-moduulien kanssa. Tärkeää: kun määrität module_dependencies-parametrin, skriptin on latauduttava footerissa (in_footer => true) tai defer-strategialla, muuten moduulin tuontikartta ei ole valmis, kun skripti suoritetaan.

Mitä skriptejä WordPressissä on jo valmiina

WordPress rekisteröi kymmeniä JavaScript-kirjastoja valmiiksi: jQuery, jQuery UI, Backbone, wp-api, MediaElement.js ja muita. Täydellinen lista virallisessa dokumentaatiossa.

Pääsääntö: älä koskaan lataa jQueryä CDN:stä, kuten Googlesta tai cdnjs-palvelusta, jos teemasi toimii WordPress-ekosysteemissä. WordPress itse tarjoaa jQueryn kahvalla jquery. Käyttääksesi sitä, määritä vain array( 'jquery' ) riippuvuuksissa, WordPress lataa oman versionsa, joka on testattu yhteensopivaksi koko ytimen kanssa.

Voit tarkistaa, onko kirjasto rekisteröity wp_script_is()-funktiolla:

1 if ( wp_script_is( 'jquery-ui-datepicker', 'registered' ) ) {
2     // Library is available — just add to $deps
3 }

Wp_enqueue_scripts-koukun käyttäminen

wp_enqueue_scripts-koukku laukeaa julkisella puolella. Tähän wp_enqueue_script-kutsut kääritään. Älä kutsu funktiota suoraan functions.php-tiedoston rungossa ilman koukkua, skripti saattaa latautua ennen kuin WordPress rekisteröi järjestelmäkirjastot.

Hallinta-aluetta varten käytä erillistä koukkua:

1 add_action( 'admin_enqueue_scripts', 'mytheme_admin_scripts' );
2 function mytheme_admin_scripts( $hook_suffix ) {
3     // $hook_suffix contains the current admin page
4     if ( 'post.php' !== $hook_suffix ) {
5         return; // load script only on the post edit page
6     }
7     wp_enqueue_script( 'mytheme-admin', get_template_directory_uri() . '/js/admin.js', array(), '1.0', true );
8 }

Ehdollinen lataaminen säästää resursseja: asetussivun skriptin ei tulisi latautua kaikilla hallintasivuilla. WordPress välittää $hook_suffix-parametrin automaattisesti, käytä sitä.

Jos skriptiä tarvitaan sekä julkisella puolella että hallinnassa, koukuta yksi funktio molempiin:

1 add_action( 'wp_enqueue_scripts', 'mytheme_global_scripts' );
2 add_action( 'admin_enqueue_scripts', 'mytheme_global_scripts' );

Inline-JavaScriptin lisääminen: wp_add_inline_script

Kaikkea koodia ei kannata laittaa erilliseen tiedostoon. Lyhyille pätkille, laskureille, konfiguraatiomuuttujille, nopeille käsittelijöille WordPress tarjoaa wp_add_inline_script-funktion:

1 function mytheme_inline_config() {
2     wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/js/main.js', array(), '1.0', true );
3     wp_add_inline_script(
4         'mytheme-main',
5         'const MYTHEME_AJAX_URL = "' . admin_url( 'admin-ajax.php' ) . '";',
6         'before'
7     );
8 }
9 add_action( 'wp_enqueue_scripts', 'mytheme_inline_config' );

Kolmas parametri, 'before' tai 'after', määrittää, lisätäänkö koodi ennen määritettyä skriptiä vai sen jälkeen. Tämä on kätevää PHP-muuttujien välittämiseen JavaScriptille: AJAX-käsittelijän URL, tietoturva-avain (nonce), nykyisen artikkelin ID.

Tärkeä yksityiskohta: wp_add_inline_script toimii vain rekisteröidyn skriptin kanssa. Jos välität kahvan, joka ei ole jonossa, koodia ei tulosteta. Joten ensin wp_enqueue_script, sitten wp_add_inline_script.

Vaihtoehto lapsiteemoille: wp_head ja wp_footer

Jos työskentelet lapsiteemassa etkä halua luoda erillistä tiedostoa, voit tulostaa koodia suoraan wp_head- (<head>-osiossa) tai wp_footer-koukkujen (ennen </body>-elementtiä) kautta:

1 add_action( 'wp_footer', function() { ?>
2     <script>
3         ( function( $ ) {
4             'use strict';
5             $( function() {
6                 // Your code here — DOM is already ready
7             } );
8         } ( jQuery ) );
9     </script>
10 <?php } );

Tämä menetelmä on lyhyempi mutta vähemmän joustava kuin wp_enqueue_script: ei riippuvuuksia, versiointia tai mahdollisuutta poistaa skriptiä jonosta lapsiteeman kautta. Käytä sitä pieniin korjauksiin, kun et halua luoda erillistä tiedostoa.

Miten poistaa jonosta lisäosan tai teeman lisäämä skripti

Joskus lisäosa lataa tarpeettoman skriptin kaikilla sivuilla ja hidastaa sivustoa. Voit poistaa sen wp_dequeue_script-funktiolla:

1 function mytheme_dequeue_plugin_scripts() {
2     if ( ! is_page( 'contacts' ) ) {
3         wp_dequeue_script( 'plugin-handle' );
4     }
5 }
6 add_action( 'wp_enqueue_scripts', 'mytheme_dequeue_plugin_scripts', 20 );

Prioriteetti 20 (add_action-funktion kolmas argumentti) sijoittaa funktiosi lisäosan rekisteröinnin jälkeen, muuten kahva ei ole vielä jonossa. Löydät skriptin kahvan selaimen konsolin kautta: avaa sivun lähdekoodi ja etsi id-attribuutti <script>-tagista, kahva vastaa yleensä id:tä ilman -js-päätettä.

Jos sinun täytyy korvata skripti kokonaan, poista ensin vanhan rekisteröinti wp_deregister_script-funktiolla ja rekisteröi sitten uusi:

1 function mytheme_replace_script() {
2     wp_deregister_script( 'old-handle' );
3     wp_enqueue_script( 'old-handle', get_template_directory_uri() . '/js/replacement.js', array(), '2.0', true );
4 }
5 add_action( 'wp_enqueue_scripts', 'mytheme_replace_script', 20 );

Ennen tällaisia toimenpiteitä tee täydellinen sivuston varmuuskopio. Lisäosien skriptien korvaaminen on suora tie rikkinäiseen toiminnallisuuteen, jos et testaa staging-ympäristössä.

Yllä oleva video näyttää vaiheittaisen erittelyn CSS:n ja JavaScriptin jonottamisesta WordPress-teemassa wp_enqueue_script- ja wp_enqueue_style-funktioiden avulla. Jos olet uusi koukkujen parissa, aloita siitä ja palaa sitten tähän kirjalliseen oppaaseen yksityiskohtia varten.

⁉️🤔 Usein kysytyt kysymykset

Onko wp_enqueue_scriptin käyttö pakollista jokaiselle js-tiedostolle?

Käytännössä kyllä, kaikille globaalisti ladattaville skripteille. Skriptille, joka toimii vain yhdellä sivulla ja generoidaan dynaamisesti, on hyväksyttävää lisätä <script> suoraan mallipohjaan. Mutta heti kun sinulla on kaksi tai useampi skripti, wp_enqueue_script-jonotus säästää tunteja debuggausta.

Miten wp_register_script eroaa wp_enqueue_scriptistä?

wp_register_script ainoastaan rekisteröi skriptin järjestelmään (asettaa kahvan, polun, riippuvuudet), mutta ei tulosta tagia sivulle. wp_enqueue_script rekisteröi JA asettaa välittömästi jonoon tulostusta varten. Erottelu on hyödyllinen, kun skriptiä ei aina tarvita: rekisteröi kerran functions.php-tiedostossa ja kutsu wp_enqueue_script('my-handle') vain tarvittavilla sivuilla.

Voinko ladata skriptejä ulkoisesta CDN:stä?

Teknisesti kyllä, välitä täysi URL toisena parametrina. Mutta jQuerylle ja muille WordPressin ydinkirjastoille tämä on huono käytäntö: WordPress sisältää ne jo ja testaa yhteensopivuuden. Ulkoinen CDN on perusteltu kolmannen osapuolen palveluille, kuten Google Analytics, reCAPTCHA, chat-widgetit. Siellä määritä URL sellaisenaan.

Miten varmistan, että skripti todella latautui?

Avaa kehittäjätyökalut (F12), Network-välilehti, suodata JS:llä ja päivitä sivu. Tiedostosi tulisi olla listalla 200-tilakoodilla. Jos skripti puuttuu, tarkista, laukeaako wp_enqueue_scripts-koukku tällä sivulla ja että tiedostopolku on oikein. Debuggausta varten tulosta get_template_directory_uri() erikseen ja vertaa URL-osoitetta.

Mitä teen, jos skriptit lakkaavat toimimasta teemapäivityksen jälkeen?

Todennäköisesti päivitys ylikirjoitti functions.php-tiedostosi. Ratkaisu on lapsiteema: luo sellainen, siirrä funktiosi sinne ja aktivoi se. Tämän jälkeen ylätason teeman päivitykset jättävät koodisi koskemattomaksi.

Mitä virhe "$ is not defined" tarkoittaa jQueryä käytettäessä?

WordPress lataa jQueryn noConflict-tilassa, $-muuttujaa ei ole varattu jQuerylle ristiriitojen välttämiseksi muiden kirjastojen kanssa. Käytä täyttä nimeä jQuery $-merkin sijaan tai kääri koodi itsekutsuvaksi funktioksi: (function($) { ... })(jQuery);.

Kannattaako wp_enqueue_scriptin kanssa nähdä vaivaa parin skriptin takia?

Jos sivustollasi on useampi kuin yksi lisäosa, kannattaa. WordPressin skriptijono on suunniteltu niin, että yksi jQueryn suoraan lataava lisäosa rikkoo puolet sivustosta sillä hetkellä, kun asennat välimuistilisäosan. wp_enqueue_script eliminoi tämän koko ongelmaluokan.

Viiden tiedoston teemalle käytä wp_enqueue_script-funktiota. Yhdelle lyhyelle pätkälle tietyllä sivulla wp_add_inline_script tai wp_footer-koukku käy. Mutta heti kun sinulla on kaksi tai useampi skripti, palaa jonoon. Tunti oikeaoppiseen jonottamiseen nyt säästää illan debuggausta seuraavan WordPress-päivityksen jälkeen.

1	/**
2	* Enqueue the main theme script.
3	*/
4	function mytheme_enqueue_scripts() {
5	wp_enqueue_script(
6	'mytheme-main', // $handle — unique name
7	get_template_directory_uri() . '/js/main.js', // $src — file path
8	array( 'jquery' ), // $deps — dependencies
9	'1.0.0', // $ver — version for cache busting
10	true // $in_footer — load in footer
11	);
12	}
13	add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

1	wp_enqueue_script(
2	'mytheme-main',
3	get_template_directory_uri() . '/js/main.js',
4	array( 'jquery' ),
5	'1.0.0',
6	array(
7	'in_footer' => true,
8	'strategy' => 'defer',
9	)
10	);

1	if ( wp_script_is( 'jquery-ui-datepicker', 'registered' ) ) {
2	// Library is available — just add to $deps
3	}

1	add_action( 'admin_enqueue_scripts', 'mytheme_admin_scripts' );
2	function mytheme_admin_scripts( $hook_suffix ) {
3	// $hook_suffix contains the current admin page
4	if ( 'post.php' !== $hook_suffix ) {
5	return; // load script only on the post edit page
6	}
7	wp_enqueue_script( 'mytheme-admin', get_template_directory_uri() . '/js/admin.js', array(), '1.0', true );
8	}

1	function mytheme_inline_config() {
2	wp_enqueue_script( 'mytheme-main', get_template_directory_uri() . '/js/main.js', array(), '1.0', true );
3	wp_add_inline_script(
4	'mytheme-main',
5	'const MYTHEME_AJAX_URL = "' . admin_url( 'admin-ajax.php' ) . '";',
6	'before'
7	);
8	}
9	add_action( 'wp_enqueue_scripts', 'mytheme_inline_config' );

1	add_action( 'wp_footer', function() { ?>
2	<script>
3	( function( $ ) {
4	'use strict';
5	$( function() {
6	// Your code here — DOM is already ready
7	} );
8	} ( jQuery ) );
9	</script>
10	<?php } );

1	function mytheme_dequeue_plugin_scripts() {
2	if ( ! is_page( 'contacts' ) ) {
3	wp_dequeue_script( 'plugin-handle' );
4	}
5	}
6	add_action( 'wp_enqueue_scripts', 'mytheme_dequeue_plugin_scripts', 20 );

1	function mytheme_replace_script() {
2	wp_deregister_script( 'old-handle' );
3	wp_enqueue_script( 'old-handle', get_template_directory_uri() . '/js/replacement.js', array(), '2.0', true );
4	}
5	add_action( 'wp_enqueue_scripts', 'mytheme_replace_script', 20 );

Kaikki WordPressistä, web-kehityksestä — ja paljon muuta

🛠 Oikeaoppinen JavaScriptin lisääminen WordPress-teemoissa