Islands
Block-Islands behalten die normale Blockstudio-Rendering-Pipeline eines Blocks bei und verlagern gleichzeitig anfragespezifische Ausgaben aus der anfänglichen HTML-Antwort.
Das ist nützlich, wenn eine Seite aggressiv zwischengespeichert werden soll, ein Block aber weiterhin vom aktuellen Besucher, seiner Sitzung, seinem Warenkorb, seinen Berechtigungen oder einem anderen aktuellen Anfragekontext abhängt.
Blockstudio-Blöcke bleiben dynamische WordPress-Blöcke. Islands machen daraus keine vorkompilierten statischen HTML. Stattdessen ändert Blockstudio, was bei der ersten Anfrage gerendert wird:
- Hydrierte Islands rendern ihr normales cache-sicheres HTML und erhalten ein Mount-Ereignis
- Dynamische Islands rendern zuerst einen cache-sicheren Platzhalter und rufen dann das echte Fragment im Browser des Besuchers ab
Modi
Hydrierte Islands
Verwende ein hydriertes Island, wenn die Serverausgabe cache-sicher ist und der Block nur ein Mount-Signal im Frontend benötigt.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Das vollständige Block-HTML ist in der anfänglichen Antwort enthalten. Die Island-Laufzeit stellt dafür keine REST-Anfrage. Sie löst am Marker blockstudio:island:hydrate aus, damit Frontend-Code das Verhalten hinzufügen kann.
Dynamische Islands
Verwende ein dynamisches Island, wenn die echte Blockausgabe im Anfragekontext des Besuchers gerendert werden muss.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Die anfängliche Antwort enthält nur einen Platzhalter. Der Browser bündelt alle bereiten dynamischen Islands in einer einzigen Anfrage an:
POST /wp-json/blockstudio/v1/island/render
Der Endpunkt rendert nur registrierte Blockstudio-Blöcke, die dynamisch sind und für die blockstudio.island.mode auf dynamic gesetzt ist.
Konfiguration
Der Wert von island kann eine Kurzform oder ein Objekt sein.
{
"blockstudio": {
"island": true
}
}
true und "hydrate" bedeuten beide hydriert. "dynamic" bedeutet dynamisch.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Eigenschaft | Typ | Standard | Beschreibung |
|---|---|---|---|
mode |
"hydrate" oder "dynamic" |
"hydrate" |
Island-Modus. |
tag |
string |
"div" |
Markup-Wrapper-Tag. |
attributes |
string[] |
alle Blockattribute | Attribut-Zulassungsliste, die an dynamische Fragmentanfragen gesendet wird. |
placeholder |
string |
automatisch erkannt | Relativer Pfad zur Platzhaltervorlage. |
loading |
"eager" oder "visible" |
"eager" |
Zeitpunkt, zu dem die Laufzeit ein dynamisches Island abrufen soll. |
event |
string |
nicht festgelegt | Name des Fensterereignisses, das ein dynamisches Island aktualisiert. |
context |
boolean |
false |
Abgefragte Beitrags-ID und Beitragstyp der Seite für dynamische Fragmente signieren und wiederherstellen. |
cache |
boolean oder object |
false |
Optionale Fragment-Cache-Richtlinie. |
Seitenkontext
Dynamische Fragmente werden normalerweise unabhängig vom Seitenlayout gerendert. Übernimm die Identität der Seite, wenn dein Block seitenspezifische Einstellungen oder zugehörige Inhalte ausliest:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Der Marker enthält die postId und postType der abgefragten Seite in data-bs-island-context. Beide Werte werden zusammen mit dem Blocknamen und den zugelassenen Attributen mithilfe des Geheimnisses der ausliefernden Website signiert. Sie können nicht geändert oder einer Anfrage hinzugefügt werden, ohne dass die Signatur ungültig wird. Die Laufzeit sendet sie mit der bestehenden gebündelten Fragmentanfrage, auch bei Aktualisierungen aufgrund sichtbarer Inhalte und Ereignisse. Das funktioniert auch mit bs_render_block(), bs_block() und Block-Tags.
Während des Renderns des Fragments beziehen sich $block['postId'], $block['postType'], get_the_ID() und get_queried_object_id() auf diese Seite. WordPress-Abfrage- und Beitrags-Globals werden anschließend wiederhergestellt, auch nach einer Render-Ausnahme. Gemeint ist die abgefragte Seite, nicht ein Element innerhalb einer Query Loop. Beliebige URL-Parameter werden nicht erneut angewendet und die ursprüngliche Anfrage-URL wird nicht wiederhergestellt. Verwende get_permalink($block['postId']), wenn du die kanonische URL der Seite HTML benötigst. Für Archive und Render-Vorgänge ohne abgefragten Beitrag wird keine Seitenidentität gesendet.
Der Endpunkt prüft vor dem Zugriff auf den Fragment-Cache, ob die Seite noch existiert, den signierten Beitragstyp hat und für den aktuellen Besucher lesbar ist. Eine gültige Signatur umgeht weder den Schutz privater Beiträge oder den Passwortschutz noch die Island-Berechtigung, Attribut-Zulassungslisten oder die eigenen Berechtigungsprüfungen deines Blocks. Wenn eine Seitenidentität vorhanden ist, gehört sie immer zum Fragment-Cache-Schlüssel. Daher werden Fragmente desselben Blocks mit denselben Attributen auf verschiedenen Seiten nie gemeinsam genutzt. Verwende per: "user" oder keinen Fragment-Cache, wenn die Ausgabe auch vom Besucher abhängt.
Wenn context weggelassen oder auf false gesetzt wird, bleiben vorhandene Marker und das Verhalten ohne Kontext unverändert. Lege keine vertraulichen Daten im öffentlichen Marker ab.
Dynamische Platzhalter
Dynamische Islands sollten einen Platzhalter rendern, der in einem gemeinsam genutzten vollständigen Seiten-Cache sicher ist. Füge im Platzhalterzweig keine besucherspezifischen Daten ein.
Blockstudio sucht in dieser Reihenfolge nach Platzhaltern:
- der explizite Pfad
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- die normale Vorlage mit Platzhalter-Flags
<div class="cart-count-placeholder">
Loading cart...
</div>
Wenn keine Platzhalterdatei vorhanden ist, verwende die Vorlagen-Flags in deiner normalen Vorlage:
<?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; ?>
Dieselben Werte sind in PHP-, Twig- und Blade-Vorlagen verfügbar:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase ist "normal", "hydrate", "placeholder" oder "fragment".
Laufzeitverhalten
Blockstudio fügt die Island-Laufzeit nur ein, wenn die gerenderte Seite einen Island-Marker enthält. Seiten ohne Islands laden keine zusätzliche Island-JavaScript.
Bei dynamischen Islands führt die Laufzeit Folgendes aus:
- sammelt alle bereiten Marker
- entfernt Duplikate identischer Paare aus Blockname, Attributen und Signatur
- sendet eine gebündelte REST-Anfrage
- ersetzt jeden Platzhalter durch das zurückgegebene Fragment
- löst
blockstudio:island:renderedaus - löst
blockstudio:island:hydrateaus
loading: "eager"-Islands werden gerendert, sobald die Laufzeit startet. loading: "visible"-Islands warten auf IntersectionObserver. Wenn mehrere sichtbare Islands gleichzeitig in den Viewport gelangen, werden sie in einer Anfrage gebündelt.
event aktualisiert ein Island, wenn das benannte Window-Ereignis ausgelöst wird:
window.dispatchEvent(new Event('cart:updated'));
Bei Fehlern bleibt der Platzhalter bestehen und blockstudio:island:error wird ausgelöst.
Fragment-Endpunkt
Der Island-Endpunkt ist öffentlich, aber keine allgemeine Block-Rendering-API.
Jeder Marker enthält:
- den Blocknamen
- die erlaubten Attribute
- eine serverseitig generierte Signatur
Der Endpunkt rendert nur, wenn:
- der Block registriert ist
- der Block ein dynamischer WordPress-Block ist
- der Block als dynamisches Blockstudio-Island markiert ist
- die eingehenden Attribute dem Blockschema und der Island-Erlaubnisliste entsprechen
- die Signatur mit dem normalisierten Blocknamen und den Attributen übereinstimmt
Signaturen werden zur Renderzeit auf der ausliefernden WordPress-Website anhand der Salts dieser Website und der Island-Nutzdaten generiert. Sie werden weder exportiert noch in ein Theme eingebettet.
Endpunktantworten sind als nicht cachebar gekennzeichnet. Wenn du Fragment-Caching möchtest, verwende island.cache.
Fragment-Caching
Dynamische Fragmente werden standardmäßig nicht gecacht.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true verwendet einen kurzen globalen Cache. Verwende für eine genaue Steuerung die Objektform:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" teilt sich ein gecachtes Fragment für denselben Block, dieselben Attribute und denselben optionalen Seitenkontext.
per: "user" variiert den Cache anhand der aktuellen Benutzer-ID von WordPress.
Programmgesteuertes Rendering
Islands funktionieren überall dort, wo Blockstudio-Blöcke gerendert werden:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Sie funktionieren auch über Block-Tags:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Die anfängliche Ausgabe enthält weiterhin den Island-Marker und den Platzhalter. Die Laufzeit wird eingefügt, wenn die gerenderte Antwort diesen Marker enthält.
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() validiert Block-Metadaten. Dynamische Marker werden nur für registrierte dynamische Blockstudio-Blöcke erstellt, bei denen island.mode auf dynamic gesetzt ist.
Hooks
Erkennung und Markup:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpunkt und Rendering:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request legt die maximale Anzahl dynamischer Islands fest, die eine gebündelte Endpunktanfrage akzeptiert. Der Standardwert ist 50.
Laufzeitkonfiguration:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Signaturen:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Lebenszyklus-Aktionen:
blockstudio/islands/registered
blockstudio/islands/rendered
Wann du Islands nicht verwenden solltest
Verwende kein dynamisches Island für SEO-kritische Inhalte. Dynamische Island-Fragmente sind nicht im anfänglichen HTML enthalten und sollen nicht indexiert werden.
Verwende normales Rendering oder ein hydratisiertes Island, wenn der Inhalt cache-sicher ist und für Crawler sichtbar sein soll. Verwende ein dynamisches Island nur für Inhalte, die nach der Seitenhülle geladen werden können, etwa Kontodaten UI, Warenkorbstatus, personalisierte Empfehlungen oder zugriffsbeschränkte Steuerelemente.