Øer
Blokøer lader en blok beholde den normale renderingspipeline for Blockstudio, mens anmodningsspecifikt output flyttes væk fra det indledende HTML-svar.
Det er nyttigt, når en side skal caches aggressivt, men en blok stadig afhænger af den aktuelle besøgende, session, indkøbskurv, tilladelser eller en anden aktiv anmodningskontekst.
Blockstudio-blokke er stadig dynamiske WordPress-blokke. Øer gør dem ikke til prækompilerede statiske HTML. I stedet ændrer Blockstudio, hvad der gengives ved den første anmodning:
- hydrerede øer gengiver deres normale cache-sikre HTML og modtager en monteringshændelse
- dynamiske øer gengiver først en cache-sikker pladsholder og henter derefter det rigtige fragment fra den besøgendes browser
Tilstande
Hydrerede øer
Brug en hydreret ø, når serveroutputtet er sikkert at cache, og blokken kun har brug for et monteringssignal på frontend.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Hele blokkens HTML er med i det indledende svar. Øernes runtime sender ikke en REST-anmodning efter det. Den udsender blockstudio:island:hydrate på
markøren, så frontend-kode kan tilknytte funktionalitet.
Dynamiske øer
Brug en dynamisk ø, når det rigtige blokoutput skal gengives i den besøgendes anmodningskontekst.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Det indledende svar indeholder kun en pladsholder. Browseren samler alle klar-dynamiske øer i én enkelt anmodning til:
POST /wp-json/blockstudio/v1/island/render
Endpointet gengiver kun registrerede Blockstudio-blokke, der er dynamiske og
har blockstudio.island.mode sat til dynamic.
Konfiguration
Værdien af island kan være en forkortelse eller et objekt.
{
"blockstudio": {
"island": true
}
}
true og "hydrate" betyder begge hydreret. "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"
}
}
}
}
| Egenskab | Type | Standard | Beskrivelse |
|---|---|---|---|
mode |
"hydrate" eller "dynamic" |
"hydrate" |
Ø-tilstand. |
tag |
string |
"div" |
Indpakningstag for markør. |
attributes |
string[] |
alle blokattributter | Tilladelsesliste over attributter, der sendes til dynamiske fragmentforespørgsler. |
placeholder |
string |
registreres automatisk | Relativ sti til pladsholderskabelon. |
loading |
"eager" eller "visible" |
"eager" |
Hvornår runtime-miljøet skal hente en dynamisk ø. |
event |
string |
ikke angivet | Navn på vindueshændelse, der opdaterer en dynamisk ø. |
context |
boolean |
false |
Underskriv og gendan det forespurgte sideelements ID og indholdstype for dynamiske fragmenter. |
cache |
boolean eller object |
false |
Valgfri cachepolitik for fragmenter. |
Sidekontekst
Dynamiske fragmenter renderes normalt uafhængigt af sideskallen. Tilvælg sidens identitet, hvis din blok læser sidespecifikke indstillinger eller relateret indhold:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Markøren indeholder det forespurgte sideelements postId og postType i data-bs-island-context. Begge værdier underskrives med bloknavnet og de tilladte attributter ved hjælp af den serverende sides hemmelighed. De kan ikke ændres eller føjes til en anmodning uden at gøre signaturen ugyldig. Runtime-miljøet sender dem med den eksisterende samlede fragmentanmodning, herunder ved synlige og hændelsesstyrede opdateringer. Dette fungerer også med bs_render_block(), bs_block() og bloktags.
Under fragmentrendering henviser $block['postId'], $block['postType'], get_the_ID() og get_queried_object_id() til den side. WordPress-forespørgsels- og indlægsvariablerne gendannes bagefter, også efter en renderingsundtagelse. Dette er den forespurgte side, ikke et element i en Query Loop. Vilkårlige URL-parametre afspilles ikke, og den oprindelige anmodnings-URL gendannes ikke. Brug get_permalink($block['postId']), når du har brug for den HTML sides kanoniske URL. Arkiver og renderinger uden et forespurgt indlæg sender ingen sideidentitet.
Endpointet kontrollerer, at siden stadig findes, har den underskrevne indholdstype og kan læses af den aktuelle besøgende, før fragmentcachen konsulteres. En gyldig signatur omgår ikke beskyttelse af private indlæg eller adgangskodebeskyttelse, krav til ø-egnethed, tilladelseslister for attributter eller din bloks egne tilladelseskontroller. Sideidentitet indgår altid i fragmentcache-nøglen, når den er til stede, så den samme blok og de samme attributter på forskellige sider aldrig deler et fragment. Brug per: "user" eller undlad fragmentcache, når outputtet også afhænger af den besøgende.
Hvis context udelades eller er false, forbliver eksisterende markører og kontekstfri adfærd uændret. Læg ikke fortrolige data i den offentlige markør.
Dynamiske pladsholdere
Dynamiske øer bør gengive en pladsholder, der er sikker i en delt cache for hele siden. Medtag ikke besøgendes specifikke data i pladsholdergrenen.
Blockstudio søger efter pladsholdere i denne rækkefølge:
- den eksplicitte sti
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- den normale skabelon med pladsholderflag
<div class="cart-count-placeholder">
Loading cart...
</div>
Hvis der ikke findes nogen pladsholderfil, skal du bruge skabelonflagene i din normale skabelon:
<?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; ?>
De samme værdier er tilgængelige i skabelonerne PHP, Twig og Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase er "normal", "hydrate", "placeholder" eller "fragment".
Runtime-adfærd
Blockstudio indsætter øernes runtime kun, når den gengivne side indeholder en ømarkør. Sider uden øer sender ingen ekstra ø-JavaScript.
For dynamiske øer gør runtime følgende:
- indsamler alle klar-markører
- fjerner dubletter af identiske par af bloknavn, attributter og signatur
- sender én samlet REST-anmodning
- erstatter hver pladsholder med det returnerede fragment
- udsender
blockstudio:island:rendered - udsender
blockstudio:island:hydrate
loading: "eager"-øer gengives, så snart runtime starter. loading: "visible"-øer venter på IntersectionObserver. Hvis flere synlige øer
kommer ind i visningsområdet samtidig, samles de i én anmodning.
event opdaterer en ø, når den navngivne vindueshændelse udløses:
window.dispatchEvent(new Event('cart:updated'));
Ved fejl beholdes pladsholderen, og blockstudio:island:error udsendes.
Fragmentendpoint
Ø-endpointet er offentligt, men det er ikke et generelt blokrenderings-API.
Hver markør indeholder:
- bloknavnet
- attributterne på tilladelseslisten
- en signatur genereret af serveren
Endpointet gengiver kun, når:
- blokken er registreret
- blokken er en dynamisk WordPress-blok
- blokken er markeret som en dynamisk Blockstudio-ø
- de indgående attributter overholder blokskemaet og øens tilladelsesliste
- signaturen stemmer overens med det normaliserede bloknavn og attributterne
Signaturer genereres under gengivelsen på det WordPress-websted, der leverer siden, ud fra webstedets salte og øens nyttedata. De eksporteres ikke og indbygges ikke i et tema.
Endpoint-svar markeres som ikke-cachebare. Brug island.cache, hvis du vil cache fragmenter.
Fragmentcaching
Dynamiske fragmenter caches ikke som standard.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true bruger en kortvarig global cache. Brug objektformen for eksplicit styring:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" deler ét cachet fragment for samme blok, attributter og
fravalgt sidekontekst.
per: "user" varierer cachen efter den aktuelle WordPress bruger-id.
Programmatisk gengivelse
Øer fungerer alle steder, hvor Blockstudio-blokke gengives:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
De fungerer også via blok-tags:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Det indledende output er stadig ømarkøren og pladsholderen, og runtime indsættes, når det gengivne svar indeholder 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() validerer blokmetadata. Dynamiske markører oprettes kun for
registrerede dynamiske Blockstudio-blokke med island.mode sat til dynamic.
Hooks
Registrering og markup:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint og gengivelse:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request ændrer det maksimale antal dynamiske
øer, der accepteres i én samlet endpointanmodning. Standardværdien er 50.
Runtime-konfiguration:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Signaturer:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Livscyklushandlinger:
blockstudio/islands/registered
blockstudio/islands/rendered
Hvornår du ikke skal bruge øer
Brug ikke en dynamisk ø til SEO-kritisk indhold. Dynamiske øfragmenter findes ikke i det indledende HTML og er ikke beregnet til indeksering.
Brug normal gengivelse eller en hydreret ø, når indholdet er cache-sikkert og bør være synligt for crawlere. Brug kun en dynamisk ø til indhold, der kan indlæses efter sideskallen, f.eks. kontooplysninger UI, indkøbskurvens tilstand, personlige anbefalinger eller kontrolelementer, der kræver bestemte tilladelser.