Персонализированные фрагменты на кэшируемых страницах
Страница, отданная из статического кэша, одинакова для всех. В этом и состоит смысл кэширования, но это же создает проблему: в шапке нужно написать «Привет, Ada» для вошедшего пользователя, а на значке корзины показать три товара. Если шаблон проверяет текущего пользователя, кэш либо сохранит приветствие одного посетителя для всех, либо страницу придется полностью исключить из кэша.
Динамические островки Blockstudio разделяют эти задачи. Кэшированный HTML содержит безопасную для кэша заглушку. После загрузки страницы небольшая среда выполнения запрашивает у WordPress персональный фрагмент в рамках собственного запроса посетителя и подставляет его. Страница остается пригодной для кэширования, а динамическим остается только фрагмент.
В этом руководстве мы создадим два островка: приветствие и счетчик корзины, а также разберем содержимое кэшированной страницы, формат запроса фрагмента и то, как эндпоинт определяет посетителя. Руководство дополняет раздел Подача WordPress в виде статики HTML.
Как работает динамический островок
- Блок выводит заглушку внутри элемента-маркера. Маркер содержит имя блока, список разрешенных атрибутов и подпись, созданную сервером.
- Поскольку отрендеренная страница содержит маркер, Blockstudio подключает среду выполнения островков. На страницах без островков ресурсы островков JavaScript не загружаются.
- Среда выполнения собирает готовые маркеры и отправляет один пакетный
POSTв/wp-json/blockstudio/v1/island/render. - Эндпоинт проверяет подпись каждого маркера, выводит блок в контексте запроса посетителя и возвращает фрагменты.
- Среда выполнения заменяет каждую заглушку и отправляет события.
В редакторе блоков блок отображается обычным образом, без заглушки.
Шаг 1: блок приветствия
Создайте блок из трех файлов:
blocks/
└── greeting/
├── block.json
├── placeholder.php
└── index.php
{
"apiVersion": 3,
"name": "acme/greeting",
"title": "Greeting",
"category": "widgets",
"icon": "admin-users",
"description": "Account link that greets signed-in visitors.",
"blockstudio": {
"island": {
"mode": "dynamic",
"tag": "span",
"attributes": ["guestLabel"],
"cache": {
"ttl": 300,
"per": "user"
}
},
"attributes": [
{ "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
]
}
}
mode: "dynamic" превращает блок в островок с запросом фрагмента.
tag задает элемент-маркер, благодаря чему островок можно встроить в строку панели навигации. attributes — список разрешенных атрибутов блока, передаваемых вместе с запросом фрагмента; неуказанные атрибуты не отправляются и не подписываются. cache описан ниже.
Кэшированная страница содержит заглушку. Она должна быть безопасной для показа любому посетителю, поэтому не содержит пользовательских данных. Ссылка «Аккаунт» подходит всем:
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>
Основной шаблон выводит настоящий фрагмент:
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
<?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
</a>
<?php else : ?>
<a href="<?php echo esc_url( wp_login_url() ); ?>">
<?php echo esc_html( $a['guestLabel'] ); ?>
</a>
<?php endif; ?>
Здесь можно проверять текущего пользователя: этот шаблон выполняется только для запроса фрагмента, но не для кэшированной страницы.
Разместите его там, где выводится шапка:
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>
Подойдут и теги блоков: <bs:acme-greeting /> или
<block name="acme/greeting" />.
Шаг 2: содержимое кэшированной страницы
После серверного рендеринга блок выводит только маркер и заглушку:
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{"guestLabel":"Sign in"}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>
Выполните рендеринг один раз для анонимного посетителя и один раз для вошедшего пользователя — обе строки побайтно совпадут. Именно это свойство необходимо статическому пререндерингу с включенным параметром serveLoggedIn: независимо от того, кто запустил рендеринг, сохраненный документ одинаков, и в него не попадут персональные данные.
Шаг 3: запрос фрагмента
Среда выполнения отправляет все готовые островки одним запросом:
{
"islands": [
{
"clientId": "a1",
"name": "acme/greeting",
"attributes": {
"guestLabel": "Sign in"
},
"signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
}
]
}
Ответы индексируются по clientId. Для вошедшего пользователя:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/account/\">\n Hi, Ada </a>\n"
}
Если запись не прошла проверку, вместо HTML возвращается код ошибки, но обработка остальных записей пакета продолжается. Здесь во второй записи изменили guestLabel без соответствующей подписи, а в третьей указали блок, который не является динамическим островком:
{
"a1": "<!--blockstudio/acme/greeting--> <a href=\"https://example.com/wp-login.php\">\n Sign in </a>\n",
"a2": {
"error": "blockstudio_island_invalid_signature"
},
"a3": {
"error": "blockstudio_island_not_allowed"
}
}
В каждом ответе передаются Cache-Control: no-store, no-cache, must-revalidate, max-age=0,
Pragma: no-cache и X-Robots-Tag: noindex. Эндпоинт находится в /wp-json, который статический пререндеринг всегда обходит, поэтому ни исходный кэш, ни CDN, соблюдающий заголовки источника, не сохранят фрагмент.
Кто является посетителем
Среда выполнения отправляет запрос с credentials: 'same-origin', поэтому браузер включает файл cookie входа WordPress. WordPress REST API обычно игнорирует аутентификацию по файлу cookie без nonce, а nonce нельзя поместить в кэшированную страницу. Эндпоинт островка обрабатывает это самостоятельно: для браузерного запроса с того же источника он проверяет файл cookie logged_in и восстанавливает пользователя перед рендерингом.
Запрос считается отправленным с того же источника по заголовку Sec-Fetch-Site и, если он присутствует, по заголовку Origin, сопоставленному с home_url(). Запрос с другого источника, даже если в нем передан файл cookie, обрабатывается как анонимный, поэтому сайт никогда не выведет персональный фрагмент посетителя для запроса с другого сайта. На практике:
| Запрос | Выводится как |
|---|---|
| Запрос fetch с того же источника и действительным файлом cookie входа | вошедший пользователь |
| Запрос с другого источника с тем же файлом cookie | анонимный посетитель |
| Без файла cookie | анонимный посетитель |
Какая это страница?
Добавьте "context": true в blockstudio.island, если фрагменту нужен идентификатор его страницы. Тогда маркер подписывает идентификатор записи и тип записи запрошенной страницы вместе с атрибутами. Во фрагменте $block['postId'], $block['postType'], get_the_ID() и get_queried_object_id() относятся к этой странице. Внутри цикла Query Loop это по-прежнему внешняя запрошенная страница, а не элемент цикла.
Контекст страницы включается по желанию и также входит в ключ кэша фрагмента. Конечная точка повторно проверяет доступ даже для кэшированных фрагментов, поэтому подписанный маркер не откроет страницу, которая с тех пор стала приватной или защищённой паролем. См. Контекст страницы, где описаны настройки и меры безопасности. Произвольные URL или параметры запроса повторно не используются.
Шаг 4: счетчик корзины с автообновлением
Второй островок показывает другой стиль заглушки и два параметра среды выполнения. Вместо отдельного файла заглушки шаблон проверяет $isIslandPlaceholder:
{
"apiVersion": 3,
"name": "acme/cart-count",
"title": "Cart Count",
"category": "widgets",
"icon": "cart",
"description": "Number of items in the visitor's cart.",
"blockstudio": {
"island": {
"mode": "dynamic",
"loading": "visible",
"event": "acme:cart-updated"
},
"attributes": []
}
}
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
<a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
<a href="/cart/" class="cart-count">
Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
</a>
<?php endif; ?>
Во всех языках шаблонов доступны одинаковые флаги: isIsland,
isIslandPlaceholder, isIslandFragment и islandPhase ("normal",
"hydrate", "placeholder" или "fragment"). Здесь количество берется из фильтра acme/cart_count, значение которого задает код электронной коммерции. Если он возвращает 3, эндпоинт возвращает:
{"c1":"<!--blockstudio/acme/cart-count--> <a href=\"/cart/\" class=\"cart-count\">\n Cart <span class=\"cart-count__badge\">3</span>\n </a>\n"}
loading: "visible" откладывает запрос до появления маркера в области просмотра, используя IntersectionObserver. Видимые островки, появившиеся одновременно, все равно объединяются в один запрос. event задает имя события окна, которое повторно загружает островок. Поэтому после добавления товара в корзину вашему скрипту достаточно отправить это событие:
window.dispatchEvent(new Event('acme:cart-updated'));
Реакция в коде внешней части сайта
События всплывают от маркера, поэтому одного обработчика на document достаточно для всех островов. event.detail.name содержит имя блока:
document.addEventListener('blockstudio:island:rendered', (event) => {
if (event.detail.name !== 'acme/cart-count') return;
event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});
document.addEventListener('blockstudio:island:error', (event) => {
console.warn('Island failed', event.detail.name, event.detail.error);
});
После замены среда выполнения отправляет blockstudio:island:rendered, затем blockstudio:island:hydrate. При сбое заполнитель остается на месте и срабатывает blockstudio:island:error. Гидратированные острова ("island": "hydrate") полностью пропускают запрос: весь HTML уже есть на странице, и они получают только событие hydrate, что подходит для интерактивных блоков, безопасных для кэширования, например вкладок.
Кэширование фрагментов
По умолчанию фрагменты отображаются при каждом запросе. Приветствие выше использует короткое кэширование:
{
"cache": {
"ttl": 300,
"per": "user"
}
}
per: "user" разделяет кэшированный фрагмент по ID пользователя WordPress, а анонимные запросы при этом не кэшируются, поэтому два анонимных посетителя не могут получить одну запись, предназначенную для пользователя. per: "global" использует один фрагмент для того же блока с теми же атрибутами, что подходит для актуального, но неперсонального содержимого, например уровня запасов. По умолчанию ttl задает 60 секунд, а cache: true — глобальный кэш на 60 секунд.
Модель безопасности
Конечная точка общедоступна, но она не предназначена для общего отображения блоков. Она отображает запись, только если выполнены все условия:
- блок зарегистрирован, является динамическим, и для
island.modeзадано значениеdynamic - подпись соответствует имени блока и атрибутам, прошедшим фильтр: учитываются только ключи, присутствующие и в схеме блока, и в списке разрешенных для острова
Подпись — это HMAC-SHA256 для нормализованного имени блока и атрибутов, вычисленная с использованием соли auth сайта, обслуживающего запрос. Подписи создаются при отображении на этом сайте и никогда не встраиваются в тему. Отсюда следуют два вывода. Документ, отображенный на тестовом сервере, содержит подписи тестового сервера, поэтому отображайте документы на сайте, который их обслуживает. А при смене солей WordPress все подписи в сохраненных документах становятся недействительными, поэтому после смены соли очистите статически предварительно отображенные страницы.
Один запрос принимает до 50 островов; при большем количестве возвращается HTTP 413. Измените ограничение с помощью blockstudio/islands/max_per_request. Для хостов, которым нужна другая схема, предусмотрены хуки подписи (blockstudio/islands/signature_payload, blockstudio/islands/signature, blockstudio/islands/verify_signature).
Когда не следует использовать остров
Фрагменты отсутствуют в первоначальном HTML, поэтому поисковые роботы их не видят. Содержимое, важное для SEO, оставляйте в обычном отображении. Используйте динамические острова для того, что может появиться после оболочки страницы: ссылок на аккаунт, состояния корзины, рекомендаций и элементов управления с ограниченным доступом. Если вся страница персональная, например панель аккаунта, укажите ее путь в dynamicPaths и отображайте ее динамически.
Следующие шаги
- Справочник по островам: все параметры, порядок поиска заполнителей, PHP API и хуки.
- Обслуживание WordPress как статического HTML: кэш, для которого предназначены эти острова.
- Справочник по статическому предварительному отображению:
serveLoggedIn, динамические пути и раннее обслуживание. - Интерактивные компоненты: поведение на стороне клиента для блоков, которым недостаточно события монтирования.