Pular para o conteúdo

Ilhas

As ilhas de blocos permitem que um bloco mantenha o pipeline normal de renderização Blockstudio, enquanto transfere a saída específica da solicitação para fora da resposta HTML inicial.

Isso é útil quando uma página deve ser armazenada agressivamente em cache, mas um bloco ainda depende do visitante atual, da sessão, do carrinho, das permissões ou de outro contexto de solicitação em tempo real.

Os blocos Blockstudio continuam sendo blocos WordPress dinâmicos. As ilhas não os transformam em HTML estáticos pré-compilados. Em vez disso, Blockstudio altera o que é renderizado na primeira solicitação:

  • ilhas hidratadas renderizam o HTML normal, seguro para cache, e recebem um evento de montagem
  • ilhas dinâmicas renderizam primeiro um espaço reservado seguro para cache e, em seguida, buscam o fragmento real no navegador do visitante

Modos

Ilhas hidratadas

Use uma ilha hidratada quando a saída do servidor for segura para cache e o bloco precisar apenas de um sinal de montagem no frontend.

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

O HTML completo do bloco está presente na resposta inicial. O runtime da ilha não faz uma solicitação REST para buscá-lo. Ele envia blockstudio:island:hydrate no marcador para que o código do frontend possa associar o comportamento.

Ilhas dinâmicas

Use uma ilha dinâmica quando a saída real do bloco precisar ser renderizada no contexto da solicitação do visitante.

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

A resposta inicial contém apenas um espaço reservado. O navegador agrupa todas as ilhas dinâmicas prontas em uma única solicitação para:

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

O endpoint renderiza apenas blocos Blockstudio registrados que sejam dinâmicos e tenham blockstudio.island.mode definido como dynamic.

Configuração

O valor island pode ser uma forma abreviada ou um objeto.

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

true e "hydrate" significam hidratada. "dynamic" significa dinâmica.

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "section",
      "attributes": ["productId", "variant"],
      "placeholder": "cart-placeholder.php",
      "loading": "visible",
      "event": "cart:updated",
      "cache": {
        "ttl": 60,
        "per": "user"
      }
    }
  }
}
Propriedade Tipo Padrão Descrição
mode "hydrate" ou "dynamic" "hydrate" Modo de ilha.
tag string "div" Tag wrapper do marcador.
attributes string[] todos os atributos do bloco Lista de permissões de atributos enviada às solicitações de fragmentos dinâmicos.
placeholder string detectado automaticamente Caminho relativo do modelo de placeholder.
loading "eager" ou "visible" "eager" Quando o runtime deve buscar uma ilha dinâmica.
event string não definido Nome do evento da janela que atualiza uma ilha dinâmica.
context boolean false Assina e restaura o ID e o tipo de publicação da página consultada para fragmentos dinâmicos.
cache boolean ou object false Política opcional de cache de fragmentos.

Contexto da página

Normalmente, os fragmentos dinâmicos são renderizados independentemente da estrutura da página. Ative a identidade da página se o bloco usar configurações específicas da página ou conteúdo relacionado:

JSON
{
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "context": true,
      "cache": { "ttl": 60, "per": "global" }
    }
  }
}

O marcador inclui o postId e o postType da página consultada em data-bs-island-context. Ambos os valores são assinados com o nome do bloco e os atributos permitidos, usando o segredo do site que os fornece. Não é possível alterá-los nem adicioná-los a uma solicitação sem invalidar a assinatura. O runtime os envia junto com a solicitação de fragmentos em lote existente, incluindo atualizações visíveis e acionadas por eventos. Isso também funciona com bs_render_block(), bs_block() e tags de bloco.

Durante a renderização de fragmentos, $block['postId'], $block['postType'], get_the_ID() e get_queried_object_id() fazem referência a essa página. As variáveis globais WordPress de consulta e de publicação são restauradas depois, inclusive se ocorrer uma exceção durante a renderização. Esta é a página consultada, não um item dentro de um Query Loop. Não reproduz parâmetros arbitrários de URL nem restaura o URL da solicitação original. Use get_permalink($block['postId']) quando precisar do URL canônico da página HTML. Arquivos e renderizações sem uma publicação consultada não enviam identidade da página.

O endpoint verifica se a página ainda existe, se tem o tipo de publicação assinado e se pode ser lida pelo visitante atual antes de consultar o cache de fragmentos. Uma assinatura válida não ignora a proteção de publicações privadas ou por senha, os critérios de elegibilidade de ilhas, as listas de permissões de atributos nem as próprias verificações de permissão do bloco. Quando presente, a identidade da página sempre faz parte da chave do cache de fragmentos; assim, o mesmo bloco e os mesmos atributos em páginas diferentes nunca compartilham um fragmento. Use per: "user" ou nenhum cache de fragmentos quando a saída também depender do visitante.

