Към съдържанието

Острови

Островите на блокове позволяват на блок да запази обичайния процес на визуализиране Blockstudio, като изнасят специфичния за заявката изход извън първоначалния отговор HTML.

Това е полезно, когато страницата трябва да се кешира интензивно, но един от блоковете зависи от текущия посетител, сесията, количката, разрешенията или друг контекст на текущата заявка.

Блоковете Blockstudio продължават да бъдат динамични блокове WordPress. Островите не ги превръщат в предварително компилирани статични HTML. Вместо това Blockstudio променя начина на визуализиране при първата заявка:

  • хидратираните острови визуализират обичайния си безопасен за кеширане HTML и получават събитие за монтиране
  • динамичните острови първо визуализират безопасен за кеширане заместител, след което извличат реалния фрагмент от браузъра на посетителя

Режими

Хидратирани острови

Използвайте хидратиран остров, когато изходът от сървъра е безопасен за кеширане и блокът се нуждае само от сигнал за монтиране във фронтенда.

JSON
{
  "name": "acme/tabs",
  "blockstudio": {
    "island": "hydrate"
  }
}

Пълният HTML на блока присъства в първоначалния отговор. Средата за изпълнение на островите не изпраща REST заявка за него. Тя задейства blockstudio:island:hydrate върху маркера, за да може кодът във фронтенда да прикачи поведение.

Динамични острови

Използвайте динамичен остров, когато реалният изход на блока трябва да се визуализира в контекста на заявката на посетителя.

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

Първоначалният отговор съдържа само заместител. Браузърът обединява всички готови динамични острови в една заявка към:

Text
POST /wp-json/blockstudio/v1/island/render

Крайната точка визуализира само регистрирани блокове Blockstudio, които са динамични и имат blockstudio.island.mode със стойност dynamic.

Конфигурация

Стойността на island може да бъде кратък запис или обект.

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

true и "hydrate" означават хидратиран режим. "dynamic" означава динамичен режим.

JSON
{
  "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 Незадължителна политика за кеширане на фрагменти.

Контекст на страницата

Динамичните фрагменти обикновено се рендират независимо от обвивката на страницата. Използвайте идентичността ѝ, когато блокът ви чете специфични за страницата настройки или свързано съдържание:

JSON
{
  "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 търси заместители в следния ред:

  1. изричния път island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. обичайния шаблон с флагове за заместители
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Ако няма файл за заместителя, използвайте флаговете на шаблона в обичайния си шаблон:

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

Същите стойности са налични в шаблоните PHP, Twig и Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase е "normal", "hydrate", "placeholder" или "fragment".

Поведение на средата за изпълнение

Blockstudio добавя средата за изпълнение на островите само когато визуализираната страница съдържа маркер на остров. Страниците без острови не включват допълнителни ресурси на JavaScript.

За динамичните острови средата за изпълнение:

  1. събира всички готови маркери
  2. премахва дублиращите се двойки с еднакви имена на блокове, атрибути и подписи
  3. изпраща една обединена заявка REST
  4. заменя всеки заместител с върнатия фрагмент
  5. задейства blockstudio:island:rendered
  6. задейства blockstudio:island:hydrate

Островите loading: "eager" се визуализират веднага щом средата за изпълнение стартира. Островите loading: "visible" изчакват IntersectionObserver. Ако няколко видими острова попаднат едновременно в прозореца за визуализация, те се обединяват в една заявка.

event обновява остров при задействане на посоченото събитие на прозореца:

JavaScript
window.dispatchEvent(new Event('cart:updated'));

При неуспешна заявка заместителят остава на мястото си и се задейства blockstudio:island:error.

Крайна точка за фрагменти

Крайната точка на островите е публична, но не е обща крайна точка за визуализиране на блокове API.

Всеки маркер съдържа:

  • името на блока
  • атрибутите от списъка с разрешени
  • генериран от сървъра подпис

Крайната точка визуализира съдържание само когато:

  • блокът е регистриран
  • блокът е динамичен блок WordPress
  • блокът е обозначен като динамичен остров Blockstudio
  • входящите атрибути отговарят на схемата на блока и списъка с разрешени атрибути за острова
  • подписът съвпада с нормализираното име и атрибути на блока

Подписите се генерират по време на визуализирането на обслужващия сайт WordPress, като се използват солите на сайта и данните на острова. Те не се експортират и не се вграждат в тема.

Отговорите на крайната точка са обозначени като некешируеми. Ако искате да кеширате фрагменти, използвайте island.cache.

Кеширане на фрагменти

Динамичните фрагменти не се кешират по подразбиране.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "cache": true
    }
  }
}

true използва краткотраен глобален кеш. Използвайте обектната форма за изричен контрол:

JSON
{
  "cache": {
    "ttl": 120,
    "per": "user"
  }
}

per: "global" споделя един кеширан фрагмент за същия блок, атрибути и контекст на страницата с изрично включено кеширане. per: "user" променя кеша според текущия потребителски ID WordPress.

Програмно визуализиране

Островите работят навсякъде, където се визуализират блокове Blockstudio:

PHP
bs_render_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

echo bs_block([
  'name' => 'acme/cart-count',
  'data' => ['productId' => 42],
]);

Работят и чрез тагове за блокове:

HTML
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />

Първоначалният изход все още съдържа маркера и заместителя на острова, а средата за изпълнение се добавя, когато визуализираният отговор съдържа този маркер.

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() валидира метаданните на блока. Динамични маркери се създават само за регистрирани динамични блокове Blockstudio със island.mode със стойност dynamic.

Куки

Откриване и маркиране:

PHP
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder

Крайна точка и визуализиране:

PHP
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment

blockstudio/islands/max_per_request променя максималния брой динамични острови, приемани в една обединена заявка към крайната точка. Стойността по подразбиране е 50.

Конфигурация на средата за изпълнение:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Подписи:

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

Действия в жизнения цикъл:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Кога да не използвате острови

Не използвайте динамичен остров за съдържание, критично за SEO. Фрагментите на динамичните острови не присъстват в първоначалния HTML и не са предназначени за индексиране.

Използвайте обичайно визуализиране или хидратиран остров, когато съдържанието е безопасно за кеширане и трябва да се вижда от роботите за обхождане. Използвайте динамичен остров само за съдържание, което може да се зареди след обвивката на страницата, например данни за акаунта UI, състояние на количката, персонализирани препоръки или контроли, ограничени с разрешения.