Con las variaciones de estilos de los bloques (estilos de bloques), puedes ofrecer tus propios estilos prediseñados en los bloques del núcleo para garantizar la consistencia de la estética de la marca y optimizar la producción de contenido. Con los estilos de bloques también evitas tener que crear bloques personalizados y mantienes tu código más limpio.
En esta guía, aprenderás varias formas de añadir estilos de bloques personalizados en WordPress, tanto en temas como en plugins. Hablaremos sobre las diferentes opciones, JSON (theme.json), PHP (register_block_style()) y JavaScript, con consejos sobre cuándo utilizar cada una.
También veremos cómo excluir del editor la opción de estilar los bloques por defecto y mejorar la experiencia para tus usuarios.
El código de theme.json se refiere a los estilos de bloques como variaciones, lo que puede confundirse con las variaciones de bloques o las variaciones de estilos globales. En este artículo nos referiremos a ellos como estilos de bloques para evitar confusiones.
Empezaremos con unos ejemplos sencillos e introduciremos gradualmente métodos más avanzados de añadir estilos de bloques, ya sean pequeños cambios en el tema o modificaciones más complejas en un plugin.
El código del que se hace referencia en esta entrada está disponible también en GitHub:
- Temas: plain-pauli
- Plugins: block-styles
Necesitas tener nociones básicas de CSS para seguir esta guía. También debes estar familiarizado con theme.json, y te puede resultar muy útil tener algunos conocimientos de PHP y los hooks de WordPress.
Para seguir el tutorial o utilizar el código de ejemplo, puedes utilizar Studio, nuestro entorno de desarrollo local gratuito y de código abierto, disponible en Mac y Windows.
- ¿Qué son los estilos de bloques personalizados?
- Método 1: añadir un estilo de bloque mediante un archivo JSON (carpeta /styles)
- Método 2: registrar el estilo de bloque en PHP y darle estilo mediante theme.json
- Método 3: añadir un estilo de bloque con register_block_style() (PHP)
- Método 4: registrar estilos de bloque utilizando JavaScript + CSS
- Opcional: eliminar estilos de bloques del núcleo
- Resumen: los estilos de bloques personalizados de un solo vistazo
- Más recursos
¿Qué son los estilos de bloques personalizados?
Con los estilos de bloques personalizados puedes definir alternativas visuales para bloques que ya existen, como añadir un borde, cambiar el fondo o modificar la tipografía.
Al seleccionar el bloque, estos estilos personalizados aparecerán en el panel Estilos de la barra lateral del editor. Con esto, los usuarios podrán aplicar patrones de diseños reutilizables de forma sencilla y consistente. Puedes crear todos los estilos de bloques personalizados que quieras.
El siguiente ejemplo es del bloque Imagen. En el panel de Estilos aparecen cuatro estilos: Por defecto, Redondeado, Borde violeta y Borde rojo (que es el que está seleccionado en el editor).
Veamos las seis formas de añadir estilos personalizados en los bloques de WordPress, desde modificaciones sencillas del tema hasta otros métodos más avanzados.
Método 1: añadir un estilo de bloque mediante un archivo JSON (carpeta /styles)
- Ideal para: Desarrolladores de temas
- Dónde utilizarlo: Por lo general, en temas
- Requisitos de versión: WordPress 6.6 o superior con theme.json v3
La forma más sencilla de añadir estilos de bloques personalizados en un tema es añadir un archivo nuevo a la carpeta /styles.
Este método requiere mejorar el schema de theme.json a v3, el cual solo está disponible en WordPress 6.6 o superior. Como desarrollador del tema, tendrás que pedirle a tus usuarios que instalen el plugin Gutenberg o actualizar los requisitos mínimos del tema a WordPress 6.6 para garantizar que todo funciona correctamente.
Pongamos que queremos añadir un estilo de borde azul con el nombre image-blue-border.json.
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Blue Border",
"slug": "blue-border",
"blockTypes": [ "core/image" ],
"styles": {
"border": {
"color": "#00f9ff",
"style": "solid",
"width": "4px",
"radius": "15px"
},
"shadow": "var(--wp--preset--shadow--natural)"
}
}
Con theme.json v3, la información de los metadatos de un estilo de bloque se registra automáticamente en WP_Block_Styles_Registry:
- El title es el mismo que la label del código register_block_style.
- El slug es similiar a la propiedad name de la función register_block_style.
- La propiedad blockTypes se puede utilizar para asignar un estilo a un bloque o a una serie de bloques específicos.
El código "shadow": "var(--wp--preset--shadow--natural)" se refiere al estilo de sombras prediseñado «Natural» en WordPress. Con una variable preset, el bloque reflejará automáticamente cualquier cambio en los estilos globales, de forma que el diseño se mantendrá consistente en todos los temas y actualizaciones.
Cuando hayas guardado los cambios en el código:
- Se añadirá el nuevo estilo al panel Estilos del bloque.
- El editor de bloques mostrará una vista previa al pasar el cursor sobre el botón.
- El motor de los estilos adjuntará la clase de CSS is-blue-border al bloque, tanto en el editor como en el front-end.
- Abriendo los estilos globales desde Estilos → Bloques → Imagen, el usuario puede modificar los estilos de todo el sitio.
Para organizar mejor el código del estilo de bloque, puedes crear una subcarpeta en la carpeta de estilos llamada /blocks y reunirlo todo allí. Hay desarrolladores que consiguen reducir considerablemente la longitud de su archivo functions.php utilizando las subcarpetas.
Método 2: registrar el estilo de bloque en PHP y darle estilo mediante theme.json
- Ideal para: Desarrolladores de temas
- Dónde utilizarlo: En los archivos theme.json y functions.php
- Requisitos de versión: WordPress 6.6 o superior con theme.json v3
Para añadir un estilo de bloque personalizado con este método, tendrás que registrar primero el estilo y añadir los estilos en el archivo theme.json.
Registrar el estilo de bloque
En el archivo functions.php, utiliza la función register_block_style() para establecer los dos argumentos obligatorios (los argumentos opcionales los veremos más adelante):
- name: El identificador del estilo utilizado para computar la clase CSS.
- label: La etiqueta del estilo en un formato legible para personas.
Cuando los hayas establecido, añádelos al hook init de tu tema.
function my_style_red(){
register_block_style(
'core/image',
array(
'name' => 'red-border',
'label' => __( 'Red Border', 'my-theme' )
)
);
}
add_action( 'init', 'my_style_red' );
Añadir estilos a theme.json
Ahora vamos a darle algo de estilo a la variación red-border del archivo theme.json. Se ubica en la sección styles.blocks.core/image, ya que estamos haciendo cambios en el bloque Imagen.
"styles": {
"blocks": {
"core/image":{
"variations": {
"red-border":{
"border": {
"color":"#cf2e2e",
"style": "solid",
"width": "4px",
"radius":"15px"
}
}
}
},
Estos dos fragmentos de código funcionan juntos porque el name utilizado en la función register_block_style() del archivo functions.php y los argumentos del name de las variaciones del archivo theme.json son idénticos.
Este método produce los mismos resultados en el editor y el front-end que si utilizaras un archivo JSON en la carpeta /styles:
- El estilo estará visible en el editor y en el front-end.
- También está disponible en la sección Editor → Estilos → Bloques → Imagen para personalizar el sitio de forma global.
Si los estilos disponibles en theme.json no son suficientes, tienes más opciones:
- Puedes utilizar la propiedad CSS en notación JSON. En el artículo de WordPress.org sobre CSS en bloques con theme.json hay un buen resumen de cómo se hace.
- Puedes utilizar cualquiera de los siguientes métodos y añadirlos a tu archivo functions.php.
- Puedes registrar el estilo de bloque con register_block_style() e incluir el CSS en el archivo style.css general de tu tema, haciendo referencia al bloque y al nombre de la clase del estilo. Sin embargo, esto no es recomendable, ya que estos estilos siempre se cargarán, incluso si el bloque no se está utilizando. Además, hay un fallo por el que los estilos no se cargan en el front-end.
- También puedes utilizar las hojas de estilo del bloque para cargar los estilos solo cuando se está usando el bloque, como se puede ver en el tutorial sobre las hojas de estilo de los bloques de WordPress Theme.
Método 3: añadir un estilo de bloque con register_block_style() (PHP)
La función register_block_style() tiene otros tres parámetros opcionales. Los puedes ver en la página de documentación de la clase WP_Block_Styles_Registry, que se encarga de registrar y gestionar los estilos de bloques.
- style_data: Un objeto similar a theme.json utilizado para generar CSS.
- inline_style: Código CSS inline que registra la clase CSS necesaria para el estilo.
- style_handle: El handle de un estilo previo registrado para ponerlo en la cola junto con el estilo de bloque.
Échale un vistazo a la documentación de register_block_style() para ver más información.
3a. Utilizar el parámetro style_data
- Ideal para: Desarrolladores de plugins y desarrolladores de temas
- Dónde utilizarlo: En los archivos del plugin o en functions.php
- Requisitos de versión: WordPress 6.6 o superior
A pesar de que los estilos de bloque son parte fundamental de WordPress desde la versión 5.0, el parámetro style_data fue añadido en WordPress 6.6.
Este método para añadir estilos de bloque utiliza un objeto similar a theme.json, es decir, un conjunto de estilos anidados en un formato que resulta muy parecido a la sección de estilos de un archivo theme.json. A nivel de raíz, los estilos se aplican en el bloque (o bloques) que definas con el array block_name.
Si conoces bien la estructura del archivo theme.json, puedes utilizar este método para añadir más estilos. Este método activa los estilos en Editor → Estilos → Bloques, y los usuarios pueden realizar cambios desde allí.
Como puedes ver, la notación del array de este parámetro sigue a JSON muy de cerca.
El theme.json es como sigue:
"border": {
"color":"#cf2e2e",
"style": "solid",
"width": "4px",
"radius":"15px"
}
El array en PHP es así:
array(
'border' => array(
'color' => '#f5bc42',
'style' => 'solid',
'width' => '4px',
'radius' => '15px'
),
Para que se vea más claro, con esta función se añade un borde naranja con una sombra de caja utilizando el estilo prediseñado de sombras «Nítida».
function my_orange_border() {
register_block_style(
array( 'core/image' ),
array(
'name' => 'orange-border',
'label' => __( 'Orange Border', 'pauli' ),
'style_data'=> array(
'border' => array(
'color' => '#f5bc42',
'style' => 'solid',
'width' => '4px',
'radius' => '15px'
),
'shadow' => array(
'var(--wp--preset--shadow--sharp)'
)
)
)
);
};
add_action( 'init', 'my_orange_border' );
De estos tres parámetros, solo la información de style_data se añadirá a la sección de estilos globales del editor del sitio para que pueda ser editada por el usuario. Los otros dos añaden los estilos al panel Estilos, y no se pueden editar desde la interfaz de usuario.
3b. Utilizar el parámetro inline_style
- Ideal para: Desarrolladores de plugins y desarrolladores de temas
- Dónde utilizarlo: En el archivo PHP principal del plugin o en functions.php
- Requisitos de versión: WordPress 5 o superior
El valor del parámetro inline_style es una combinación del selector CSS y las propiedades CSS.
function my_double_frame_styles() {
register_block_style(
'core/image',
array(
'name' => 'double-frame',
'label' => __( 'Double-Frame', 'pauli' ),
'inline_style' => '.wp-block-image.is-style-double-frame
img { border: 10px ridge lightgreen; }'
)
);
}
add_action( 'init', 'my_double_frame_styles' );
El nombre de la clase sigue las convenciones propias del editor de bloques. Cada nombre de clase de los bloques del núcleo contiene el prefijo wp-block + el nombre del bloque. A continuación la sigue el prefijo del estilo del bloque is-style y el slug del estilo registrado, como double-frame.
Tras el nombre de clase .wp-block-image.is-style-double-frame, va el estilo que quieras añadir al bloque. Aquí puedes ver los valores CSS de la propiedad borde del elemento imagen (img), que añade un borde con relieve de color verde claro de 1 px de grosor.
Puedes combinar varias propiedades CSS en el parámetro inline_style de la función, pero, si hay muchas, se puede hacer difícil de leer o gestionar.
3c. Utilizar el parámetro style_handle
- Ideal para: Desarrolladores de plugins y desarrolladores de temas
- Dónde utilizarlo: En archivos del plugin o en functions.php
- Requisitos de versión: WordPress 5 o superior
Si quieres utilizar estilos más elaborados, tienes la opción de colocar el código CSS en un archivo separado y utilizar wp_enqueue_style() para cargarlo en el front y el back-end. Utiliza el parámetro style_handle en la función register_block_style().
Estos son algunos ejemplos de código que utilizan este método para añadir un estilo de borde violeta.
function my_purple_border_styles() {
wp_enqueue_style(
'my-image-block-style',
plugin_dir_url(__FILE__) . '/my-purple-border.css',
array( 'wp-edit-blocks' ),
'1.0'
);
register_block_style(
'core/image',
array(
'name' => 'purple-border',
'label' => __( 'Purple Border, slightly rounded', 'pauli' ),
'style_handle' => 'my-image-block-style'
)
);
}
Y esto es lo que lo acompaña en el archivo my-purple-border.css, que irá en la carpeta raíz del plugin.
.is-style-purple-border img {
border: 6px solid purple;
border-radius: 15px;
box-shadow: 10px 5px 5px #e090fc;
};
El bloque de imagen ahora tiene un estilo de borde violeta con una sombra rosácea.
Nota: Existe un fallo por el que la hoja de estilos se carga incluso cuando no se utiliza el estilo de bloque. Por ello no es recomendable utilizar un CSS demasiado complejo.
Método 4: registrar estilos de bloque utilizando JavaScript + CSS
- Ideal para: Desarrolladores de plugins y desarrolladores de temas
- Dónde utilizarlo: En un archivo *.js separado, en la cola de un archivo de plugin o en functions.php
- Requisitos de versión: WordPress 5 o superior
Si lo comparamos con el método de utilizar un archivo JSON separado para añadir una variación de estilo de bloque, JavaScript es una alternativa un poco más compleja. Consta de tres partes:
- PHP: para poner en cola los archivos necesarios
- JavaScript: para registrar el estilo de bloque
- CSS: para darle estilo al bloque
La función wp_enqueue_script() añade los archivos de JavaScript a la página web. No es JavaScript en sí, sino más bien una función PHP de WordPress que se suele utilizar en el desarrollo de temas y plugins de WordPress. En este ejemplo, podemos almacenar el archivo .js en el subdirectorio /js/ del tema y nombrarlo curate-core.js.
El código del ejemplo carga nuestro archivo curate-core.js personalizado después de los scripts del editor de bloques de WordPress. Se añade en la parte inferior de la página para que tenga mejor rendimiento, y utiliza un hook con enqueue_block_editor_assets para que solo se cargue en el editor.
Este ejemplo de código se incluye en el archivo functions.php del tema o en el archivo *.php del plugin.
function pauli_block_editor_scripts() {
wp_enqueue_script(
'pauli-editor',
get_theme_file_uri( '/js/curate-core.js' ),
array( 'wp-blocks', 'wp-dom' ),
wp_get_theme()->get( 'Version' ), true
);
}
add_action( 'enqueue_block_editor_assets', 'pauli_block_editor_scripts' );
El siguiente código debe ir en el archivo JavaScript curate-core.js:
wp.domReady( function() {
wp.blocks.registerBlockStyle(
'core/image', {
name: 'black-border',
label: 'Black Border',
}
);
} );
Después, puedes añadir nuestros estilos de bloque al archivo style.css del tema utilizando el nombre de clase que se añade automáticamente: is-style-black-border.
.is-style-black-border img {
border: 15px ridge black;
}
Hay que añadir el archivo style.css al front-end, ya que parece que hay un fallo por el que no se carga automáticamente. Utiliza wp_enqueue_style() y después el hook wp_enqueue_scripts.
Ahora añade lo siguiente a functions.php o al archivo del plugin:
function enqueue_theme_styles() {
wp_enqueue_style(
'my-theme-styles',
get_stylesheet_uri(), // This gets your style.css
array(),
wp_get_theme()->get( 'Version' )
);
}
add_action( 'wp_enqueue_scripts', 'enqueue_theme_styles' );
También necesitarás añadir el style.css al editor de bloques para que los usuarios puedan ver cómo queda el estilo de bloque mientras editan la página o la entrada.
//add style.css to editor
function add_theme_editor_styles() {
add_editor_style( 'style.css' );
}
add_action( 'after_setup_theme', 'add_theme_editor_styles' );
Opcional: eliminar estilos de bloques del núcleo
Ahora que ya sabes cómo añadir estilos de bloques a un tema o plugin, quizá te interese también eliminar algunos de los estilos que vienen incluidos en el editor de bloques.
Hay dos funciones de las que debes encargarte:
- La función de PHP unregister_block_style()
- La función de JavaScript unregisterBlockStyle()
Los estilos de bloque solo pueden «desregistrarse» en el mismo lenguaje de código que se utilizó para registrarlos. Todos los bloques del núcleo están registrados con JavaScript.
El siguiente ejemplo de código elimina los estilos del bloque Imagen que se llamen rounded.
wp.domReady( function() {
wp.blocks.unregisterBlockStyle( 'core/image', [ 'rounded' ] );
} );
En este artículo puedes encontrar muchas más formas de modificar el editor de bloques para personalizar la experiencia de uso de WordPress.
Resumen: los estilos de bloques personalizados de un solo vistazo
Ahora ya sabes que hay seis formas de registrar estilos de bloques en el editor de bloques de WordPress. Aquí tienes un resumen de los métodos de los que hemos hablado:
| Estilo de bloque añadido en el ejemplo de código | Lenguaje | Tema/Plugin | Parámetro | Archivo | Estilos globales |
|---|---|---|---|---|---|
| 🟥 Rojo | PHP+ | Tema | theme.json | sí | |
| 🟦 Azul | JSON | Tema | image-blue-border.json | sí | |
| 🟧 Naranja | PHP | Tema/Plugin | style_data | sí | |
| 🟪 Violeta | PHP | Tema/Plugin | style_handle | .css | no |
| 🟩 Doble marco | PHP | Tema/Plugin | inline_style | no | |
| ⬛ Negro | JS | Tema/Plugin | .js + .css + .php | no |
Lo más sencillo es añadir un archivo JSON a la carpeta /styles utilizando el formato theme.json. Hay otra opción que utiliza muy poco PHP en el archivo functions.php junto con la configuración del theme.json. Ambos métodos añaden estilos de bloques a panel Estilos del editor, donde los usuarios pueden utilizarlos y personalizarlos.
Los desarrolladores de plugins pueden usar el parámetro style_data para conseguir resultados similares, incluyendo la integración con los estilos globales.
Otras opciones para plugins (que utilizan inline_style, style_handle o JavaScript) no son compatibles con los estilos globales, pero sí se pueden seleccionar en el editor.
Ten en cuenta que los tres primeros métodos (el archivo JSON, theme.json con PHP y style_data) requieren la versión 6.6 de WordPress o superior. Si quieres dar soporte a versiones de WordPress más antiguas, tendrás que utilizar una de las otras opciones disponibles.
Más recursos
¿Quieres profundizar más en los estilos y las variaciones de bloques? Échale un vistazo a estos recursos (en inglés):
YouTube
Nota de desarrollo de Make.WordPress
Blog de desarrollo de WordPress
- Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6
- Leveraging theme.json and per-block styles for more performant themes
- Per-block CSS with theme.json
- Beyond block styles, part 1: using the WordPress scripts package with themes
- Beyond block styles, part 2: building a custom style for the Separator block
- Beyond block styles, part 3: building custom design tools
Manual del editor de bloques
Manual de temas
WordPress.com en Español 