Asennat lisäosan ja se tuo mukanaan oman kopionsa jQuerysta. Teemasi latasi jo jQueryn wp_enqueue_script-funktiolla. Lisäosa lataa sen vielä kerran suoraan CDN:stä. Sivulla on kaksi tai jopa kolme versiota samasta kirjastosta. Ristiriitoja, turvonnut koko, arvaamatonta toimintaa.

Ongelma on yhtä vanha kuin WordPress itse, mutta sitä tapahtuu yhä: kehittäjät kopioivat <script src="jquery.js">-rivin header.php-tiedostoon, "koska se on nopeampaa". Nopeampaa siihen asti, kunnes tulee ensimmäinen ristiriita lisäosan kanssa, joka odottaa natiivia WP-versiota.

Vuonna 2026 WordPress toimittaa jQuery 3.6.0:n vakiona ja tarjoaa yksinkertaisen, deterministisen tavan sisällyttää se ilman päällekkäisyyksiä ja ilman versioiden manuaalista seuraamista. Alla on ainoa oikea lähestymistapa, perustason wp_enqueue_script-kutsusta aina sen turvalliseen korvaamiseen CDN-versiolla ja noConflict-tilan käyttöön.

💡 Pikaopas:

• Miten WordPress jo lataa jQueryn ja miksi sinun ei pitäisi tehdä sitä manuaalisesti
• wp_enqueue_script ja jquery-riippuvuus: yksi rivi functions.php-tiedostossa
• Milloin ja miten sisäänrakennettu jQuery korvataan turvallisesti CDN-versiolla (Google / cdnjs)
• noConflict-tila: suoja törmäyksiä vastaan muiden kirjastojen kanssa
• Vinkkejä teemoille ja lisäosille: milloin sisäänrakennettua jQuerya EI pidä korvata

JQuery on jo ytimessä: mitä WordPress tekee puolestasi

Versiosta 3.6 alkaen WordPress rekisteröi jQueryn kahvalla jquery. Sinun ei tarvitse ladata jquery.min.js-tiedostoa, sijoittaa sitä teemakansioosi ja sisällyttää sitä <script>-tagilla. Ydin tekee tämän automaattisesti heti, kun määrität jquery-riippuvuuden skriptillesi.

WordPress-ytimen nykyinen jQuery-versio on 3.6.0. Sen mukana tulee jQuery Migrate (taaksepäin yhteensopivuutta varten vanhan koodin kanssa), ja se latautuu vain, kun jokin skripti ilmoittaa jquery-riippuvuuden. Jos riippuvuuksia ei ole, jQuery ei ilmesty sivulle, eikä sivusto lataa turhia resursseja.

Tästä syystä suora <script src="/wp-content/themes/mytime/jquery.js"> header.php-tiedostossa on virhe, ei oikotie. Ohitat riippuvuusjärjestelmän, poistat WP:n kyvyn hallita latausjärjestystä ja saat päällekkäisyyden, kun jokin lisäosa pyytää jQuerya asianmukaisesti wp_enqueue_script-funktiolla.

Oikea tapa: wp_enqueue_script ja riippuvuus

Perusmekaniikka mahtuu yhteen riviin wp_enqueue_scripts-koukun sisällä. Kirjoitat skriptisi, ja WordPress selvittää, milloin ja missä järjestyksessä kaikki ladataan.

Luo (tai avaa) teemasi functions.php ja lisää:

1
function mytheme_enqueue_scripts() {
2
    wp_enqueue_script(
3
        'mytheme-main',
4
        get_template_directory_uri() . '/js/main.js',
5
        array( 'jquery' ),
6
        '1.0.0',
7
        array(
8
            'strategy'  => 'defer',
9
            'in_footer' => true,
10
        )
11
    );
12
}
13
add_action( 'wp_enqueue_scripts', 'mytheme_enqueue_scripts' );

Mitä tässä tapahtuu:

• mytheme-main on skriptisi yksilöllinen kahva. Keksi omasi, etuliitteenä teeman nimi.
• get_template_directory_uri() . '/js/main.js' on tiedoston polku. Voit käyttää myös ulkoista CDN-osoitetta.
• array( 'jquery' ) on avainkohta: kerrot WP:lle "skriptini riippuu jQuerysta". Ydin näkee tämän ja asettaa jQueryn automaattisesti jonoon ennen skriptiäsi. Ei <script>-tageja templaatissa.
• '1.0.0' on versio välimuistin ohitusta varten. Vaihda se jokaisen skriptipäivityksen yhteydessä.
• array( 'strategy' => 'defer', 'in_footer' => true ): WordPress 6.3:sta alkaen $args-parametri hyväksyy taulukon. defer tarkoittaa "suorita skripti DOMin rakentamisen jälkeen mutta ennen DOMContentLoaded-tapahtumaa". in_footer sijoittaa skriptin alatunnisteeseen.

Vanha syntaksi, jossa viides parametri on totuusarvo (true = alatunnisteeseen), toimii yhä, mutta uusissa projekteissa käytä taulukkosyntaksia. Se on luettavampi ja antaa hallinnan async/defer-määrityksiin.

