Öar
Blocköar låter ett block behålla den vanliga renderingspipen för Blockstudio, samtidigt som utdata som är specifika för en begäran flyttas ut från det första HTML-svaret.
Det här är användbart när en sida bör cachas aggressivt, men ett block fortfarande är beroende av den aktuella besökaren, sessionen, kundvagnen, behörigheter eller annan aktuell begärandekontext.
Blockstudio-block är fortfarande dynamiska WordPress-block. Öar omvandlar dem inte till förkompilerade statiska HTML. I stället ändrar Blockstudio vad som renderas vid den första begäran:
- hydrerade öar renderar sin vanliga cache-säkra HTML och tar emot en monteringshändelse
- dynamiska öar renderar först en cache-säker platshållare och hämtar sedan det verkliga fragmentet från besökarens webbläsare
Lägen
Hydrerade öar
Använd en hydrerad ö när serverutdata är säker att cacha och blocket bara behöver en monteringssignal i frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Hela blockets HTML finns i det första svaret. Öarnas körmiljö gör ingen REST-begäran efter det. Den skickar blockstudio:island:hydrate på markören så att frontendkod kan koppla på beteenden.
Dynamiska öar
Använd en dynamisk ö när det verkliga blockinnehållet måste renderas i besökarens begärandekontext.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Det första svaret innehåller bara en platshållare. Webbläsaren samlar alla dynamiska öar som är klara i en enda begäran till:
POST /wp-json/blockstudio/v1/island/render
Slutpunkten renderar bara registrerade Blockstudio-block som är dynamiska och har blockstudio.island.mode inställt på dynamic.
Konfiguration
Värdet för island kan vara en kortform eller ett objekt.
{
"blockstudio": {
"island": true
}
}
true och "hydrate" betyder båda hydrerad. "dynamic" betyder dynamisk.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Egenskap | Typ | Standard | Beskrivning |
|---|---|---|---|
mode |
"hydrate" eller "dynamic" |
"hydrate" |
Ö-läge. |
tag |
string |
"div" |
Omslagstagg för markör. |
attributes |
string[] |
alla blockattribut | Tillåtelselista för attribut som skickas med dynamiska fragmentförfrågningar. |
placeholder |
string |
identifieras automatiskt | Relativ sökväg till platshållarmallen. |
loading |
"eager" eller "visible" |
"eager" |
När körmiljön ska hämta en dynamisk ö. |
event |
string |
ej angivet | Namn på fönsterhändelse som uppdaterar en dynamisk ö. |
context |
boolean |
false |
Signera och återställ den efterfrågade sidans inläggs-ID och inläggstyp för dynamiska fragment. |
cache |
boolean eller object |
false |
Valfri cachepolicy för fragment. |
Sidkontext
Dynamiska fragment renderas normalt oberoende av sidans skal. Aktivera sidans identitet om ditt block läser sidspecifika inställningar eller relaterat innehåll:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Markören innehåller den efterfrågade sidans postId och postType i data-bs-island-context. Båda värdena signeras med blocknamnet och tillåtna attribut med hjälp av den visande webbplatsens hemlighet. De kan inte ändras eller läggas till i en förfrågan utan att signaturen blir ogiltig. Körmiljön skickar dem med den befintliga batchade fragmentförfrågan, även vid uppdateringar som utlöses av synlighet eller händelser. Detta fungerar också med bs_render_block(), bs_block() och blocktaggar.
Under fragmentrendering hänvisar $block['postId'], $block['postType'], get_the_ID() och get_queried_object_id() till den sidan. WordPress-frågan och globala inläggsvärden återställs efteråt, även om ett renderingsfel inträffar. Detta är den efterfrågade sidan, inte ett objekt inuti en Query Loop. Godtyckliga parametrar i URL spelas inte upp igen och den ursprungliga förfrågans URL återställs inte. Använd get_permalink($block['postId']) när du behöver den HTML sidans kanoniska URL. Arkiv och renderingar utan ett efterfrågat inlägg skickar ingen sididentitet.
Slutpunkten kontrollerar att sidan fortfarande finns, har den signerade inläggstypen och kan läsas av den aktuella besökaren innan fragmentcachen används. En giltig signatur kringgår inte skydd för privata inlägg eller lösenordsskydd, ö-behörighet, tillåtelselistor för attribut eller blockets egna behörighetskontroller. Sididentiteten ingår alltid i fragmentcachenyckeln när den finns, så samma block och attribut på olika sidor delar aldrig ett fragment. Använd per: "user" eller ingen fragmentcache när utdata också beror på besökaren.
Om context utelämnas eller är false förblir befintliga markörer och det kontextfria beteendet oförändrade. Lägg inte konfidentiella data i den offentliga markören.
Dynamiska platshållare
Dynamiska öar bör rendera en platshållare som är säker i en delad helsidescache. Ta inte med besökarspecifika data i platshållargrenen.
Blockstudio letar efter platshållare i följande ordning:
- den uttryckliga sökvägen
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- den vanliga mallen med platshållarflaggor
<div class="cart-count-placeholder">
Loading cart...
</div>
Om ingen platshållarfil finns använder du mallflaggorna i den vanliga mallen:
<?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; ?>
Samma värden är tillgängliga i mallarna PHP, Twig och Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase är "normal", "hydrate", "placeholder" eller "fragment".
Körmiljöns beteende
Blockstudio lägger till körmiljön för öar endast när den renderade sidan innehåller en ömarkör. Sidor utan öar skickar ingen extra ö-JavaScript.
För dynamiska öar gör körmiljön följande:
- samlar alla markörer som är klara
- tar bort dubbletter av par med identiska blocknamn, attribut och signaturer
- skickar en enda samlad REST-begäran
- byter ut varje platshållare mot det returnerade fragmentet
- skickar
blockstudio:island:rendered - skickar
blockstudio:island:hydrate
loading: "eager"-öar renderas så snart körmiljön startar. loading: "visible"-öar väntar på IntersectionObserver. Om flera synliga öar kommer in i visningsområdet samtidigt samlas de i en enda begäran.
event uppdaterar en ö när den namngivna fönsterhändelsen utlöses:
window.dispatchEvent(new Event('cart:updated'));
Vid fel ligger platshållaren kvar och blockstudio:island:error skickas.
Fragmentändpunkt
Öns ändpunkt är offentlig, men den är inte ett allmänt gränssnitt för blockrendering API.
Varje markör innehåller:
- blocknamnet
- attributen i tillåtelselistan
- en serverskapad signatur
Ändpunkten renderar bara när:
- blocket är registrerat
- blocket är ett dynamiskt WordPress-block
- blocket är markerat som en dynamisk Blockstudio-ö
- de inkommande attributen följer blockschemat och öns tillåtelselista
- signaturen matchar det normaliserade blocknamnet och attributen
Signaturer skapas vid rendering på den betjänande WordPress-webbplatsen utifrån webbplatsens salter och öns nyttolast. De exporteras inte och bäddas inte in i ett tema.
Ändpunktssvar markeras som ej cachebara. Använd island.cache om du vill cacha fragment.
Fragmentcachning
Dynamiska fragment cachas inte som standard.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true använder en kortlivad global cache. Använd objektformen för uttrycklig kontroll:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" delar ett cachelagrat fragment för samma block, attribut och
kontext för sidor med opt-in.
per: "user" varierar cachen efter aktuellt WordPress användar-ID.
Programmatisk rendering
Öar fungerar där Blockstudio-block renderas:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
De fungerar även via blocktaggar:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Den första utdata är fortfarande ömarkören och platshållaren, och körmiljön läggs till när det renderade svaret innehåller den markören.
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() validerar blockmetadata. Dynamiska markörer skapas bara för registrerade dynamiska Blockstudio-block där island.mode är inställt på dynamic.
Hooks
Identifiering och markup:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Ändpunkt och rendering:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request ändrar det högsta antalet dynamiska öar som godtas i en enda samlad ändpunktsbegäran. Standardvärdet är 50.
Körmiljökonfiguration:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Signaturer:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Livscykelåtgärder:
blockstudio/islands/registered
blockstudio/islands/rendered
När du inte ska använda öar
Använd inte en dynamisk ö för innehåll som är kritiskt för SEO. Dynamiska öfragment finns inte i det första HTML och är inte avsedda att indexeras.
Använd normal rendering eller en hydrerad ö när innehållet är cache-säkert och bör vara synligt för sökrobotar. Använd en dynamisk ö endast för innehåll som kan komma efter sidskalet, till exempel kontots UI, kundvagnsstatus, personliga rekommendationer eller behörighetsstyrda kontroller.