Salos
Blokų salos leidžia blokui naudoti įprastą Blockstudio atvaizdavimo grandinę, o konkrečiai užklausai skirtą išvestį perkelti iš pradinio HTML atsakymo.
Tai naudinga, kai puslapį reikia intensyviai talpinti į podėlį, tačiau vienas blokas vis tiek priklauso nuo esamo lankytojo, sesijos, krepšelio, teisių ar kito esamos užklausos konteksto.
Blockstudio blokai vis tiek yra dinaminiai WordPress blokai. Salos nepaverčia jų iš anksto sukompiliuotais statiniais HTML. Vietoj to, Blockstudio pakeičia tai, kas atvaizduojama per pirmąją užklausą:
- hidratuotos salos atvaizduoja įprastą talpyklai saugią HTML ir gauna prijungimo įvykį
- dinaminės salos pirmiausia atvaizduoja talpyklai saugų pakaitalą, tada lankytojo naršyklėje gauna tikrąją dalį
Režimai
Hidratuotos salos
Naudokite hidratuotą salą, kai serverio išvestį saugu talpinti į podėlį, o blokui reikia tik sąsajos prijungimo signalo.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Visa bloko HTML yra pradiniame atsakyme. Salos vykdymo aplinka dėl jos nesiunčia REST užklausos. Ji išsiunčia blockstudio:island:hydrate žymos elementui, kad sąsajos kodas galėtų prijungti elgseną.
Dinaminės salos
Naudokite dinaminę salą, kai tikrąją bloko išvestį reikia atvaizduoti lankytojo užklausos kontekste.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Pradiniame atsakyme yra tik pakaitalas. Naršyklė sugrupuoja visas paruoštas dinamines salas į vieną užklausą adresu:
POST /wp-json/blockstudio/v1/island/render
Galinis punktas atvaizduoja tik registruotus Blockstudio blokus, kurie yra dinaminiai ir kurių blockstudio.island.mode nustatytas į dynamic.
Konfigūracija
island reikšmė gali būti trumpinys arba objektas.
{
"blockstudio": {
"island": true
}
}
true ir "hydrate" reiškia hidratuotą režimą. "dynamic" reiškia dinaminį režimą.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Savybė | Tipas | Numatytoji reikšmė | Aprašymas |
|---|---|---|---|
mode |
"hydrate" arba "dynamic" |
"hydrate" |
Salos režimas. |
tag |
string |
"div" |
Žymeklio apgaubiamoji žyma. |
attributes |
string[] |
visi bloko atributai | Į dinaminio fragmento užklausas siunčiamas atributų leidžiamasis sąrašas. |
placeholder |
string |
aptinkamas automatiškai | Santykinis vietaženklių šablono kelias. |
loading |
"eager" arba "visible" |
"eager" |
Kada vykdymo aplinka turėtų gauti dinaminę salą. |
event |
string |
nenustatyta | Lango įvykio pavadinimas, kuris atnaujina dinaminę salą. |
context |
boolean |
false |
Pasirašo ir atkuria užklausto puslapio įrašo ID bei tipą dinaminiams fragmentams. |
cache |
boolean arba object |
false |
Pasirenkama fragmentų talpyklos politika. |
Puslapio kontekstas
Dinaminiai fragmentai paprastai atvaizduojami nepriklausomai nuo puslapio apvalkalo. Įtraukite puslapio tapatybę, jei jūsų blokas naudoja konkretaus puslapio nustatymus ar susijusį turinį:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Žymeklyje yra užklausto puslapio postId ir postType, įrašytų į data-bs-island-context. Abi reikšmės pasirašomos naudojant bloko pavadinimą, leidžiamuosius atributus ir aptarnaujančios svetainės paslaptį. Jų negalima pakeisti ar pridėti prie užklausos nepanaikinus parašo galiojimo. Vykdymo aplinka siunčia jas kartu su esama paketine fragmentų užklausa, įskaitant matomus ir įvykių inicijuojamus atnaujinimus. Tai taip pat veikia su bs_render_block(), bs_block() ir blokų žymomis.
Atvaizduojant fragmentą, $block['postId'], $block['postType'], get_the_ID() ir get_queried_object_id() nurodo tą puslapį. Po to atkuriamos WordPress užklausos ir įrašo globalios reikšmės, taip pat ir įvykus atvaizdavimo išimčiai. Tai yra užklaustas puslapis, o ne elementas Query Loop viduje. Savavališki URL parametrai neatkuriami, taip pat neatkuriamas pradinis užklausos URL. Jei reikia puslapio HTML kanoninio URL, naudokite get_permalink($block['postId']). Archyvai ir atvaizdavimai be užklausto įrašo puslapio tapatybės nesiunčia.
Prieš tikrindamas fragmentų talpyklą, galinis punktas patikrina, ar puslapis vis dar egzistuoja, ar jo įrašo tipas atitinka pasirašytąjį ir ar dabartinis lankytojas gali jį skaityti. Galiojantis parašas nepanaikina privačių įrašų ar apsaugos slaptažodžiu, salos tinkamumo, atributų leidžiamųjų sąrašų ar jūsų bloko leidimų patikrų. Kai puslapio tapatybė pateikiama, ji visada įtraukiama į fragmento talpyklos raktą, todėl tas pats blokas su tais pačiais atributais skirtinguose puslapiuose niekada nesidalija fragmentu. Naudokite per: "user" arba išjunkite fragmentų talpyklą, jei išvestis priklauso ir nuo lankytojo.
Jei context praleistas arba false, esami žymekliai ir nuo konteksto nepriklausanti elgsena lieka nepakitę. Nedėkite konfidencialių duomenų į viešą žymeklį.
Dinaminiai pakaitalai
Dinaminės salos turi atvaizduoti pakaitalą, kurį saugu naudoti bendroje viso puslapio talpykloje. Pakaitalo šakoje neįtraukite konkrečiam lankytojui skirtų duomenų.
Blockstudio pakaitalų ieško tokia tvarka:
- aiškiai nurodytas kelias
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- įprastas šablonas su pakaitalų vėliavėlėmis
<div class="cart-count-placeholder">
Loading cart...
</div>
Jei pakaitalo failo nėra, įprastame šablone naudokite šablono vėliavėles:
<?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; ?>
Tos pačios reikšmės pasiekiamos šablonuose PHP, Twig ir Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase yra "normal", "hydrate", "placeholder" arba "fragment".
Vykdymo elgsena
Blockstudio įterpia salos vykdymo aplinką tik tada, kai atvaizduotame puslapyje yra salos žyma. Puslapiuose be salų neįkeliama papildoma salos JavaScript.
Dinaminėms saloms vykdymo aplinka:
- surenka visas paruoštas žymas
- pašalina pasikartojančias identiškas bloko pavadinimo, atributų ir parašo poras
- siunčia vieną sugrupuotą REST užklausą
- pakeičia kiekvieną pakaitalą grąžinta dalimi
- išsiunčia
blockstudio:island:rendered - išsiunčia
blockstudio:island:hydrate
loading: "eager" salos atvaizduojamos iškart, kai paleidžiama vykdymo aplinka. loading: "visible" salos laukia IntersectionObserver. Jei kelios matomos salos vienu metu patenka į peržiūros sritį, jų užklausos sugrupuojamos į vieną.
event atnaujina salą, kai įvyksta nurodytas lango įvykis:
window.dispatchEvent(new Event('cart:updated'));
Nesėkmės atveju pakaitalas paliekamas vietoje ir išsiunčiamas blockstudio:island:error.
Dalių galinis punktas
Salos galinis punktas yra viešas, tačiau tai nėra bendros paskirties blokų atvaizdavimo API.
Kiekviena žyma turi:
- bloko pavadinimą
- leidžiamų atributų sąrašą
- serverio sugeneruotą parašą
Galinis punktas atvaizduoja tik tada, kai:
- blokas yra registruotas
- blokas yra dinaminis WordPress blokas
- blokas pažymėtas kaip dinaminė Blockstudio sala
- gaunami atributai atitinka bloko schemą ir salos leidžiamų atributų sąrašą
- parašas atitinka normalizuotą bloko pavadinimą ir atributus
Parašai generuojami atvaizdavimo metu aptarnaujančioje WordPress svetainėje, naudojant tos svetainės druskas ir salos duomenis. Jie neeksportuojami ir neįrašomi į temą.
Galinio punkto atsakymai pažymimi kaip netinkami talpinti į podėlį. Jei norite talpinti dalis į podėlį, naudokite island.cache.
Dalių talpinimas į podėlį
Dinaminės dalys pagal numatytuosius nustatymus nėra talpinamos į podėlį.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true naudoja trumpalaikę visuotinę talpyklą. Aiškiai kontrolei naudokite objekto formą:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" naudoja tą pačią talpyklos iškarpą, kai sutampa blokas, atributai ir pasirenkamas puslapio kontekstas.
per: "user" talpyklos įrašą diferencijuoja pagal dabartinio WordPress naudotojo ID.
Atvaizdavimas programiškai
Salos veikia visur, kur atvaizduojami Blockstudio blokai:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Jos taip pat veikia per blokų žymas:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Pradinė išvestis vis tiek yra salos žyma ir pakaitalas, o vykdymo aplinka įterpiama, kai atvaizduotame atsakyme yra ta žyma.
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() tikrina bloko metaduomenis. Dinaminės žymos sukuriamos tik registruotiems dinaminiams Blockstudio blokams, kurių island.mode nustatytas į dynamic.
Kabliukai
Aptikimas ir žymėjimas:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Galinis punktas ir atvaizdavimas:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request keičia didžiausią dinaminių salų skaičių, kurį priima viena sugrupuota galinio punkto užklausa. Numatytoji reikšmė yra 50.
Vykdymo aplinkos konfigūracija:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Parašai:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Gyvavimo ciklo veiksmai:
blockstudio/islands/registered
blockstudio/islands/rendered
Kada salų nenaudoti
Nenaudokite dinaminės salos SEO svarbiam turiniui. Dinaminių salų dalys nėra pradiniame HTML ir nėra skirtos indeksuoti.
Kai turinį saugu talpinti į podėlį ir jis turi būti matomas tikrinimo robotams, naudokite įprastą atvaizdavimą arba hidratuotą salą. Dinaminę salą naudokite tik turiniui, kuris gali būti pateiktas įkėlus puslapio karkasą, pavyzdžiui, paskyros UI, krepšelio būsenai, suasmenintoms rekomendacijoms ar tik leidimą turintiems naudotojams rodomiems valdikliams.