Se context for omitido ou for false, os marcadores existentes e o comportamento independente do contexto permanecem inalterados. Não inclua dados confidenciais no marcador público.

Espaços reservados dinâmicos

Ilhas dinâmicas devem renderizar um espaço reservado seguro para um cache compartilhado de página inteira. Não inclua dados específicos do visitante no ramo do espaço reservado.

Blockstudio procura espaços reservados nesta ordem:

  1. o caminho explícito island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. o template normal com sinalizadores de espaço reservado
PHP
<div class="cart-count-placeholder">
  Loading cart...
</div>

Se não houver arquivo de espaço reservado, use os sinalizadores do template normal:

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

Os mesmos valores estão disponíveis nos templates PHP, Twig e Blade:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

islandPhase é "normal", "hydrate", "placeholder" ou "fragment".

Comportamento do runtime

Blockstudio injeta o runtime das ilhas somente quando a página renderizada contém um marcador de ilha. Páginas sem ilhas não incluem JavaScript adicional de ilha.

Para ilhas dinâmicas, o runtime:

  1. coleta todos os marcadores prontos
  2. elimina pares idênticos de nome de bloco, atributos e assinatura
  3. envia uma solicitação REST em lote
  4. substitui cada espaço reservado pelo fragmento retornado
  5. envia blockstudio:island:rendered
  6. envia blockstudio:island:hydrate

Ilhas loading: "eager" são renderizadas assim que o runtime é iniciado. Ilhas loading: "visible" aguardam IntersectionObserver. Se várias ilhas visíveis entrarem na área de visualização ao mesmo tempo, elas serão agrupadas em uma única solicitação.

event atualiza uma ilha quando o evento de janela indicado é disparado:

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

Em caso de falha, o espaço reservado permanece no lugar e é enviado blockstudio:island:error.

Endpoint de fragmentos

O endpoint da ilha é público, mas não é uma API genérica de renderização de blocos.

Cada marcador contém:

  • o nome do bloco
  • os atributos permitidos
  • uma assinatura gerada pelo servidor

O endpoint só renderiza quando:

  • o bloco está registrado
  • o bloco é um bloco WordPress dinâmico
  • o bloco está marcado como uma ilha Blockstudio dinâmica
  • os atributos recebidos passam pelo esquema do bloco e pela lista de atributos permitidos da ilha
  • a assinatura corresponde ao nome normalizado do bloco e aos atributos

As assinaturas são geradas no momento da renderização no site WordPress que atende à solicitação, usando os salts desse site e o conteúdo da ilha. Elas não são exportadas nem incorporadas a um tema.

As respostas do endpoint são marcadas como não armazenáveis em cache. Para armazenar fragmentos em cache, use island.cache.

Cache de fragmentos

Por padrão, os fragmentos dinâmicos não são armazenados em cache.

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

true usa um cache global de curta duração. Use a forma de objeto para ter controle explícito:

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

per: "global" compartilha um fragmento em cache para o mesmo bloco, atributos e contexto de página com adesão explícita. per: "user" varia o cache de acordo com o ID do usuário WordPress atual.

Renderização programática

As ilhas funcionam em qualquer lugar onde blocos Blockstudio sejam renderizados:

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

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

Elas também funcionam por meio de tags de bloco:

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

A saída inicial continua sendo o marcador da ilha e o espaço reservado, e o runtime é injetado quando a resposta renderizada contém esse marcador.

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() valida os metadados do bloco. Marcadores dinâmicos são criados somente para blocos Blockstudio dinâmicos registrados com island.mode definido como dynamic.

Hooks

Detecção e marcação:

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

Endpoint e renderização:

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

blockstudio/islands/max_per_request altera o número máximo de ilhas dinâmicas aceitas por uma solicitação em lote ao endpoint. O padrão é 50.

Configuração do runtime:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Assinaturas:

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

Ações do ciclo de vida:

PHP
blockstudio/islands/registered
blockstudio/islands/rendered

Quando não usar ilhas

Não use uma ilha dinâmica para conteúdo SEO crítico. Os fragmentos de ilhas dinâmicas não estão presentes na resposta HTML inicial e não foram feitos para serem indexados.

Use a renderização normal ou uma ilha hidratada quando o conteúdo for seguro para cache e precisar ficar visível para os rastreadores. Use uma ilha dinâmica somente para conteúdo que possa chegar depois da estrutura da página, como UI da conta, estado do carrinho, recomendações personalizadas ou controles com acesso restrito por permissões.