Saltar al contenido

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.

JSON
{
  "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.

JSON
{
  "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:

Text
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.

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

true y "hydrate" indican que es una isla hidratada. "dynamic" indica que es 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"
      }
    }
  }
}
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:

JSON
{
  "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:

  1. la ruta explícita island.placeholder
  2. placeholder.php
  3. placeholder.blade.php
  4. placeholder.twig
  5. placeholder.html
  6. la plantilla normal con indicadores de marcador de posición
PHP
<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
<?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:

  • isIsland
  • isIslandPlaceholder
  • isIslandFragment
  • islandPhase

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:

  1. recopila todos los marcadores listos
  2. elimina los pares duplicados de nombre de bloque, atributos y firma
  3. envía una solicitud REST agrupada
  4. sustituye cada marcador de posición por el fragmento recibido
  5. envía blockstudio:island:rendered
  6. 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:

JavaScript
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.

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

true usa una caché global de corta duración. Usa el formato de objeto para controlarlo explícitamente:

JSON
{
  "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:

PHP
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:

HTML
<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

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 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:

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

Endpoint y renderizado:

PHP
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:

PHP
blockstudio/islands/endpoint_url
blockstudio/islands/loading

Firmas:

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

Acciones del ciclo de vida:

PHP
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.