Saarekkeet
Lohkosaarekkeiden avulla lohko voi käyttää tavallista Blockstudio-renderöintiputkea ja siirtää pyyntökohtaisen tulosteen pois alkuperäisestä HTML-vastauksesta.
Tästä on hyötyä, kun sivu halutaan tallentaa tehokkaasti välimuistiin, mutta jokin lohko riippuu edelleen nykyisestä kävijästä, istunnosta, ostoskorista, käyttöoikeuksista tai muusta ajantasaisesta pyyntökontekstista.
Blockstudio-lohkot ovat yhä dynaamisia WordPress-lohkoja. Saarekkeet eivät muuta niitä valmiiksi käännetyiksi staattisiksi HTML-lohkoiksi. Sen sijaan Blockstudio muuttaa sitä, mitä ensimmäisellä pyynnöllä renderöidään:
- Hydratut saarekkeet renderöivät tavallisen välimuistiystävällisen HTML-sisältönsä ja saavat käynnistystapahtuman
- Dynaamiset saarekkeet renderöivät ensin välimuistiystävällisen paikkamerkin ja hakevat sitten todellisen osan kävijän selaimesta
Tilat
Hydratut saarekkeet
Käytä hydrattua saareketta, kun palvelimen tuloste voidaan tallentaa turvallisesti välimuistiin ja lohko tarvitsee vain käyttöliittymän käynnistyssignaalin.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Koko lohkon HTML on mukana alkuperäisessä vastauksessa. Saarekeajonaikainen ympäristö ei tee siitä REST-pyyntöä. Se lähettää tapahtuman blockstudio:island:hydrate merkkiin, jotta käyttöliittymän koodi voi liittää siihen toiminnan.
Dynaamiset saarekkeet
Käytä dynaamista saareketta, kun todellinen lohkotuloste on renderöitävä kävijän pyyntökontekstissa.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Alkuperäinen vastaus sisältää vain paikkamerkin. Selain kokoaa kaikki valmiit dynaamiset saarekkeet yhdeksi pyynnöksi osoitteeseen:
POST /wp-json/blockstudio/v1/island/render
Päätepiste renderöi vain rekisteröidyt Blockstudio-lohkot, jotka ovat dynaamisia ja joille blockstudio.island.mode on asetettu arvoon dynamic.
Määritykset
island-arvo voi olla lyhyt muoto tai objekti.
{
"blockstudio": {
"island": true
}
}
true ja "hydrate" tarkoittavat molemmat hydrattua tilaa. "dynamic" tarkoittaa dynaamista tilaa.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Ominaisuus | Tyyppi | Oletusarvo | Kuvaus |
|---|---|---|---|
mode |
"hydrate" tai "dynamic" |
"hydrate" |
Saaritila. |
tag |
string |
"div" |
Merkkikääreen tunniste. |
attributes |
string[] |
kaikki lohkon attribuutit | Attribuuttien sallittujen arvojen luettelo dynaamisiin fragmenttipyyntöihin. |
placeholder |
string |
tunnistetaan automaattisesti | Suhteellinen paikkamerkkimallin polku. |
loading |
"eager" tai "visible" |
"eager" |
Milloin ajonaikaisen ympäristön pitäisi hakea dynaaminen saari. |
event |
string |
ei asetettu | Ikkunatapahtuman nimi, joka päivittää dynaamisen saaren. |
context |
boolean |
false |
Allekirjoita kyselyn kohteena olevan sivun artikkelin tunnus ja tyyppi ja palauta ne dynaamisille fragmenteille. |
cache |
boolean tai object |
false |
Valinnainen fragmentin välimuistikäytäntö. |
Sivun konteksti
Dynaamiset fragmentit renderöidään tavallisesti sivun kuoresta riippumatta. Ota sivun identiteetti käyttöön, jos lohkosi lukee sivukohtaisia asetuksia tai niihin liittyvää sisältöä:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Merkki sisältää kyselyn kohteena olevan sivun postId ja postType arvot kohdassa data-bs-island-context. Molemmat arvot allekirjoitetaan lohkon nimellä ja sallituilla attribuuteilla sivuston salaisuutta käyttäen. Niitä ei voi muuttaa tai lisätä pyyntöön allekirjoitusta mitätöimättä. Ajonaikainen ympäristö lähettää ne olemassa olevan erämuotoisen fragmenttipyynnön mukana myös näkyvyyden ja tapahtumien käynnistämissä päivityksissä. Tämä toimii myös kohteiden bs_render_block() ja bs_block() sekä lohkotunnisteiden kanssa.
Fragmenttia renderöitäessä $block['postId'], $block['postType'], get_the_ID() ja get_queried_object_id() viittaavat kyseiseen sivuun. WordPress-kysely ja artikkelien globaalit palautetaan renderöinnin jälkeen, myös silloin, kun renderöinti aiheuttaa poikkeuksen. Tämä on kyselyn kohteena oleva sivu, ei kyselysilmukan sisäinen kohde. Mielivaltaisia URL-parametreja ei toisteta eikä alkuperäistä pyyntöä URL palauteta. Käytä get_permalink($block['postId'])-kohdetta, kun tarvitset HTML-sivun kanonisen arvon URL. Arkistoissa ja renderöinneissä, joissa ei ole kyselyn kohteena olevaa artikkelia, sivun identiteettiä ei lähetetä.
Päätepiste tarkistaa, että sivu on edelleen olemassa, sen artikkelityyppi vastaa allekirjoitettua tyyppiä ja nykyinen kävijä voi lukea sen, ennen fragmentin välimuistin tarkistamista. Kelvollinen allekirjoitus ei ohita yksityisen artikkelin tai salasanan suojausta, saaren kelpoisuutta, attribuuttien sallittujen arvojen luetteloita eikä lohkosi omia käyttöoikeustarkistuksia. Sivun identiteetti kuuluu aina fragmentin välimuistiavaimeen, jos se on määritetty, joten sama lohko samoilla attribuuteilla ei koskaan jaa fragmenttia eri sivujen välillä. Käytä per: "user"-arvoa tai poista fragmentin välimuisti käytöstä, jos tuloste riippuu myös kävijästä.
Jos context jätetään pois tai käytössä on false, olemassa olevat merkit ja toiminta ilman kontekstia pysyvät ennallaan. Älä lisää julkiseen merkkiin luottamuksellisia tietoja.
Dynaamiset paikkamerkit
Dynaamisten saarekkeiden tulisi renderöidä paikkamerkki, joka voidaan turvallisesti tallentaa jaettuun koko sivun välimuistiin. Älä sisällytä kävijäkohtaisia tietoja paikkamerkkihaaraan.
Blockstudio etsii paikkamerkkejä seuraavassa järjestyksessä:
- nimenomainen
island.placeholder-polku placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- tavallinen malli, jossa on paikkamerkkiliput
<div class="cart-count-placeholder">
Loading cart...
</div>
Jos paikkamerkkitiedostoa ei ole, käytä tavallisen mallin mallilippuja:
<?php if ( $isIslandPlaceholder ) : ?>
<div class="cart-count-placeholder">Loading cart...</div>
<?php else : ?>
<div class="cart-count">
<?php echo esc_html( acme_cart_count() ); ?>
</div>
<?php endif; ?>
Samat arvot ovat käytettävissä malleissa PHP, Twig ja Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase on "normal", "hydrate", "placeholder" tai "fragment".
Ajonaikainen toiminta
Blockstudio lisää saarekkeiden ajonaikaisen ympäristön vain, jos renderöity sivu sisältää saarekemerkin. Sivut, joilla ei ole saarekkeita, eivät sisällä ylimääräistä saareke-JavaScript-tiedostoa.
Dynaamisten saarekkeiden ajonaikainen ympäristö:
- kerää kaikki valmiit merkit
- poistaa kaksoiskappaleet saman lohkon nimen, attribuuttien ja allekirjoitusparien osalta
- lähettää yhden erämuotoisen REST-pyynnön
- korvaa kunkin paikkamerkin palautetulla osalla
- lähettää tapahtuman
blockstudio:island:rendered - lähettää tapahtuman
blockstudio:island:hydrate
loading: "eager"-saarekkeet renderöidään heti ajonaikaisen ympäristön käynnistyessä. loading: "visible"-saarekkeet odottavat arvoa IntersectionObserver. Jos useita näkyviä saarekkeita tulee näkymään yhtä aikaa, ne kootaan yhdeksi pyynnöksi.
event päivittää saarekkeen, kun nimetty ikkunatapahtuma käynnistyy:
window.dispatchEvent(new Event('cart:updated'));
Virhetilanteissa paikkamerkki jää paikalleen ja lähetetään tapahtuma
blockstudio:island:error.
Osan päätepiste
Saarekkeen päätepiste on julkinen, mutta se ei ole yleiskäyttöinen lohkojen renderöinnin API.
Kukin merkki sisältää:
- lohkon nimen
- sallittujen attribuuttien luettelon
- palvelimella luodun allekirjoituksen
Päätepiste renderöi vain, jos:
- lohko on rekisteröity
- lohko on dynaaminen WordPress-lohko
- lohko on merkitty dynaamiseksi Blockstudio-saarekkeeksi
- saapuvat attribuutit läpäisevät lohkon skeeman ja saarekkeen sallittujen attribuuttien luettelon
- allekirjoitus vastaa normalisoitua lohkon nimeä ja attribuutteja
Allekirjoitukset luodaan renderöinnin yhteydessä sivua palvelevalla WordPress-sivustolla kyseisen sivuston suoloista ja saarekkeen hyötykuormasta. Niitä ei viedä eikä sisällytetä teemaan.
Päätepisteen vastaukset merkitään välimuistiin tallentamattomiksi. Jos haluat osien välimuistitallennuksen, käytä island.cache-ominaisuutta.
Osien välimuistitallennus
Dynaamisia osia ei tallenneta oletuksena välimuistiin.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true käyttää lyhytaikaista yleistä välimuistia. Käytä objektimuotoa, jos haluat määrittää asetukset tarkasti:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" jakaa saman välimuistissa olevan katkelman, kun lohko, määritteet ja sivun valinnainen konteksti ovat samat.
per: "user" muuttaa välimuistia nykyisen käyttäjän WordPress ID:n mukaan.
Ohjelmallinen renderöinti
Saarekkeet toimivat kaikkialla, missä Blockstudio-lohkot renderöidään:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Ne toimivat myös lohkomerkintöjen kautta:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Alkuperäinen tuloste sisältää edelleen saarekemerkin ja paikkamerkin, ja ajonaikainen ympäristö lisätään, kun renderöity vastaus sisältää kyseisen merkin.
PHP API
Blockstudio\Islands::is_island('acme/cart-count');
Blockstudio\Islands::mode('acme/cart-count');
Blockstudio\Islands::registered();
Blockstudio\Islands::marker('acme/cart-count', $attributes, $html);
marker() tarkistaa lohkon metatiedot. Dynaamiset merkit luodaan vain rekisteröidyille dynaamisille Blockstudio-lohkoille, joiden island.mode-arvoksi on asetettu dynamic.
Hookit
Tunnistus ja merkintä:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Päätepiste ja renderöinti:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request muuttaa dynaamisten saarekkeiden enimmäismäärää, jonka yksi erämuotoinen päätepistepyyntö hyväksyy. Oletusarvo on 50.
Ajonaikaisen ympäristön määritys:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Allekirjoitukset:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Elinkaaren toiminnot:
blockstudio/islands/registered
blockstudio/islands/rendered
Milloin saarekkeita ei kannata käyttää
Älä käytä dynaamista saareketta sisällölle, joka on kriittistä SEO-näkyvyyden kannalta. Dynaamiset saarekeosat eivät sisälly alkuperäiseen HTML-vastaukseen, eikä niitä ole tarkoitettu indeksoitaviksi.
Käytä tavallista renderöintiä tai hydrattua saareketta, kun sisältö voidaan tallentaa välimuistiin ja sen tulee näkyä indeksointiroboteille. Käytä dynaamista saareketta vain sisällölle, joka voi latautua sivurungon jälkeen, kuten tilin UI-tiedoille, ostoskorin tilalle, personoiduille suosituksille tai käyttöoikeuksien rajaamille ohjaimille.