Como registrar estilos de bloque para editor y frontend (PHP y JS) en WordPress

Contents

Introducción: qué cubre este artículo

Este artículo explica con todo lujo de detalles cómo registrar estilos de bloque para el editor (Gutenberg) y para el frontend en WordPress, mediante PHP y mediante JavaScript. Incluye métodos modernos (block.json y register_block_type_from_metadata), ejemplos de plugin y tema, buenas prácticas sobre dependencias y versionado, y solución para bloques dinámicos. Los ejemplos de código están incluidos en bloques

preparados para EnlighterJS.

Conceptos clave

Editor vs Frontend: El editor (Gutenberg) necesita estilos específicos para que la vista en el editor refleje la apariencia real el frontend necesita los estilos que verán los visitantes.
Dos formas principales de registrar estilos:
1. Usar block.json y register_block_type_from_metadata o register_block_type con claves style y editor_style.
2. Registrar manualmente scripts/estilos con wp_register_style y asociarlos al bloque (o encolarlos desde render_callback para bloques dinámicos).
Build tools: Si usas un bundler (webpack, @wordpress/scripts), normalmente importas los .scss/.css en JS y el bundler genera style/editor.css y index.js junto con index.asset.php que contiene dependencias y versión.
register_block_style / registerBlockStyle: sirven para registrar variaciones de estilo (p. ej. rounded, outline) que aparecen como opciones en la barra lateral del bloque y aplican clases que deben tener estilos tanto para editor como para frontend.

Enfoque recomendado: usar block.json register_block_type_from_metadata

WordPress permite declarar metadatos del bloque en un archivo block.json. Para estilos se usan las claves style y editorStyle. Con register_block_type_from_metadata (o register_block_type con la ruta), WordPress enlaza automáticamente los handles especificados.

block.json: ejemplo mínimo

{
  apiVersion: 2,
  name: mi-plugin/mi-bloque,
  version: 1.0.0,
  title: Mi Bloque,
  category: widgets,
  editorScript: file:./build/index.js,
  script: file:./build/frontend.js,
  style: file:./build/style.css,
  editorStyle: file:./build/editor.css
}

Con este block.json, al llamar register_block_type_from_metadata( __DIR__ ) WordPress leerá los campos y registrará los handles necesarios si existen los ficheros en la ruta indicada.

Registro en PHP usando register_block_type_from_metadata

Este enfoque es el más limpio cuando usas create-block o un build que genera build/index.js, build/style.css y build/editor.css.

Registro manual en PHP: control total sobre handles y dependencias

Si no usas block.json o quieres mayor control sobre cómo se registran los estilos, registra scripts y estilos manualmente y asigna las keys a register_block_type.

Estructura de ejemplo (plugin)

mi-plugin/
- build/index.js
- build/editor.css
- build/style.css
- src/block.php

Registro manual completo (PHP)

 mi-bloque-editor-js,
        editor_style  => mi-bloque-editor-css,
        style         => mi-bloque-frontend-css,
    ) )
}
add_action( init, mi_bloque_registrar_assets )

Al usar las claves editor_style y style, WordPress encolará los estilos correspondientes solamente donde proceda: editor o frontend. Si el bloque es usado en el frontend, el CSS indicado en style se imprimirá automáticamente.

Bloque dinámico con estilos enqueueados bajo demanda

Para bloques con render_callback (PHP rendering), quizá quieras encolar el CSS solo cuando el bloque realmente se renderiza en la página. En ese caso, encolamos el estilo desde la función de renderizado.

Contenido del bloque

return html } function mi_bloque_registrar_dinamico() { register_block_type( mi-plugin/mi-bloque-dinamico, array( render_callback => mi_bloque_render_callback, editor_script => mi-bloque-editor-js, // opcional editor_style => mi-bloque-editor-css, // opcional ) ) } add_action( init, mi_bloque_registrar_dinamico )

Registrar variaciones de estilo (block styles)

Las variaciones de estilo son las opciones que aparecen en la barra lateral del bloque y aplican clases CSS. Pueden registrarse desde PHP y enlazar un handle de estilo común.

Ejemplo: register_block_style (PHP)

 fancy-quote,
            label        => Fancy Quote,
            style_handle => mi-bloque-variaciones-css,
        )
    )
}
add_action( init, mi_bloque_registrar_variaciones )

Con lo anterior, la variación registrará el handle mi-bloque-variaciones-css para editor y frontend automáticamente cuando la variación esté presente.

Enfoque JS moderno: importar estilos desde el código del bloque

Si usas un bundler, lo habitual es que index.js importe los estilos (editor.scss y style.scss). El build generará los CSS y la configuración (index.asset.php) con dependencias. Ejemplo:

index.js (entrada del bloque)

import ./editor.scss // Estilos solo para editor
import ./style.scss  // Estilos para editor   frontend (esto depende de tu configuración de build)

// código del bloque
import { registerBlockType } from @wordpress/blocks
import Edit from ./edit
import save from ./save

registerBlockType( mi-plugin/mi-bloque, {
    edit: Edit,
    save,
} )

Con @wordpress/scripts y una configuración estándar, el build separará editor y style si tu configuración lo define así. El resultado serán archivos en build/ que podrás referenciar desde PHP o desde block.json.

CSS: estructura y buenas prácticas

Usar selectores específicos del bloque, por ejemplo .wp-block-mi-plugin-mi-bloque o .is-style-nombre para evitar conflictos.
Si defines estilos para el editor, a menudo necesitas anidar dentro de .editor-styles-wrapper para afectar la visualización de la zona de contenido en el editor con el mismo CSS que en frontend.
Evitar reglas globales que afecten al admin más allá del editor. Si encolas un CSS para el editor, WordPress lo carga solo en el editor si está registrado como editor_style.

