Migración a v7
Esta guía describe los cambios que debes realizar al actualizar de Blockstudio 6 a 7.
Importaciones de módulos ES
Nuevo prefijo npm: (recomendado)
Blockstudio 7 introduce un nuevo prefijo npm: para las importaciones de módulos ES, que coincide con la convención del especificador Deno de npm.
Antes (v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
Después (v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
Importaciones de CSS
El mismo cambio se aplica a las importaciones de CSS:
Antes (v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
Después (v7):
import "npm:swiper@11.0.0/swiper.min.css";
Compatibilidad con versiones anteriores
El prefijo blockstudio/ sigue siendo compatible con versiones anteriores. El código existente seguirá funcionando sin cambios. Sin embargo, recomendamos migrar al prefijo npm: para mantener la coherencia con el ecosistema JavaScript en general.
El prefijo npm: ofrece varias ventajas:
- Coherencia con el ecosistema: sigue la convención establecida de Deno
- Claridad: deja claro de inmediato que se importa desde npm
- Preparación para el futuro: el prefijo
blockstudio/podría quedar obsoleto en una futura versión principal
Nombres de hooks
Blockstudio 7 estandariza todos los nombres de hooks de PHP para que usen snake_case en lugar de camelCase, en consonancia con las convenciones del núcleo de WordPress.
Nombres de hooks modificados
| Nombre anterior (v6) | Nombre nuevo (v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
Compatibilidad con versiones anteriores
Los nombres de hooks antiguos en camelCase siguen siendo compatibles con versiones anteriores. El código existente seguirá funcionando sin cambios. Sin embargo, recomendamos migrar a los nuevos nombres en snake_case para mantener la coherencia.
Ejemplo de migración:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
Etiquetas canónicas de bloques
Blockstudio 7.6 mantiene los prefijos de proyecto y los alias exactos como puntos de extensión en tiempo de ejecución, pero usa <bs:namespace-slug> como forma canónica en ejemplos, resultados del catálogo, declaraciones de renderizado y diagnósticos. Las etiquetas canónicas llevan el nombre real del bloque registrado y no dependen de un filtro específico del entorno.
Para un proyecto con brand => ["theme-components"] y ui => ["bsui"]:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
Un comando de migración independiente inventaría un proyecto existente y reescribe las formas abreviadas con la forma canónica. Primero genera un informe, se detiene ante casos sin resolver y solo cambia los nombres de las etiquetas. Consulta Migración de etiquetas de bloques para ver el comando, sus entradas y su comportamiento seguro.
Nombres de archivos de recursos
Blockstudio 7 introduce la notación con punto para los sufijos de archivos de recursos y la recomienda en lugar de la antigua notación con guion.
Nombres de archivo modificados
| Nombre anterior (v6) | Nombre nuevo (v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
Compatibilidad con versiones anteriores
La notación con guion sigue siendo compatible con versiones anteriores. Los archivos existentes seguirán funcionando sin necesidad de cambiarles el nombre. Sin embargo, recomendamos usar la notación con punto en los bloques nuevos.
Ejemplo de migración:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
Control de campos
La propiedad switch ahora tiene false como valor predeterminado, en lugar de true. En v6, todos los campos tenían un interruptor invisible en el borde izquierdo que estaba activado de forma predeterminada. En v7, el interruptor es opcional y usa un icono de ojo visible en la etiqueta del campo.
Cambios realizados
- El valor predeterminado ahora es
false: los campos ya no tienen un interruptor, a menos que establezcas"switch": trueexplícitamente - Icono de ojo visible: en lugar de una zona de clic oculta a la izquierda, aparece un botón con un icono de ojo en el área de la etiqueta
- Capa de desactivación: cuando un campo está desactivado, se muestra una capa desenfocada con el texto «Este campo está desactivado» en lugar de limitarse a reducir la opacidad
Migración
Si dependías del comportamiento predeterminado del interruptor en v6, debes activarlo explícitamente:
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
Si antes establecías "switch": false para desactivar el interruptor, puedes eliminarlo, ya que false es ahora el valor predeterminado.
Tailwind CSS
Blockstudio 7 sustituye por completo el enfoque v6 Tailwind. En v6, Tailwind CSS se compilaba en el cliente mediante CDN en el editor y se guardaba en el disco al guardar la publicación. En v7, Tailwind CSS se compila en el servidor en cada solicitud del frontend mediante TailwindPHP con almacenamiento en caché automático basado en archivos.
Consulta la documentación de Tailwind CSS para conocer todos los detalles del nuevo sistema.
Compilación en el servidor siempre activa
Cuando tailwind.enabled está true, cada solicitud del frontend se compila en el servidor. El proceso de compilación es el siguiente:
- WordPress renderiza la página completa HTML en un búfer de salida
- Las clases candidatas de CSS se extraen de HTML (expresión regular rápida, sin compilación)
- Las candidatas se ordenan y se calcula su hash con la configuración CSS para crear una clave de caché
- Si hay una coincidencia en la caché: se lee e inserta el archivo CSS almacenado
- Si no hay coincidencia: TailwindPHP compila CSS, lo escribe en la caché de ejecución compartida de Blockstudio dentro del ámbito
tailwindy lo inserta
El CSS compilado se inserta como una etiqueta <style id="blockstudio-tailwind"> en línea antes de </head>. Incluye el preajuste de Tailwind y todas las clases de utilidad coincidentes.
El script CDN sigue activo en el editor solo para la vista previa en directo. Nunca se sirve en el frontend.
Cambio de formato de config
La propiedad config cambió de un objeto JSON (Tailwind v3) a una cadena CSS (sintaxis Tailwind v4 CSS primero).
Antes (v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
Después (v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
Se eliminó la opción customClasses
Se eliminó la opción de matriz customClasses. Con el enfoque que da prioridad a CSS de Tailwind v4, las clases de utilidad personalizadas se definen directamente en la cadena config mediante @layer utilities.
Antes (v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
Después (v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
O mediante el filtro para configuraciones multilínea:
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
También se eliminó el filtro blockstudio/settings/tailwind/custom_classes. Usa el filtro blockstudio/tailwind/css para añadir reglas CSS personalizadas.
Se eliminó el endpoint REST
Se eliminó el endpoint POST /blockstudio/v1/editor/tailwind/save. El CSS compilado ya no se guarda desde el editor. Si tenías código personalizado que llamaba a este endpoint, puedes eliminarlo sin problemas.
Almacenamiento en caché
Blockstudio usa una estrategia de almacenamiento en caché basada en candidatas. En lugar de calcular el hash de toda la página HTML (lo que invalidaría la caché en cada solicitud debido a los nonces y las marcas de tiempo), solo se calcula el hash de las candidatas de clase CSS. Esto significa que:
- Dos páginas con las mismas clases CSS comparten el mismo archivo en caché
- El contenido dinámico (nonces, barras de administración y marcas de tiempo) no invalida la caché
- La caché solo se invalida cuando cambia el conjunto de clases CSS o la configuración
Los archivos de caché usan la raíz de ejecución Blockstudio configurada en
sites/{network-blog}/{runtime-identity}/tailwind/. Llama a
Blockstudio\Runtime_Cache::purge('tailwind') para forzar la recompilación.
Cambios en los filtros
| Nombre anterior (v6) | Nombre nuevo (v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
Eliminado |
blockstudio/settings/tailwind/custom_classes |
Eliminado |
Archivos y recursos encolados eliminados
En v6, Tailwind CSS se encolaba como hojas de estilo externas (blockstudio-tailwind, blockstudio-tailwind-preflight). En v7, todo CSS se inserta en línea mediante un búfer de salida. En el frontend no hay etiquetas de enlace ni hojas de estilo encoladas para Tailwind.
Biblioteca de bloques
Se eliminó la biblioteca integrada «Elementos de Blockstudio». La opción library de blockstudio.json y el filtro blockstudio/settings/library ya no tienen ningún efecto.
Si usabas los bloques de la biblioteca (Galería, Carrusel, Comparación de imágenes, Código, Icono), copia las carpetas de bloques del directorio includes/library/blockstudio-element/ de tu instalación de v6 al directorio blockstudio de tu tema y actualiza sus archivos block.json con los nuevos nombres y categorías.