Varmista, että teemasi kutsuu wp_head()-funktiota ennen sulkevaa </head>-tagia ja wp_footer()-funktiota ennen </body>-tagia. Ilman näitä kutsuja wp_enqueue_script ei yksinkertaisesti toimi. Tämä on yleinen ansa siirryttäessä pois ikivanhoista teemoista.

Miten sisäänrakennettu jQuery korvataan omalla versiolla

Joskus natiiviversio ei riitä. Haluat jQuery 4.0.0:n CDN:stä uusimpien korjausten vuoksi, tai tarvitset tietyn version yhteensopivuuteen vanhan lisäosan kanssa. Voit korvata sen, mutta varovasti.

Virhe: kutsutaan suoraan wp_enqueue_script('jquery', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js'). WordPress EI ylikirjoita jo rekisteröityä kahvaa. Saat sekä natiiviversion ETTÄ CDN-version samalle sivulle.

Oikea järjestys: ensin poistetaan natiivin jquery-kahvan rekisteröinti, sitten rekisteröidään oma:

1
function mytheme_use_cdn_jquery() {
2
    // Deregister the built-in jQuery
3
    wp_deregister_script( 'jquery' );
4
 
5
    // Register your own — from CDN
6
    wp_register_script(
7
        'jquery',
8
        'https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js',
9
        array(),
10
        '4.0.0',
11
        true
12
    );
13
 
14
    // Enqueue it
15
    wp_enqueue_script( 'jquery' );
16
}
17
add_action( 'wp_enqueue_scripts', 'mytheme_use_cdn_jquery' );

Kolme usein huomiotta jäävää seikkaa:

Googlen Hosted Libraries. Googlen vaihtoehtoinen CDN on yhä toiminnassa ja tarjoaa jQuery 3.7.1:n: https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js. Hyöty: miljoonat sivustot ovat jo lämmittäneet selainvälimuistit tälle osoitteelle. Haitta: Google lisää omat otsakkeensa eikä päivitä versioita heti julkaisun jälkeen.

cdnjs. Jos tarvitset jQuery 4.0.0:n, hae se osoitteesta cdn.jsdelivr.net/npm/[email protected]/. cdnjs peilaa npm-paketin ja tarjoilee sen asianmukaisilla CORS-otsakkeilla.

Älä poista jQueryn rekisteröintiä julkisissa teemoissa. Jos teemasi on menossa WordPress.orgin tietovarastoon, käytä ytimen natiivia jQuerya. Syy on yksinkertainen: kun sivustolla on sekä teema (jossa CDN-jQuery 4.0.0) että lisäosa (joka odottaa jQuery 3.6.0:aa ytimestä), käyttäjä ratkaisee ristiriidan, ei kehittäjä. Kaupallisissa teemoissa ja räätälöidyissä projekteissa voit vapaasti korvata sen.

NoConflict-tila: kun sivulla on useampi kuin yksi kirjasto

Oletuksena jQuery varaa globaalin muuttujan $. Ongelma on, että $ on suosittu nimi: Prototype, MooTools ja jotkin vanhat kehykset käyttävät sitä myös. Jos lisäosa tai toinen skripti myös vaatii $-muuttujaa, viimeisenä latautunut voittaa, ja muut hajoavat.

Suoja yhdellä rivillä skriptisi alussa:

1
var $j = jQuery.noConflict();

Tämän jälkeen $ on vapautettu muille kirjastoille, ja koodisi toimii $j-muuttujan kautta. Täysi esimerkki: sivupalkki, jossa on hover-animaatio:

1
jQuery(document).ready( function( $ ) {
2
    // Here $ is jQuery, but only inside this function
3
    $( '#sidebar li a' ).hover(
4
        function() {
5
            $( this ).stop().animate( { paddingLeft: '20px' }, 400 );
6
        },
7
        function() {
8
            $( this ).stop().animate( { paddingLeft: '0' }, 400 );
9
        }
10
    );
11
} );

Tässä $ toimii jQueryna jQuery(document).ready()-sulkeuman sisällä, ja sen ulkopuolella se on vapaa muille. Tämä on siistimpää kuin $j-, $jq- ja $myJQ-muuttujien viljely ympäri koodia.

Milloin noConflictia ei tarvita: jos sivustosi pyörii kokonaan WordPressillä ilman kolmannen osapuolen JS-kehyksiä ja kaikki lisäosat on kirjoitettu wp_enqueue_scriptille, $ on turvallinen. Mutta noConflictin sisällyttäminen teemasi vakiopohjaan on hyvä tapa, joka maksaa vain yhden rivin.

Mitä lisäosakehittäjien tulisi tehdä

Jos kirjoitat lisäosaa julkiseen jakeluun, käytä vain wp_enqueue_scriptiä ja jquery-riippuvuutta. Ei wp_deregister_script('jquery')-kutsua lisäosien sisällä: et tiedä, mitä jQuery-versiota muut saman sivuston lisäosat odottavat.

Oikea malli lisäosalle näyttää tältä:

1
function myplugin_frontend_scripts() {
2
    wp_enqueue_script(
3
        'myplugin-frontend',
4
        plugins_url( '/js/frontend.js', __FILE__ ),
5
        array( 'jquery' ),
6
        MYPLUGIN_VERSION,
7
        true
8
    );
9
}
10
add_action( 'wp_enqueue_scripts', 'myplugin_frontend_scripts' );

MYPLUGIN_VERSION on lisäosan versiovakio. Jokaisen lisäosapäivityksen yhteydessä käyttäjän selain saa tuoreen skriptin vanhan välimuistissa olevan sijaan.

Ylläpidon skripteille (vain hallintapaneeli) käytä admin_enqueue_scripts-koukkua. jQuery ylläpidossa on myös rekisteröity samalla jquery-kahvalla.

⁉️🤔 Usein kysytyt kysymykset

Miksi jQuery-koodini ei toimi, vaikka wp_enqueue_script on kutsuttu oikein?

Yleisin syy: teema ei kutsu wp_head()- ja wp_footer()-funktioita. Ilman näitä funktioita WordPress ei fyysisesti pysty lisäämään <script>-tageja HTML:ään. Avaa header.php. Siellä pitäisi olla <?php wp_head(); ?> ennen </head>-tagia. footer.php-tiedostossa pitäisi olla <?php wp_footer(); ?> ennen </body>-tagia. Jos teema on ikivanha ja nämä kutsut puuttuvat, lisää ne. Tämä on turvallista. Kaikki modernit teemat ja lisäosat nojaavat wp_head/wp_footer-funktioihin. Ilman niitä ei ainoastaan skriptien lataus ole rikki, vaan myös SEO-lisäosat, fontit ja rakenteinen data.

Voinko käyttää jQuery 4.0.0:aa WordPressissä, jos ydin toimittaa version 3.6.0?

Kyllä, wp_deregister_script + wp_register_script -yhdistelmällä (katso yllä oleva osio). Mutta huomioi: jQuery 4.0.0 pudotti IE 11 -tuen ja useita vanhentuneita metodeja. Jos sivustosi tai lisäosasi nojaa jQuery Migrateen, pysy ydinversiossa tai sisällytä Migrate erikseen. WordPress on vähitellen siirtymässä natiiviin JavaScriptiin ja Reactiin lohkoeditorissa, mutta jQuery pysyy ytimessä pitkään: liian monet teemat ja lisäosat riippuvat siitä.

Lisäosa lataa oman jQuerynsa, vaikka sisällytin sen jo functions.php:n kautta. Mitä teen?

Lisäosa todennäköisesti kovakoodasi <script src="jquery...">-tagin ohittaen wp_enqueue_script-funktion. Tämä on lisäosan virhe. Kaksi ratkaisua: etsi suora kutsu lisäosan koodista ja korvaa se wp_enqueue_script-kutsulla ja riippuvuudella (jos olet valmis paikkaamaan lisäosaa), tai ota yhteyttä lisäosan tekijään ja pyydä häntä korjaamaan se. Väliaikaisena kiertotienä voit kutsua wp_dequeue_script-funktiota tai poistaa lisäosan koukun, mutta tämä hoitaa oireita eikä syytä.

Kumpi on nopeampi: jQuery WordPress-ytimestä vai CDN:stä?

Jos käyttäjän selain on jo välimuistittanut jQueryn CDN:stä (Google tai cdnjs), CDN-versio latautuu välittömästi 304 Not Modified -koodilla. Jos ei, latausnopeusero ytimen ja CDN:n välillä on merkityksetön jQueryn kohdalla (noin 85 KB gzipattuna). Paljon liikennettä saavissa projekteissa CDN säästää palvelimesi kaistaa; tyypilliselle WordPress-sivustolle eroa ei ole.

Pitäisikö jQuery hylätä natiivin JS:n hyväksi

Lyhyt vastaus: riippuu projektista. Pakattu jQuery 4.0.0 painaa noin 85 KB. Se ei ole nolla, mutta ei myöskään syy paniikkiin. Moderni natiivi JS (querySelectorAll, fetch ja classList) kattaa 90% siitä, mihin jQuerya tarvittiin vuonna 2015. Jos rakennat uutta teemaa tyhjästä etkä ole riippuvainen jQuery-lisäosista, harkitse vanilla JS:ää. Se on siistimpää ja nopeampaa.

Mutta jos projektissa on jo jQuery-riippuvuuksia (liukusäätimiä, gallerioita, lisäosien käyttöliittymäkomponentteja), älä monimutkaista asioita. WordPress lataa jQueryn joka tapauksessa, kun jokin lisäosa sitä pyytää. Kirjoita siistejä wp_enqueue_script-kutsuja riippuvuuksineen, älä sekaannu ytimen latausjärjestyksen hallintaan, ja jQuery toimii nopeasti ja ennustettavasti.

🔗 wp_enqueue_script-dokumentaatio | 🔗 wp_deregister_script-dokumentaatio