Ejemplo de style.scss (frontend)

.wp-block-mi-plugin-mi-bloque {
  padding: 1rem
  border: 1px solid #e2e2e2
  background: #fff
}

/ Variación /
.wp-block-mi-plugin-mi-bloque.is-style-fancy {
  border-radius: 8px
  box-shadow: 0 2px 6px rgba(0,0,0,0.08)
}

Ejemplo de editor.scss (solo editor)

/ Asegúrate de apuntar a la capa correcta del editor /
.editor-styles-wrapper .wp-block-mi-plugin-mi-bloque {
  padding: 1rem
  border: 1px dashed rgba(0,0,0,0.15)
}

Versionado y cache busting

Usa filemtime durante desarrollo o versiones basadas en package.json/build hash en producción. Si generas index.asset.php con @wordpress/scripts, aquel contiene version útil.

Compatibilidad y debugging

Para ver si un CSS se ha encolado: inspecciona el HTML generado (frontend) o la página del editor (Tools → Network o Sources en DevTools).
Si el estilo del editor no se refleja, revisa que estés registrando como editor_style o que al importarlo en JS el bundler esté generando editor.css.
En bloques dinámicos con render_callback, encola estilos dentro de la función de renderizado para evitar cargar CSS innecesario en páginas donde no aparece el bloque.
Comprueba dependencias: si tu CSS para editor necesita variables o utilidades de WordPress, añade wp-edit-blocks como dependencia cuando registres el style.

Resumen práctico: checklist antes de publicar

¿Tienes build que genera index.js, editor.css y style.css? Usa block.json para simplificar.
¿Necesitas control fino? Registra scripts y estilos manualmente con wp_register_script/wp_register_style y asócialos con register_block_type.
¿Es un bloque dinámico? Encola CSS solo cuando se renderiza (render_callback).
¿Registras variaciones? Usa register_block_style y proporciona style_handle para compartir CSS entre editor y frontend.
¿Versionas los assets? Usa filemtime en desarrollo o la versión desde index.asset.php generada por el build.
¿Pruebas en el editor? Usa .editor-styles-wrapper y revisa que el handle del CSS editor esté declarado con dependencia wp-edit-blocks si es necesario.

Ejemplo final completo (plugin simple)

A continuación un ejemplo compacto que usa el enfoque manual y soporta bloque estático y variación de estilo.

 ejemplo-bloque-editor-js,
        editor_style  => ejemplo-bloque-editor-css,
        style         => ejemplo-bloque-frontend-css,
    ) )

    // Registrar una variación para un bloque core con su propio stylesheet
    wp_register_style(
        ejemplo-variaciones-css,
        plugins_url( build/block-styles.css, __FILE__ ),
        array(),
        filemtime( build_dir . block-styles.css )
    )

    register_block_style( core/quote, array(
        name => ejemplo-fancy,
        label => Ejemplo Fancy,
        style_handle => ejemplo-variaciones-css,
    ) )
}
add_action( init, ejemplo_bloque_init )

Notas finales y recomendaciones

Prioriza el uso de block.json cuando tu flujo de trabajo lo permita: simplifica el registro y la integración con el build.
Usa nombres de handle únicos y coherentes (prefijo del plugin/tema) para evitar colisiones.
Para bloques reutilizables o compartidos por varios bloques, centraliza estilos comunes en un único handle y añádelo como dependencia en cada bloque.
Si trabajas en un tema y quieres que los bloques tengan estilos globales, considera registrar estilos del bloque desde functions.php del tema o usar theme.json para variables y ajustes globales.

Acepto donaciones de BAT's mediante el navegador Brave 🙂

Como registrar estilos de bloque para editor y frontend (PHP y JS) en WordPress

Introducción: qué cubre este artículo

Conceptos clave

Enfoque recomendado: usar block.json register_block_type_from_metadata

block.json: ejemplo mínimo

Registro en PHP usando register_block_type_from_metadata

Registro manual en PHP: control total sobre handles y dependencias

Estructura de ejemplo (plugin)

Registro manual completo (PHP)

Bloque dinámico con estilos enqueueados bajo demanda

Registrar variaciones de estilo (block styles)

Ejemplo: register_block_style (PHP)

Enfoque JS moderno: importar estilos desde el código del bloque

index.js (entrada del bloque)

CSS: estructura y buenas prácticas

Ejemplo de style.scss (frontend)

Ejemplo de editor.scss (solo editor)

Versionado y cache busting

Compatibilidad y debugging

Resumen práctico: checklist antes de publicar

Ejemplo final completo (plugin simple)

Notas finales y recomendaciones

Relacionado

Deja una respuesta Cancelar la respuesta

Introducción: qué cubre este artículo

Conceptos clave

Enfoque recomendado: usar block.json register_block_type_from_metadata

block.json: ejemplo mínimo

Registro en PHP usando register_block_type_from_metadata

Registro manual en PHP: control total sobre handles y dependencias

Estructura de ejemplo (plugin)

Registro manual completo (PHP)

Bloque dinámico con estilos enqueueados bajo demanda

Registrar variaciones de estilo (block styles)

Ejemplo: register_block_style (PHP)

Enfoque JS moderno: importar estilos desde el código del bloque

index.js (entrada del bloque)

CSS: estructura y buenas prácticas

Ejemplo de style.scss (frontend)

Ejemplo de editor.scss (solo editor)

Versionado y cache busting

Compatibilidad y debugging

Resumen práctico: checklist antes de publicar

Ejemplo final completo (plugin simple)

Notas finales y recomendaciones

¡Si te ha servido el artículo ayúdame compartiendolo en algún sitio! Pero si no te ha sido útil o tienes dudas déjame un comentario! 🙂

Relacionado

Deja una respuesta Cancelar la respuesta