Przejdź do treści

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.

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

JSON
{
  "name": "acme/cart-count",
  "blockstudio": {
    "island": "dynamic"
  }
}

Początkowa odpowiedź zawiera tylko placeholder. Przeglądarka łączy wszystkie gotowe dynamiczne wyspy w jednym żądaniu do:

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

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

true i "hydrate" oznaczają uwodnione wyspy. "dynamic" oznacza wyspy dynamiczne.

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

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

  1. jawna ścieżka island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. zwykły szablon z flagami placeholdera
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Jeśli plik placeholdera nie istnieje, użyj flag szablonu w zwykłym szablonie:

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

Te same wartości są dostępne w szablonach PHP, Twig i Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. zbiera wszystkie gotowe znaczniki
  2. usuwa duplikaty identycznych par: nazwy bloku, atrybutów i sygnatury
  3. wysyła jedno zbiorcze żądanie REST
  4. zastępuje każdy placeholder zwróconym fragmentem
  5. wysyła zdarzenie blockstudio:island:rendered
  6. 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:

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

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

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

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

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

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() sprawdza metadane bloku. Znaczniki dynamiczne są tworzone tylko dla zarejestrowanych bloków dynamicznych Blockstudio z island.mode ustawionym na dynamic.

Hooki

Wykrywanie i znaczniki:

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

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

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Sygnatury:

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

Akcje cyklu życia:

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