Islas
Las islas de bloques permiten que un bloque mantenga el proceso de renderizado normal de Blockstudio y, al mismo tiempo, trasladen el contenido específico de la solicitud fuera de la respuesta inicial de HTML.
Esto resulta útil cuando una página debe almacenarse intensivamente en caché, pero un bloque sigue dependiendo del visitante actual, la sesión, el carrito, los permisos u otro contexto activo de la solicitud.
Los bloques Blockstudio siguen siendo bloques WordPress dinámicos. Las islas no los convierten en HTML estáticos precompilados. En cambio, Blockstudio cambia lo que se renderiza en la primera solicitud:
- Las islas hidratadas renderizan su HTML normal y seguro para la caché, y reciben un evento de montaje
- Las islas dinámicas renderizan primero un marcador de posición seguro para la caché y luego obtienen el fragmento real desde el navegador del visitante
Modos
Islas hidratadas
Usa una isla hidratada cuando el resultado del servidor sea seguro para la caché y el bloque solo necesite una señal de montaje en la interfaz pública.
{
"name": "acme/tabs",
"blockstudio": {
"island": "hydrate"
}
}
El HTML completo del bloque está presente en la respuesta inicial. El entorno de ejecución de la isla no realiza una solicitud REST para obtenerlo. Envía blockstudio:island:hydrate al marcador para que el código de la interfaz pública pueda añadirle comportamiento.
Islas dinámicas
Usa una isla dinámica cuando el resultado real del bloque deba renderizarse en el contexto de la solicitud del visitante.
{
"name": "acme/cart-count",
"blockstudio": {
"island": "dynamic"
}
}
La respuesta inicial solo contiene un marcador de posición. El navegador agrupa todas las islas dinámicas listas en una sola solicitud a:
POST /wp-json/blockstudio/v1/island/render
El endpoint solo renderiza bloques Blockstudio registrados que sean dinámicos y tengan blockstudio.island.mode establecido en dynamic.
Configuración
El valor de island puede ser una forma abreviada o un objeto.
{
"blockstudio": {
"island": true
}
}
true y "hydrate" indican que es una isla hidratada. "dynamic" indica que es 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"
}
}
}
}
| Propiedad | Tipo | Valor predeterminado | Descripción |
|---|---|---|---|
mode |
"hydrate" o "dynamic" |
"hydrate" |
Modo isla. |
tag |
string |
"div" |
Etiqueta envolvente del marcador. |
attributes |
string[] |
todos los atributos del bloque | Lista de atributos permitidos que se envía con las solicitudes de fragmentos dinámicos. |
placeholder |
string |
detección automática | Ruta relativa a la plantilla del marcador de posición. |
loading |
"eager" o "visible" |
"eager" |
Cuándo debe el runtime obtener una isla dinámica. |
event |
string |
sin definir | Nombre del evento de ventana que actualiza una isla dinámica. |
context |
boolean |
false |
Firmar y restaurar el ID de entrada y el tipo de entrada de la página consultada para los fragmentos dinámicos. |
cache |
boolean o object |
false |
Política opcional de caché de fragmentos. |
Contexto de la página
Los fragmentos dinámicos normalmente se renderizan de forma independiente del contenedor de la página. Habilita la identidad de la página si tu bloque lee ajustes específicos de la página o contenido relacionado:
{
"blockstudio": {
"island": {
"mode": "dynamic",
"context": true,
"cache": { "ttl": 60, "per": "global" }
}
}
}
El marcador incluye el postId y el postType de la página consultada en data-bs-island-context. Ambos valores se firman con el nombre del bloque y los atributos permitidos mediante el secreto del sitio que los sirve. No se pueden cambiar ni añadir a una solicitud sin invalidar la firma. El runtime los envía con la solicitud de fragmentos por lotes existente, incluidas las actualizaciones visibles y las activadas por eventos. Esto también funciona con bs_render_block(), bs_block() y las etiquetas de bloque.
Durante la renderización de fragmentos, $block['postId'], $block['postType'],
get_the_ID() y get_queried_object_id() hacen referencia a esa página. Después se restauran las variables globales de consulta y de publicación WordPress,
incluso si se produce una excepción durante la renderización.
Esta es la página consultada, no un elemento dentro de un Query Loop. No vuelve a ejecutar
parámetros arbitrarios de URL ni restaura la URL de la solicitud original. Usa
get_permalink($block['postId']) cuando necesites el valor canónico de URL de la página HTML.
Los archivos y las renderizaciones sin una publicación consultada no incluyen la identidad de la página.
El endpoint comprueba que la página siga existiendo, tenga el tipo de entrada firmado y pueda leerla el visitante actual antes de consultar la caché de fragmentos. Una firma válida no omite la protección de entradas privadas o protegidas por contraseña, la elegibilidad de la isla, las listas de atributos permitidos ni las comprobaciones de permisos propias de tu bloque. Si está presente, la identidad de la página siempre forma parte de la clave de caché del fragmento, así que el mismo bloque y los mismos atributos en páginas distintas nunca comparten un fragmento. Usa per: "user" o desactiva la caché de fragmentos cuando la salida también dependa del visitante.
Si se omite context o se usa false, los marcadores existentes y el comportamiento sin contexto no cambian. No incluyas datos confidenciales en el marcador público.
Marcadores de posición dinámicos
Las islas dinámicas deben renderizar un marcador de posición seguro para una caché de página completa compartida. No incluyas datos específicos del visitante en la rama del marcador de posición.
Blockstudio busca marcadores de posición en este orden:
- la ruta explícita
island.placeholder placeholder.phpplaceholder.blade.phpplaceholder.twigplaceholder.html- la plantilla normal con indicadores de marcador de posición
<div class="cart-count-placeholder">
Loading cart...
</div>
Si no existe ningún archivo de marcador de posición, usa los indicadores de plantilla en la plantilla 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; ?>
Los mismos valores están disponibles en las plantillas PHP, Twig y Blade:
isIslandisIslandPlaceholderisIslandFragmentislandPhase
islandPhase es "normal", "hydrate", "placeholder" o "fragment".
Comportamiento del entorno de ejecución
Blockstudio inyecta el entorno de ejecución de la isla solo cuando la página renderizada contiene un marcador de isla. Las páginas sin islas no incluyen recursos JavaScript adicionales de islas.
Para las islas dinámicas, el entorno de ejecución:
- recopila todos los marcadores listos
- elimina los pares duplicados de nombre de bloque, atributos y firma
- envía una solicitud REST agrupada
- sustituye cada marcador de posición por el fragmento recibido
- envía
blockstudio:island:rendered - envía
blockstudio:island:hydrate
Las islas loading: "eager" se renderizan en cuanto se inicia el entorno de ejecución. Las islas loading: "visible" esperan a IntersectionObserver. Si varias islas visibles entran en la ventana gráfica al mismo tiempo, se agrupan en una sola solicitud.
event actualiza una isla cuando se produce el evento de ventana indicado:
window.dispatchEvent(new Event('cart:updated'));
Si se producen errores, el marcador de posición permanece y se envía
blockstudio:island:error.
Endpoint de fragmentos
El endpoint de islas es público, pero no es un API general para renderizar bloques.
Cada marcador incluye:
- el nombre del bloque
- los atributos incluidos en la lista de permitidos
- una firma generada por el servidor
El endpoint solo renderiza cuando:
- el bloque está registrado
- el bloque WordPress es dinámico
- el bloque está marcado como una isla Blockstudio dinámica
- los atributos recibidos cumplen el esquema del bloque y la lista de atributos permitidos de la isla
- la firma coincide con el nombre y los atributos normalizados del bloque
Las firmas se generan durante el renderizado en el sitio WordPress que sirve la página, a partir de las sales de ese sitio y la carga útil de la isla. No se exportan ni se incluyen en un tema.
Las respuestas del endpoint se marcan como no almacenables en caché. Si quieres almacenar fragmentos en caché, usa island.cache.
Caché de fragmentos
Los fragmentos dinámicos no se almacenan en caché de forma predeterminada.
{
"blockstudio": {
"island": {
"mode": "dynamic",
"cache": true
}
}
}
true usa una caché global de corta duración. Usa el formato de objeto para controlarlo explícitamente:
{
"cache": {
"ttl": 120,
"per": "user"
}
}
per: "global" comparte un fragmento en caché para el mismo bloque, los mismos atributos y el mismo contexto de página opcional.
per: "user" varía la caché según el ID de usuario actual de WordPress.
Renderizado mediante código
Las islas funcionan dondequiera que se rendericen los bloques Blockstudio:
bs_render_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
echo bs_block([
'name' => 'acme/cart-count',
'data' => ['productId' => 42],
]);
También funcionan mediante etiquetas de bloque:
<bs:acme-cart-count product-id="42" />
<block name="acme/cart-count" productId="42" />
El resultado inicial sigue siendo el marcador de isla y el marcador de posición; el entorno de ejecución se inyecta cuando la respuesta renderizada contiene ese 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 los metadatos del bloque. Solo se crean marcadores dinámicos para los bloques Blockstudio dinámicos registrados que tengan island.mode establecido en dynamic.
Hooks
Detección y marcado:
blockstudio/islands/is_island
blockstudio/islands/mode
blockstudio/islands/attributes
blockstudio/islands/marker_tag
blockstudio/islands/marker_attributes
blockstudio/islands/placeholder
Endpoint y renderizado:
blockstudio/islands/allowed
blockstudio/islands/max_per_request
blockstudio/islands/request_attributes
blockstudio/islands/fragment
blockstudio/islands/max_per_request cambia el número máximo de islas dinámicas aceptadas por una solicitud agrupada al endpoint. El valor predeterminado es 50.
Configuración del entorno de ejecución:
blockstudio/islands/endpoint_url
blockstudio/islands/loading
Firmas:
blockstudio/islands/signature_payload
blockstudio/islands/signature
blockstudio/islands/verify_signature
Acciones del ciclo de vida:
blockstudio/islands/registered
blockstudio/islands/rendered
Cuándo no usar islas
No uses una isla dinámica para contenido esencial para SEO. Los fragmentos de islas dinámicas no están presentes en la respuesta inicial de HTML y no están pensados para su indexación.
Usa el renderizado normal o una isla hidratada cuando el contenido sea seguro para la caché y deba ser visible para los rastreadores. Usa una isla dinámica solo para contenido que pueda llegar después de la estructura de la página, como los datos de la cuenta UI, el estado del carrito, las recomendaciones personalizadas o los controles sujetos a permisos.