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.
{
"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.
{
"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:
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.
{
"blockstudio": {
"island": true
}
}
true e "hydrate" significam hidratada. "dynamic" significa dinâmica.
{
"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:
{
"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:
- o caminho explícito
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- o template normal com sinalizadores de espaço reservado
<div class="cart-count-placeholder">
Loading cart...
</div>
Se não houver arquivo de espaço reservado, use os sinalizadores do template normal:
<?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:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
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:
- coleta todos os marcadores prontos
- elimina pares idênticos de nome de bloco, atributos e assinatura
- envia uma solicitação REST em lote
- substitui cada espaço reservado pelo fragmento retornado
- envia
blockstudio:island:rendered - 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:
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.
{
"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:
{
"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:
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:
<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
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:
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:
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:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Assinaturas:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Ações do ciclo de vida:
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.