Personliga fragment på cachade sidor
En sida som levereras från en statisk cache är likadan för alla. Det är poängen med att cacha den, men också problemet: sidhuvudet vill säga “Hej, Ada” till en inloggad kund, och kundvagnsikonen vill visa tre varor. Om mallen väljer innehåll utifrån den aktuella användaren lagrar cachen antingen en besökares hälsning för alla eller måste hoppa över sidan helt.
Blockstudios dynamiska öar hanterar de två behoven separat. Den cachade HTML innehåller en platshållare som är säker att cacha. När sidan har lästs in ber en liten körmiljö WordPress om det personliga fragmentet i besökarens egen begäran och byter ut platshållaren mot det. Sidan förblir cachebar, och bara fragmentet är dynamiskt.
Den här guiden skapar två öar, en hälsning och en kundvagnsräknare, och går igenom vad den cachade sidan innehåller, hur fragmentbegäran ser ut och hur ändpunkten avgör vem besökaren är. Den kompletterar Servering WordPress som HTML statisk.
Så fungerar en dynamisk ö
- Blocket återger sin platshållare inuti ett markörelement. Markören innehåller blocknamnet, de tillåtna attributen och en serverskapad signatur.
- Eftersom den återgivna sidan innehåller en markör lägger Blockstudio till öns körmiljö. Sidor utan öar skickar ingen körmiljö för öar JavaScript.
- Körmiljön samlar in färdiga markörer och skickar en samlad
POSTtill/wp-json/blockstudio/v1/island/render. - Ändpunkten verifierar varje signatur, återger blocket i besökarens begärandekontext och returnerar fragmenten.
- Körmiljön byter ut varje platshållare och skickar händelser.
I blockredigeraren återges blocket normalt, utan platshållare.
Steg 1: Hälsningsblocket
Skapa blocket med tre filer:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic" gör att detta blir en ö med en fragmentbegäran.
tag anger markörelementet, så att ön kan placeras direkt i en navigeringsrad.
attributes är listan över tillåtna blockattribut som följer med fragmentbegäran. Allt som inte står med skickas eller signeras inte. cache beskrivs längre fram.
Platshållaren är det som den cachade sidan innehåller. Den måste vara säker att visa för alla besökare, så den får inte innehålla användardata. En länk med texten “Konto” fungerar för alla:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
Huvudmallen återger det verkliga fragmentet:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
Det går bra att välja innehåll utifrån den aktuella användaren här: den här mallen körs bara för fragmentbegäran, aldrig för den cachade sidan.
Placera den där sidhuvudet återges:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
Blocktaggar fungerar också: <bs:acme-greeting /> eller
<block name="acme/greeting" />.
Steg 2: Vad den cachade sidan innehåller
När blocket återges på servern skapar det bara markören och platshållaren:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
Återge det en gång som anonym besökare och en gång som inloggad användare. De två strängarna är identiska byte för byte. Det är precis vad en statisk förgenerering med serveLoggedIn aktiverat kräver: oavsett vem som utlöser återgivningen är det lagrade dokumentet detsamma och inga personuppgifter kan hamna i det.
Steg 3: Fragmentbegäran
Körmiljön skickar alla färdiga öar i en enda begäran:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
Svaret är nycklat med clientId. För en inloggad besökare:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
En post som inte godkänns vid verifieringen returneras som en felkod i stället för HTML, utan att resten av gruppen misslyckas. Här ändrades den andra postens guestLabel utan motsvarande signatur, och den tredje angav ett block som inte är en dynamisk ö:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
Varje svar innehåller Cache-Control: no-store, no-cache, must-revalidate, max-age=0, Pragma: no-cache och X-Robots-Tag: noindex. Ändpunkten finns under /wp-json, som den statiska förgenereringen alltid kringgår. Därför lagrar varken ursprungscachen eller en CDN som följer ursprungets rubriker något fragment.
Vem är besökaren
Körmiljön skickar begäran med credentials: 'same-origin', så webbläsaren inkluderar inloggningscookien WordPress. WordPress REST API ignorerar normalt cookieautentisering utan en nonce, och en nonce kan inte finnas på en cachad sida. Öns ändpunkt hanterar detta själv: vid en webbläsarbegäran från samma ursprung validerar den cookien logged_in och återställer användaren innan blocket återges.
Om en begäran har samma ursprung avgörs utifrån rubriken Sec-Fetch-Site och, när den finns, rubriken Origin jämförd med home_url(). En begäran från ett annat ursprung som råkar innehålla cookien återges som anonym, så en begäran från en annan webbplats återger aldrig en besökares personliga fragment. I praktiken:
| Begäran | Återges som |
|---|---|
| Begäran med fetch från samma ursprung och giltig inloggningscookie | den inloggade användaren |
| Begäran från ett annat ursprung med samma cookie | anonym |
| Ingen cookie | anonym |
Vilken sida är det här?
Lägg till "context": true i blockstudio.island när fragmentet behöver sidans identitet. Markören signerar då den efterfrågade sidans inläggs-ID och inläggstyp tillsammans med attributen. I fragmentet syftar $block['postId'], $block['postType'],
get_the_ID() och get_queried_object_id() på den sidan. Inuti en Query Loop avser detta fortfarande den yttre efterfrågade sidan, inte loopobjektet.
Sidkontext är valfritt och ingår också i fragmentcache-nyckeln. Slutpunkten kontrollerar åtkomsten igen, även för cachade fragment, så en signerad markör visar inte en sida som sedan dess har blivit privat eller lösenordsskyddad. Se Sidkontext för konfigurationen och säkerhetsinformationen. Inga godtyckliga URL eller frågeparametrar återanvänds.
Steg 4: En kundvagnsräknare som uppdateras automatiskt
Den andra ön visar en annan typ av platshållare och två körmiljöalternativ. I stället för en separat platshållarfil kontrollerar mallen $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
Samma flaggor finns i alla mallspråk: isIsland, isIslandPlaceholder, isIslandFragment och islandPhase ("normal", "hydrate", "placeholder" eller "fragment"). Här kommer antalet från ett acme/cart_count-filter som din handelslösning fyller i. När det returnerar 3 blir svaret från ändpunkten:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible" skjuter upp begäran tills markören kommer in i visningsområdet med hjälp av IntersectionObserver. Synliga öar som visas samtidigt samlas ändå i en enda begäran. event anger en fönsterhändelse som hämtar ön på nytt, så efter ett anrop för att lägga till i kundvagnen behöver skriptet bara meddela det:
window.dispatchEvent(new Event('acme:cart-updated'));
Reagera i frontendkod
Händelser bubblar upp från markören, så en lyssnare på document täcker varje ö. event.detail.name innehåller blocknamnet:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
Efter ett byte skickar körmiljön först blockstudio:island:rendered och sedan blockstudio:island:hydrate. Vid fel ligger platshållaren kvar och blockstudio:island:error utlöses. Hydrerade öar ("island": "hydrate") hoppar över begäran helt: hela deras HTML finns på sidan och de tar bara emot händelsen hydrate, vilket passar cache-säkra interaktiva block som flikar.
Fragmentcachelagring
Fragment renderas vid varje begäran som standard. Hälsningen ovan använder en kort cache:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" varierar det cachade fragmentet efter användar-ID:t WordPress, och anonyma begäranden cachas aldrig med detta värde, så två anonyma besökare kan inte dela en post som är avsedd för en användare. per: "global" delar ett fragment för samma block och attribut, vilket passar innehåll som är aktuellt men inte personligt, till exempel lagersaldo. ttl har standardvärdet 60 sekunder, och cache: true är en global cache på 60 sekunder.
Säkerhetsmodellen
Slutpunkten är offentlig, men den är inte en generell blockrenderare. Den renderar en post endast när allt detta stämmer:
- blocket är registrerat, dynamiskt och har
island.modeinställt pådynamic - signaturen matchar blocknamnet och attributen som återstår efter filtret: endast nycklar som finns både i blockschemat och i listan över tillåtna öar
Signaturen är en HMAC-SHA256 över det normaliserade blocknamnet och attributen, signerad med auth-saltvärdet för webbplatsen som levererar innehållet. Signaturer skapas vid rendering på den webbplatsen och bäddas aldrig in i ett tema. Det får två följder. Ett dokument som renderas på staging har staging-signaturer, så rendera dokument på webbplatsen som levererar dem. Och om saltvärdena WordPress roteras blir alla signaturer i lagrade dokument ogiltiga, så rensa den statiska förhandsrenderingen efter en saltrotation.
En begäran kan innehålla upp till 50 öar; fler ger HTTP 413. Ändra gränsen med blockstudio/islands/max_per_request. Signaturhooks (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature) finns för värdar som behöver ett annat schema.
När du inte ska använda en ö
Fragment ingår inte i den initiala HTML, så sökrobotar ser dem inte. Se till att innehåll som är relevant för SEO finns i den vanliga renderingen. Använd dynamiska öar för sådant som kan komma efter sidans grundstruktur: kontolänkar, varukorgsstatus, rekommendationer och behörighetsstyrda kontroller. När hela sidan är personlig, till exempel en kontopanel, anger du dess sökväg i dynamicPaths i stället och renderar den direkt.
Nästa steg
- Islands reference: alla alternativ, uppslagsordning för platshållare, PHP API och hooks.
- Serving WordPress as Static HTML: cachen som dessa öar är utformade för.
- Static Prerendering reference:
serveLoggedIn, dynamiska sökvägar och tidig leverans. - Interactive Components: beteende på klientsidan för block som behöver mer än en monteringshändelse.