Острова
Острова блоков позволяют сохранить стандартный конвейер рендеринга Blockstudio, перенося вывод, зависящий от запроса, за пределы первоначального ответа HTML.
Это полезно, когда страницу нужно активно кешировать, но один из блоков зависит от текущего посетителя, сеанса, корзины, разрешений или другого контекста текущего запроса.
Блоки Blockstudio по-прежнему являются динамическими блоками WordPress. Острова не превращают их в предварительно скомпилированные статические HTML. Вместо этого Blockstudio меняет способ рендеринга при первом запросе:
- гидратируемые острова отображают обычную безопасную для кеширования HTML и получают событие монтирования
- динамические острова сначала отображают безопасный для кеширования заполнитель, а затем загружают настоящий фрагмент из браузера посетителя
Режимы
Гидратируемые острова
Используйте гидратируемый остров, если вывод сервера безопасно кешировать, а блоку нужен только сигнал монтирования на внешней части сайта.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
Полный HTML блока присутствует в первоначальном ответе. Среда выполнения островов не отправляет для него запрос REST. Она вызывает событие blockstudio:island:hydrate на маркере, чтобы код внешней части сайта мог добавить поведение.
Динамические острова
Используйте динамический остров, если настоящий вывод блока должен быть сформирован с учетом контекста запроса посетителя.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
Первоначальный ответ содержит только заполнитель. Браузер объединяет все готовые динамические острова в один запрос к:
POST /wp-json/blockstudio/v1/island/render
Конечная точка отображает только зарегистрированные блоки Blockstudio, которые являются динамическими и у которых blockstudio.island.mode задано значение dynamic.
Настройка
Значение island может быть сокращенной записью или объектом.
{
"blockstudio": {
"island": true
}
}
true и "hydrate" означают гидратируемый режим. "dynamic" означает динамический режим.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "section",
"attributes": ["productId", "variant"],
"placeholder": "cart-placeholder.php",
"loading": "visible",
"event": "cart:updated",
"cache": {
"ttl": 60,
"per": "user"
}
}
}
}
| Свойство | Тип | По умолчанию | Описание |
|---|---|---|---|
mode |
"hydrate" или "dynamic" |
"hydrate" |
Режим острова. |
tag |
string |
"div" |
Тег обёртки маркера. |
attributes |
string[] |
все атрибуты блока | Список разрешённых атрибутов, передаваемых запросам динамических фрагментов. |
placeholder |
string |
определяется автоматически | Относительный путь к шаблону-заполнителю. |
loading |
"eager" или "visible" |
"eager" |
Когда среде выполнения следует запрашивать динамический остров. |
event |
string |
не задано | Имя события окна, обновляющего динамический остров. |
context |
boolean |
false |
Подписывать и восстанавливать ID записи и тип записи запрошенной страницы для динамических фрагментов. |
cache |
boolean или object |
false |
Необязательная политика кэширования фрагментов. |
Контекст страницы
Динамические фрагменты обычно рендерятся независимо от оболочки страницы. Включите идентификацию страницы, если блок считывает настройки, относящиеся к странице, или связанный контент:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
Маркер включает postId и postType запрошенной страницы в data-bs-island-context. Оба значения подписываются с именем блока и разрешёнными атрибутами с помощью секрета обслуживающего сайта. Их нельзя изменить или добавить в запрос без нарушения подписи. Среда выполнения передаёт их в существующем пакетном запросе фрагментов, включая запросы для видимых фрагментов и обновления, запускаемые событиями. Это также работает с bs_render_block(), bs_block() и тегами блоков.
При рендеринге фрагмента $block['postId'], $block['postType'], get_the_ID() и get_queried_object_id() относятся к этой странице. После этого восстанавливаются глобальные переменные запроса и записи WordPress, в том числе после ошибки рендеринга. Это запрошенная страница, а не элемент внутри Query Loop. При этом произвольные параметры URL не воспроизводятся, а исходный запрос URL не восстанавливается. Используйте get_permalink($block['postId']), если вам нужен канонический URL HTML страницы. Для архивов и рендеринга без запрошенной записи идентификатор страницы не передаётся.
Прежде чем обращаться к кэшу фрагментов, конечная точка проверяет, что страница всё ещё существует, её тип записи совпадает с подписанным и текущий посетитель может её прочитать. Действительная подпись не отменяет защиту частных записей и записей, защищённых паролем, требования к доступности острова, списки разрешённых атрибутов и собственные проверки прав блока. Если идентификатор страницы задан, он всегда входит в ключ кэша фрагмента, поэтому один и тот же блок с одинаковыми атрибутами на разных страницах не использует общий фрагмент. Используйте per: "user" или отключите кэширование фрагментов, если вывод также зависит от посетителя.
Если context не задан или задано значение false, существующие маркеры и поведение без контекста остаются без изменений. Не помещайте конфиденциальные данные в общедоступный маркер.
Динамические заполнители
Динамические острова должны отображать заполнитель, безопасный для общего кеша целых страниц. Не включайте в ветвь заполнителя данные, относящиеся к конкретному посетителю.
Blockstudio ищет заполнители в следующем порядке:
- явно заданный путь
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- обычный шаблон с флагами заполнителя
<div class="cart-count-placeholder">
Loading cart...
</div>
Если файла заполнителя нет, используйте флаги шаблона в обычном шаблоне:
<?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; ?>
В шаблонах PHP, Twig и Blade доступны те же значения:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase — это "normal", "hydrate", "placeholder" или "fragment".
Поведение среды выполнения
Blockstudio подключает среду выполнения островов, только если на отрендеренной странице есть маркер острова. На страницах без островов не загружается дополнительный ресурс островов JavaScript.
Для динамических островов среда выполнения:
- собирает все готовые маркеры
- удаляет дубликаты одинаковых пар имени блока, атрибутов и подписи
- отправляет один объединенный запрос REST
- заменяет каждый заполнитель полученным фрагментом
- вызывает событие
blockstudio:island:rendered - вызывает событие
blockstudio:island:hydrate
Острова loading: "eager" отображаются сразу после запуска среды выполнения. Острова loading: "visible" ждут IntersectionObserver. Если несколько видимых островов одновременно попадают в область просмотра, их запросы объединяются в один.
event обновляет остров при возникновении указанного события окна:
window.dispatchEvent(new Event('cart:updated'));
При сбоях заполнитель остается на месте и вызывается событие
blockstudio:island:error.
Конечная точка фрагментов
Конечная точка островов общедоступна, но она не является универсальным средством рендеринга блоков API.
Каждый маркер содержит:
- имя блока
- атрибуты из списка разрешенных
- подпись, созданную сервером
Конечная точка выполняет рендеринг, только если:
- блок зарегистрирован
- блок является динамическим блоком WordPress
- блок помечен как динамический остров Blockstudio
- входящие атрибуты соответствуют схеме блока и списку разрешенных атрибутов острова
- подпись соответствует нормализованному имени блока и атрибутам
Подписи генерируются во время рендеринга на обслуживающем сайте WordPress из солей этого сайта и данных острова. Они не экспортируются и не встраиваются в тему.
Ответы конечной точки помечаются как не подлежащие кешированию. Для кеширования фрагментов используйте island.cache.
Кеширование фрагментов
Динамические фрагменты по умолчанию не кешируются.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true использует короткосрочный глобальный кеш. Для явной настройки используйте форму объекта:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" использует один кэшированный фрагмент для одного и того же блока, атрибутов и контекста страницы с включенной поддержкой.
per: "user" меняет кэш в зависимости от ID текущего пользователя WordPress.
Программный рендеринг
Острова работают везде, где отображаются блоки Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
Они также работают с помощью тегов блоков:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
В первоначальном выводе по-прежнему присутствуют маркер острова и заполнитель, а среда выполнения подключается, если маркер есть в сформированном ответе.
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() проверяет метаданные блока. Динамические маркеры создаются только для зарегистрированных динамических блоков Blockstudio, у которых island.mode задано значение dynamic.
Хуки
Обнаружение и разметка:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Конечная точка и рендеринг:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request изменяет максимальное число динамических островов, принимаемых одним объединенным запросом к конечной точке. По умолчанию используется значение 50.
Настройка среды выполнения:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Подписи:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Действия жизненного цикла:
blockstudio/islands/registered
blockstudio/islands/rendered
Когда не следует использовать острова
Не используйте динамический остров для содержимого, критичного для SEO. Фрагменты динамических островов отсутствуют в первоначальном HTML и не предназначены для индексации.
Используйте обычный рендеринг или гидратируемый остров, если содержимое безопасно кешировать и оно должно быть видно поисковым роботам. Динамический остров подходит только для содержимого, которое может загрузиться после каркаса страницы, например данных учетной записи UI, состояния корзины, персональных рекомендаций или элементов управления с ограничением по разрешениям.