Wyspy
Wyspy bloków pozwalają zachować standardowy potok renderowania Blockstudio, a jednocześnie przenieść dane zależne od żądania poza początkową odpowiedź HTML.
Przydaje się to, gdy strona powinna być intensywnie buforowana, ale jeden blok nadal zależy od bieżącego odwiedzającego, sesji, koszyka, uprawnień lub innego kontekstu aktywnego żądania.
Bloki Blockstudio nadal są dynamicznymi blokami WordPress. Wyspy nie przekształcają ich w wstępnie skompilowane statyczne HTML. Zmieniają natomiast to, co jest renderowane podczas pierwszego żądania: Blockstudio
- uwodnione wyspy renderują zwykłe HTML bezpieczne dla pamięci podręcznej i otrzymują zdarzenie montowania
- dynamiczne wyspy najpierw renderują placeholder bezpieczny dla pamięci podręcznej, a następnie pobierają rzeczywisty fragment z przeglądarki odwiedzającego
Tryby
Uwodnione wyspy
Użyj uwodnionej wyspy, gdy wynik serwera można bezpiecznie buforować, a blok potrzebuje jedynie sygnału montowania na frontendzie.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Pełny HTML bloku znajduje się w początkowej odpowiedzi. Mechanizm wysp nie wysyła w tym celu żądania REST. Wysyła zdarzenie blockstudio:island:hydrate na znaczniku, aby kod frontendowy mógł dodać zachowanie.
Dynamiczne wyspy
Użyj dynamicznej wyspy, gdy rzeczywisty wynik bloku musi zostać wyrenderowany w kontekście żądania odwiedzającego.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Początkowa odpowiedź zawiera tylko placeholder. Przeglądarka łączy wszystkie gotowe dynamiczne wyspy w jednym żądaniu do:
POST /wp-json/blockstudio/v1/island/render
Punkt końcowy renderuje tylko zarejestrowane bloki Blockstudio, które są dynamiczne i mają blockstudio.island.mode ustawione na dynamic.
Konfiguracja
Wartość island może być skróconym zapisem lub obiektem.
{
"blockstudio": {
"island": true
}
}
true i "hydrate" oznaczają uwodnione wyspy. "dynamic" oznacza wyspy dynamiczne.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Właściwość | Typ | Domyślnie | Opis |
|---|---|---|---|
mode |
"hydrate" lub "dynamic" |
"hydrate" |
Tryb wyspy. |
tag |
string |
"div" |
Tag otaczający znacznik. |
attributes |
string[] |
wszystkie atrybuty bloku | Lista dozwolonych atrybutów wysyłana do żądań fragmentu dynamicznego. |
placeholder |
string |
wykrywana automatycznie | Ścieżka względna do szablonu zastępczego. |
loading |
"eager" lub "visible" |
"eager" |
Kiedy środowisko wykonawcze ma pobierać dynamiczną wyspę. |
event |
string |
nieustawiona | Nazwa zdarzenia okna odświeżającego dynamiczną wyspę. |
context |
boolean |
false |
Podpisuje i przywraca ID oraz typ wpisu odpytywanej strony dla fragmentów dynamicznych. |
cache |
boolean lub object |
false |
Opcjonalna polityka buforowania fragmentów. |
Kontekst strony
Fragmenty dynamiczne są zwykle renderowane niezależnie od powłoki strony. Włącz używanie tożsamości strony, jeśli blok odczytuje ustawienia specyficzne dla strony lub powiązaną z nią treść:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Znacznik zawiera postId i postType odpytywanej strony w data-bs-island-context. Obie wartości są podpisane nazwą bloku i dozwolonymi atrybutami przy użyciu klucza tajnego witryny obsługującej żądanie. Nie można ich zmienić ani dodać do żądania bez unieważnienia podpisu. Środowisko wykonawcze wysyła je wraz z istniejącym zbiorczym żądaniem fragmentów, również podczas odświeżania widocznych elementów i odświeżania wywoływanego zdarzeniami. Działa to również z bs_render_block(), bs_block() i tagami bloków.
Podczas renderowania fragmentu $block['postId'], $block['postType'], get_the_ID() i get_queried_object_id() odnoszą się do tej strony. Następnie przywracane są globalne zmienne zapytania i wpisu WordPress, również po wyjątku podczas renderowania. Chodzi o odpytywaną stronę, a nie element wewnątrz pętli Query Loop. Nie odtwarza to dowolnych parametrów URL ani nie przywraca pierwotnego żądania URL. Użyj get_permalink($block['postId']), gdy potrzebujesz kanonicznego URL strony HTML. Archiwa i renderowania bez odpytywanego wpisu nie wysyłają tożsamości strony.
Punkt końcowy sprawdza, czy strona nadal istnieje, ma podpisany typ wpisu i może być odczytana przez bieżącego użytkownika, zanim sprawdzi pamięć podręczną fragmentów. Prawidłowy podpis nie omija ochrony wpisów prywatnych ani hasłem, wymagań dotyczących kwalifikowania do wyspy, list dozwolonych atrybutów ani własnych kontroli uprawnień bloku. Gdy tożsamość strony jest dostępna, zawsze stanowi część klucza pamięci podręcznej fragmentu, więc ten sam blok i atrybuty na różnych stronach nigdy nie współdzielą fragmentu. Użyj per: "user" lub wyłącz buforowanie fragmentów, jeśli wynik zależy również od użytkownika.
Gdy pominięto context lub użyto false, istniejące znaczniki i zachowanie niezależne od kontekstu pozostają bez zmian. Nie umieszczaj poufnych danych w publicznym znaczniku.
Dynamiczne placeholdery
Dynamiczne wyspy powinny renderować placeholder, który można bezpiecznie umieścić we współdzielonej pamięci podręcznej całej strony. Nie umieszczaj danych zależnych od odwiedzającego w gałęzi placeholdera.
Blockstudio szuka placeholderów w następującej kolejności:
- jawna ścieżka
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- zwykły szablon z flagami placeholdera
<div class="cart-count-placeholder">
Loading cart...
</div>
Jeśli plik placeholdera nie istnieje, użyj flag szablonu w zwykłym szablonie:
<?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; ?>
Te same wartości są dostępne w szablonach PHP, Twig i Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase to "normal", "hydrate", "placeholder" lub "fragment".
Działanie środowiska wykonawczego
Blockstudio dołącza środowisko wykonawcze wysp tylko wtedy, gdy wyrenderowana strona zawiera znacznik wyspy. Strony bez wysp nie przesyłają dodatkowego JavaScript wysp.
W przypadku dynamicznych wysp środowisko wykonawcze:
- zbiera wszystkie gotowe znaczniki
- usuwa duplikaty identycznych par: nazwy bloku, atrybutów i sygnatury
- wysyła jedno zbiorcze żądanie REST
- zastępuje każdy placeholder zwróconym fragmentem
- wysyła zdarzenie
blockstudio:island:rendered - wysyła zdarzenie
blockstudio:island:hydrate
Wyspy loading: "eager" są renderowane zaraz po uruchomieniu środowiska wykonawczego. Wyspy loading: "visible" czekają na IntersectionObserver. Jeśli kilka widocznych wysp pojawi się jednocześnie w obszarze widoku, zostaną połączone w jedno żądanie.
event odświeża wyspę po wywołaniu nazwanego zdarzenia okna:
window.dispatchEvent(new Event('cart:updated'));
W razie błędu placeholder pozostaje na miejscu, a system wysyła zdarzenie
blockstudio:island:error.
Punkt końcowy fragmentów
Punkt końcowy wysp jest publiczny, ale nie służy do ogólnego API renderowania bloków.
Każdy znacznik zawiera:
- nazwę bloku
- atrybuty z listy dozwolonych
- sygnaturę wygenerowaną przez serwer
Punkt końcowy renderuje zawartość tylko wtedy, gdy:
- blok jest zarejestrowany
- blok jest dynamicznym blokiem WordPress
- blok jest oznaczony jako dynamiczna wyspa Blockstudio
- przychodzące atrybuty spełniają wymagania schematu bloku i listy dozwolonych atrybutów wyspy
- sygnatura pasuje do znormalizowanej nazwy bloku i atrybutów
Sygnatury są generowane podczas renderowania w obsługującej witrynie WordPress na podstawie soli tej witryny i danych wyspy. Nie są eksportowane ani wbudowywane w motyw.
Odpowiedzi punktu końcowego są oznaczane jako nieprzeznaczone do buforowania. Aby buforować fragmenty, użyj island.cache.
Buforowanie fragmentów
Dynamiczne fragmenty domyślnie nie są buforowane.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true korzysta z krótkotrwałej pamięci podręcznej globalnej. Użyj formy obiektu, aby jawnie określić ustawienia:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" współdzieli jeden buforowany fragment dla tego samego bloku, atrybutów i
kontekstu strony z włączoną opcją.
per: "user" zmienia klucz pamięci podręcznej w zależności od bieżącego identyfikatora użytkownika WordPress.
Renderowanie programowe
Wyspy działają wszędzie tam, gdzie renderowane są bloki Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Działają również za pośrednictwem znaczników bloków:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
Wynikiem początkowym nadal jest znacznik wyspy i placeholder, a środowisko wykonawcze jest dołączane, gdy wyrenderowana odpowiedź zawiera ten znacznik.
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() sprawdza metadane bloku. Znaczniki dynamiczne są tworzone tylko dla zarejestrowanych bloków dynamicznych Blockstudio z island.mode ustawionym na dynamic.
Hooki
Wykrywanie i znaczniki:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Punkt końcowy i renderowanie:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request zmienia maksymalną liczbę dynamicznych wysp przyjmowanych przez jedno zbiorcze żądanie punktu końcowego. Wartość domyślna to 50.
Konfiguracja środowiska wykonawczego:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Sygnatury:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Akcje cyklu życia:
blockstudio/islands/registered
blockstudio/islands/rendered
Kiedy nie używać wysp
Nie używaj dynamicznej wyspy do treści kluczowych dla SEO. Fragmenty dynamicznych wysp nie są obecne w początkowym HTML i nie są przeznaczone do indeksowania.
Użyj zwykłego renderowania lub uwodnionej wyspy, gdy treść można bezpiecznie buforować i powinna być widoczna dla robotów indeksujących. Używaj dynamicznej wyspy tylko dla treści, które mogą pojawić się po załadowaniu powłoki strony, takich jak UI konta, stan koszyka, spersonalizowane rekomendacje lub kontrolki dostępne po uzyskaniu uprawnień.