Saltar al contenido

Lienzo

El lienzo ofrece una vista general en miniatura, similar a Figma, de todas las páginas gestionadas por Blockstudio. Cada página se representa como una mesa de trabajo en un iframe activo dentro de una sola fila horizontal. Desplácese con el panel táctil y amplíe o reduzca con el gesto de pellizcar o Ctrl+desplazamiento.

Activación

El lienzo está disponible como página oculta de administración. Vaya a:

Código
/wp-admin/admin.php?page=blockstudio-canvas

Solo se puede acceder a la página cuando dev.canvas.enabled está true y el usuario actual tiene la capacidad edit_posts.

Ajustes

Habilite el lienzo y configure su comportamiento en el blockstudio.json de su tema:

JSON
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
Propiedad Tipo Valor predeterminado Descripción
enabled boolean false Habilitar la función de lienzo.
adminBar boolean true Mostrar la barra de administración de WordPress dentro de los iframes de las mesas de trabajo. Establézcalo en false para una vista previa más limpia.

Ambos ajustes también están disponibles como filtros:

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');

Vistas

Cambie de vista con el menú desplegable de la esquina superior derecha.

  • Páginas: todas las páginas gestionadas por Blockstudio como mesas de trabajo de ancho completo en una sola fila.
  • Bloques: todos los bloques Blockstudio registrados en una cuadrícula; cada uno se representa con los valores predeterminados de sus atributos.

Inventario público y API de documentos

Canvas ofrece un contrato PHP versionado e independiente del consumidor para las herramientas que necesitan el mismo contenido registrado sin tener que reconstruir la lógica de descubrimiento o renderizado de Blockstudio:

PHP
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);

La versión actual está disponible en Canvas::SCHEMA_VERSION. Los resultados del inventario contienen:

  • inventory: pages, blocks, patterns, templates y parts normalizados, además de ejemplos de familias públicas de ui
  • order: el orden de visualización estable entre tipos
  • sources: rutas de origen exactas seleccionadas, con procedencia en cada registro; el campo source de un registro de página es su identidad de origen estable, mientras que path es la ruta física de la plantilla de renderizado
  • warnings y errors: incidencias estructuradas en lugar de salida generada
  • deleted: identificadores solicitados que ya no existen
  • selection: la selección normalizada e indica si se dirigió a elementos específicos

Canvas::documents() añade un documento de renderizado completo por cada registro seleccionado. Cada documento contiene su cuerpo, el HTML ensamblado, los nombres de los bloques y sus dependencias, y el CSS, JavaScript, los módulos, el arranque de interactividad, los elementos globales de UI incluidos en el paquete, y la salida Tailwind. Los documentos de página usan un contenedor semántico de contenido <main>; quien los llama puede anularlo o desactivarlo mediante las opciones compartidas de documentos de renderizado. Cada página seleccionada se renderiza en su propio contexto restaurado de WordPress del frontend, de modo que las condicionales de consulta, los filtros de clases del body, los shortcodes, los diseños, las redirecciones y las funciones de retorno de wp_enqueue_scripts observan esa página en vez de la solicitud del administrador o REST que pidió el resultado de Canvas. Las clases de body proporcionadas por quien llama se combinan con las clases contextuales de la página, y los registros de encolado del frontend se aíslan entre documentos. Canvas resuelve esas funciones de retorno del ciclo de vida mediante sus nombres de función públicos WordPress, por lo que se conserva el mismo contexto cuando se carga Blockstudio a través de Composer o de un espacio de nombres de aplicación reubicado.

Semántica de selección exacta

La selección es estricta:

  • Si no se reconocen claves de tipo, se cargan todos los tipos.
  • true, null o "*" cargan todos los registros de ese tipo.
  • Una cadena o una lista carga solo los ID, nombres, slugs, rutas o rutas de origen exactos.
  • Una cadena/lista vacía o false no carga ningún registro de ese tipo.
  • En cuanto se incluye una clave de tipo, no se descubren, sincronizan, renderizan ni compilan los tipos omitidos.

Esto hace que las solicitudes que solo incluyen elementos modificados sean seguras en proyectos grandes. Los bloques y las páginas existentes se resuelven mediante sus registros canónicos. Cuando una solicitud del frontend solo ha cargado la proyección persistida de la página, Canvas descubre el origen en modo de solo lectura y combina los ID de publicación y los enlaces permanentes coincidentes sin sincronizar el contenido. La misma combinación de identidades se aplica cuando un origen lógico de descubrimiento primero llena el registro respaldado por el origen, de modo que el renderizado contextual de páginas siga usando la publicación de WordPress gestionada que corresponda. La topología de una nueva sesión activa se descubre solo alrededor del directorio modificado, mientras que los orígenes de patrones seleccionados y de plantillas del Editor del sitio se compilan solo tras la selección.

El endpoint de actualización REST sigue la misma regla para sus parámetros de consulta blocks y pages existentes. Por ejemplo, ?blocks=theme/hero devuelve ese bloque y ninguna página; use ambos parámetros para una respuesta mixta. Si se llama al endpoint sin ninguno de los parámetros, se conserva la respuesta heredada completa.

Modo en vivo

El modo en vivo usa Server-Sent Events (SSE) para detectar cambios en los archivos y actualizar el lienzo en tiempo real. Al editar una plantilla de bloque, una plantilla de página o una hoja de estilos, las mesas de trabajo afectadas se actualizan automáticamente en aproximadamente un segundo.

Active o desactive el modo en vivo desde el menú desplegable. Cuando está activo, aparece un indicador verde pulsante. El ajuste se conserva entre sesiones mediante localStorage.

El modo en vivo sigue los cambios en los archivos .php, .json, .css, .scss, .js, .twig y .html dentro de los directorios de bloques y páginas. Las ediciones conocidas actualizan solo el bloque o la página registrados. Un bloque o página verdaderamente nuevos activan un único análisis topológico limitado al directorio, de modo que crear contenido durante una sesión en vivo abierta sigue funcionando sin volver a analizar orígenes no relacionados.

Modo de enfoque

Haga clic en cualquier etiqueta de mesa de trabajo para entrar en el modo de enfoque. La mesa de trabajo seleccionada ocupa todo el ancho de la ventana gráfica y permite desplazarse verticalmente. Pulse Escape o haga clic en el botón de cierre para volver a la vista general.

Controles

Acción Entrada
Desplazar Desplazamiento / arrastre con dos dedos en el panel táctil
Ampliar o reducir Ctrl+desplazamiento o pellizcar
Ajustar a la vista Menú desplegable
Zoom al 100% Menú desplegable
Enfocar mesa de trabajo Hacer clic en la etiqueta de la mesa de trabajo
Salir del enfoque Escape / botón de cierre

Seguridad

El script del lienzo y los datos de la página solo se cargan cuando se cumplen todas las condiciones:

  • El ajuste dev.canvas.enabled está true.
  • El usuario actual tiene la capacidad edit_posts.

Los visitantes públicos nunca ven el script del lienzo ni los metadatos de la página.