Gå til indhold

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

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

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

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

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

true og "hydrate" betyder begge hydreret. "dynamic" betyder dynamisk.

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

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

  1. den eksplicitte sti island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. den normale skabelon med pladsholderflag
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Hvis der ikke findes nogen pladsholderfil, skal du bruge skabelonflagene i din normale skabelon:

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; ?>

De samme værdier er tilgængelige i skabelonerne PHP, Twig og Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. indsamler alle klar-markører
  2. fjerner dubletter af identiske par af bloknavn, attributter og signatur
  3. sender én samlet REST-anmodning
  4. erstatter hver pladsholder med det returnerede fragment
  5. udsender blockstudio:island:rendered
  6. 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:

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

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

true bruger en kortvarig global cache. Brug objektformen for eksplicit styring:

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

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

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

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() validerer blokmetadata. Dynamiske markører oprettes kun for registrerede dynamiske Blockstudio-blokke med island.mode sat til dynamic.

Hooks

Registrering og markup:

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

Endpoint og gengivelse:

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

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Signaturer:

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

Livscyklushandlinger:

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