Insule
Insulele de bloc permit unui bloc să păstreze fluxul normal de randare Blockstudio, mutând în același timp rezultatul specific cererii în afara răspunsului inițial HTML.
Acest lucru este util când pagina trebuie stocată agresiv în cache, dar un bloc depinde totuși de vizitatorul curent, sesiune, coș, permisiuni sau alt context activ al cererii.
Blocurile Blockstudio rămân blocuri dinamice WordPress. Insulele nu le transformă în HTML statice precompilate. În schimb, Blockstudio modifică ce se randează la prima cerere:
- insulele hidratate randează conținutul normal HTML sigur pentru cache și primesc un eveniment de montare
- insulele dinamice randează mai întâi un substituent sigur pentru cache, apoi preiau fragmentul real din browserul vizitatorului
Moduri
Insule hidratate
Folosiți o insulă hidratată când rezultatul serverului poate fi stocat în siguranță în cache, iar blocul are nevoie doar de un semnal de montare în frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
HTML complet al blocului este prezent în răspunsul inițial. Runtime-ul insulei nu face o cerere REST pentru acesta. El emite blockstudio:island:hydrate pe marcator, astfel încât codul frontend să poată atașa comportamentul.
Insule dinamice
Folosiți o insulă dinamică atunci când rezultatul real al blocului trebuie randat în contextul cererii vizitatorului.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Răspunsul inițial conține doar un substituent. Browserul grupează toate insulele dinamice pregătite într-o singură cerere către:
POST /wp-json/blockstudio/v1/island/render
Endpointul randează doar blocurile Blockstudio înregistrate care sunt dinamice și au blockstudio.island.mode setat la dynamic.
Configurare
Valoarea island poate fi o formă prescurtată sau un obiect.
{
"blockstudio": {
"island": true
}
}
true și "hydrate" indică ambele modul hidratat. "dynamic" indică modul dinamic.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Proprietate | Tip | Valoare implicită | Descriere |
|---|---|---|---|
mode |
"hydrate" sau "dynamic" |
"hydrate" |
Modul insulă. |
tag |
string |
"div" |
Eticheta elementului container pentru marcaj. |
attributes |
string[] |
toate atributele blocului | Lista de atribute permise, trimisă la cererile pentru fragmente dinamice. |
placeholder |
string |
detectată automat | Calea relativă către șablonul substituent. |
loading |
"eager" sau "visible" |
"eager" |
Momentul în care runtime-ul trebuie să preia o insulă dinamică. |
event |
string |
neconfigurat | Numele evenimentului din fereastră care reîmprospătează o insulă dinamică. |
context |
boolean |
false |
Semnează și restabilește ID-ul și tipul postării paginii interogate pentru fragmentele dinamice. |
cache |
boolean sau object |
false |
Politica opțională de stocare în cache a fragmentelor. |
Contextul paginii
Fragmentele dinamice sunt randate, de regulă, independent de structura paginii. Activați identitatea paginii dacă blocul citește setări specifice paginii sau conținut asociat:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Marcajul include postId și postType paginii interogate în data-bs-island-context. Ambele valori sunt semnate împreună cu numele blocului și atributele permise, folosind secretul site-ului care le furnizează. Nu pot fi modificate sau adăugate la o cerere fără ca semnătura să devină invalidă. Runtime-ul le trimite împreună cu cererea existentă pentru fragmente grupate, inclusiv la reîmprospătările vizibile și la cele declanșate de evenimente. Funcționează și cu bs_render_block(), bs_block() și etichetele blocurilor.
În timpul randării fragmentului, $block['postId'], $block['postType'],
get_the_ID() și get_queried_object_id() se referă la pagina respectivă. WordPress valorile globale
pentru query și post sunt restaurate ulterior, inclusiv după o excepție la randare.
Aceasta este pagina interogată, nu un element dintr-o buclă Query Loop. Nu redă din nou
parametri URL arbitrari și nu restaurează cererea originală URL. Folosiți
get_permalink($block['postId']) când aveți nevoie de HTML canonical al paginii URL.
Arhivele și randările fără o postare interogată nu transmit identitatea paginii.
Punctul final verifică dacă pagina există încă, are tipul de postare semnat și poate fi citită de vizitatorul curent înainte de a consulta cache-ul fragmentelor. O semnătură validă nu ocolește protecția postărilor private sau protejate prin parolă, eligibilitatea insulei, listele de atribute permise ori propriile verificări de permisiuni ale blocului. Când este prezentă, identitatea paginii face întotdeauna parte din cheia cache-ului fragmentelor, astfel încât același bloc și aceleași atribute de pe pagini diferite nu partajează niciodată un fragment. Folosiți per: "user" sau dezactivați cache-ul fragmentelor când rezultatul depinde și de vizitator.
Dacă context este omis sau false, marcajele existente și comportamentul fără context rămân neschimbate. Nu includeți date confidențiale în marcajul public.
Substituenți dinamici
Insulele dinamice trebuie să randeze un substituent sigur pentru un cache partajat al întregii pagini. Nu includeți date specifice vizitatorului în ramura substituentului.
Blockstudio caută substituenți în această ordine:
- calea explicită
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- șablonul normal cu indicatori pentru substituent
<div class="cart-count-placeholder">
Loading cart...
</div>
Dacă nu există niciun fișier substituent, folosiți indicatorii șablonului în șablonul normal:
<?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; ?>
Aceleași valori sunt disponibile în șabloanele PHP, Twig și Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase este "normal", "hydrate", "placeholder" sau "fragment".
Comportamentul runtime-ului
Blockstudio inserează runtime-ul insulei doar când pagina randată conține un marcator de insulă. Paginile fără insule nu includ niciun JavaScript suplimentar pentru insule.
Pentru insulele dinamice, runtime-ul:
- colectează toți marcatorii pregătiți
- elimină duplicatele perechilor identice de nume de bloc, atribute și semnătură
- trimite o singură cerere REST grupată
- înlocuiește fiecare substituent cu fragmentul returnat
- emite
blockstudio:island:rendered - emite
blockstudio:island:hydrate
Insulele loading: "eager" se randează imediat ce pornește runtime-ul. Insulele loading: "visible" așteaptă IntersectionObserver. Dacă mai multe insule vizibile intră simultan în fereastra de vizualizare, acestea sunt grupate într-o singură cerere.
event reîmprospătează o insulă când se declanșează evenimentul de fereastră cu numele respectiv:
window.dispatchEvent(new Event('cart:updated'));
În caz de eșec, substituentul rămâne pe loc și se emite
blockstudio:island:error.
Endpoint pentru fragmente
Endpointul insulei este public, dar nu este un API general pentru randarea blocurilor.
Fiecare marcator conține:
- numele blocului
- atributele din lista permisă
- o semnătură generată pe server
Endpointul randează doar când:
- blocul este înregistrat
- blocul este un bloc dinamic WordPress
- blocul este marcat ca insulă dinamică Blockstudio
- atributele primite respectă schema blocului și lista permisă pentru insulă
- semnătura corespunde numelui de bloc și atributelor normalizate
Semnăturile sunt generate la momentul randării pe site-ul WordPress care servește conținutul, folosind sarea acelui site și încărcătura utilă a insulei. Nu sunt exportate și nici încorporate într-o temă.
Răspunsurile endpointului sunt marcate ca necache-uibile. Dacă doriți memorarea fragmentelor în cache, folosiți
island.cache.
Memorarea fragmentelor în cache
Fragmentele dinamice nu sunt stocate în cache în mod implicit.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true folosește un cache global de scurtă durată. Folosiți forma obiect pentru control explicit:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" partajează un fragment memorat în cache pentru același bloc, aceleași atribute și același context de pagină activat opțional.
per: "user" variază memoria cache în funcție de ID-ul utilizatorului curent WordPress.
Randare programatică
Insulele funcționează oriunde sunt randate blocuri Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Funcționează și prin etichetele blocurilor:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Rezultatul inițial rămâne marcatorul și substituentul insulei, iar runtime-ul este inserat când răspunsul randat conține acel marcator.
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() validează metadatele blocului. Marcatorii dinamici sunt creați doar pentru blocurile dinamice Blockstudio înregistrate, cu island.mode setat la dynamic.
Hook-uri
Detectare și marcaj:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint și randare:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request modifică numărul maxim de insule dinamice acceptate de o singură cerere grupată către endpoint. Valoarea implicită este 50.
Configurarea runtime-ului:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Semnături:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Acțiuni de ciclu de viață:
blockstudio/islands/registered
blockstudio/islands/rendered
Când să nu folosiți insulele
Nu folosiți o insulă dinamică pentru conținut SEO esențial. Fragmentele insulei dinamice nu sunt prezente în răspunsul inițial HTML și nu sunt destinate indexării.
Folosiți randarea normală sau o insulă hidratată când conținutul poate fi stocat în cache și trebuie să fie vizibil pentru roboții de indexare. Folosiți o insulă dinamică doar pentru conținut care poate apărea după structura de bază a paginii, precum UI contului, starea coșului, recomandările personalizate sau comenzile restricționate prin permisiuni.