Treci la conținut

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.

JSON
{
  "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.

JSON
{
  "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:

Text
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.

JSON
{
  "blockstudio": {
    "island": true
  }
}

true și "hydrate" indică ambele modul hidratat. "dynamic" indică modul dinamic.

JSON
{
  "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:

JSON
{
  "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:

  1. calea explicită island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. șablonul normal cu indicatori pentru substituent
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Dacă nu există niciun fișier substituent, folosiți indicatorii șablonului în șablonul normal:

PHP
<?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:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. colectează toți marcatorii pregătiți
  2. elimină duplicatele perechilor identice de nume de bloc, atribute și semnătură
  3. trimite o singură cerere REST grupată
  4. înlocuiește fiecare substituent cu fragmentul returnat
  5. emite blockstudio:island:rendered
  6. 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:

JavaScript
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.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true folosește un cache global de scurtă durată. Folosiți forma obiect pentru control explicit:

JSON
{
  "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:

PHP
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:

HTML
<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

PHP
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:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Endpoint și randare:

PHP
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:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Semnături:

PHP
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature

Acțiuni de ciclu de viață:

PHP
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.