Contents
Introducción
Este artículo explica, con todo lujo de detalles, cómo añadir una toolbar personalizada a un bloque de Gutenberg en WordPress usando JavaScript. Cubre desde la estructura mínima del bloque hasta variantes avanzadas (botones, grupos, dropdowns, y cómo inyectar la toolbar en bloques existentes). Incluye ejemplos completos listos para pegar en tu proyecto.
Requisitos previos
- WordPress 5.0 o superior (donde está disponible el editor de bloques).
- Conocimientos básicos de JavaScript y React (JSX).
- Herramientas para compilar el bloque (por ejemplo, @wordpress/scripts) o un entorno que genere el build JS.
- Plugin o tema donde registrar los assets del editor.
Concepto: ¿dónde se añade la toolbar?
En Gutenberg, la toolbar de un bloque se añade dentro del componente de edición usando BlockControls (desde @wordpress/block-editor). Dentro de BlockControls puedes usar componentes de la librería de componentes de WordPress como Toolbar, ToolbarGroup, ToolbarButton, DropdownMenu, etc. Los botones interactúan con los atributos del bloque mediante setAttributes.
Ventajas de usar BlockControls
- Se posiciona en la toolbar del bloque (junto a las herramientas nativas).
- Accesibilidad y estilo coherente con el editor.
- Permite acciones rápidas sin abrir el inspector lateral.
Paso 1 — Estructura del bloque y atributos
Vamos a crear un bloque de ejemplo llamado my-plugin/custom-toolbar con un contenido editable y un flag booleano que togglea un estado importante usando la toolbar.
Archivo principal (index.js)
import { registerBlockType } from @wordpress/blocks
import { __ } from @wordpress/i18n
import { Fragment } from @wordpress/element
import { BlockControls, RichText } from @wordpress/block-editor
import { ToolbarGroup, ToolbarButton, DropdownMenu } from @wordpress/components
import { createElement } from @wordpress/element
registerBlockType(my-plugin/custom-toolbar, {
title: __(Texto con toolbar, my-plugin),
category: common,
attributes: {
content: {
type: string,
source: html,
selector: div
},
isImportant: {
type: boolean,
default: false
},
styleVariant: {
type: string,
default: normal
}
},
edit: ({ attributes, setAttributes }) => {
const { content, isImportant, styleVariant } = attributes
const toggleImportant = () => setAttributes({ isImportant: !isImportant })
return (
setAttributes({ styleVariant: normal }),
},
{
title: __(Énfasis, my-plugin),
onClick: () => setAttributes({ styleVariant: emphasis }),
},
{
title: __(Sutil, my-plugin),
onClick: () => setAttributes({ styleVariant: subtle }),
},
]}
/>
setAttributes({ content: })}
/>
setAttributes({ content: newContent })}
placeholder={__(Escribe algo aquí..., my-plugin)}
className={{isImportant ? is-important : } variant-{styleVariant}}
/>
)
},
save: ({ attributes }) => {
const { content, isImportant, styleVariant } = attributes
return (
Paso 2 — Estilos del editor y del frontend
Añade reglas CSS para reflejar los estados en el editor y en el frontend.
/ Editor y frontend: estilos simples para el ejemplo /
.is-important {
border-left: 4px solid #ffb300
padding-left: 10px
background: rgba(255,179,0,0.06)
}
.variant-normal { font-style: normal }
.variant-emphasis { font-weight: 700 color: #b12704 }
.variant-subtle { color: #666 font-style: italic }
Registra estos estilos como editor_style y style en la definición del bloque (o encola los CSS en el plugin) para que se apliquen tanto en editor como en el frontend según corresponda.
Paso 3 — Registrar y encolar los assets desde PHP
Ejemplo de cómo registrar el script compilado del bloque y el CSS desde el plugin.
my-plugin-editor-script,
editor_style => my-plugin-editor-style,
style => my-plugin-style,
) )
}
add_action( init, my_plugin_register_block )
?>
Variantes avanzadas
1) Añadir iconos SVG personalizados a la toolbar
Puedes pasar un elemento SVG como prop icon a ToolbarButton. Ejemplo en JSX (usa tu SVG inline o componente Icon).
2) Inyectar toolbar en bloques existentes (hooking con filtros)
Si quieres añadir una toolbar personalizada a un bloque existente (por ejemplo, core/paragraph), usa el filtro editor.BlockEdit con addFilter y un HOC.
import { addFilter } from @wordpress/hooks
import { createHigherOrderComponent } from @wordpress/compose
import { Fragment } from @wordpress/element
import { BlockControls } from @wordpress/block-editor
import { ToolbarButton } from @wordpress/components
const withCustomToolbar = createHigherOrderComponent( ( BlockEdit ) => {
return ( props ) => {
// Solo aplicamos al párrafo como ejemplo
if ( props.name !== core/paragraph ) {
return
setAttributes({ customMarked: !attributes.customMarked }) }
isPressed={ !!attributes.customMarked }
/>
)
}
}, withCustomToolbar )
addFilter(
editor.BlockEdit,
my-plugin/with-custom-toolbar,
withCustomToolbar
)
3) Accesibilidad y buenas prácticas
- Usa label en ToolbarButton y texto alternativo en iconos SVG para lectores de pantalla.
- Respeta el foco: asegúrate de que las acciones no rompan el foco del editor salvo que sea necesario.
- Usa isPressed para botones que representan estados (toggle).
- Evita operaciones pesadas en el onClick usa APIs asíncronas si necesitas llamadas a la red.
- Testea con teclado: Tab, Enter, y barras de herramientas contextuales deben ser navegables.
Depuración y errores comunes
- No aparece la toolbar: comprobar que el script está encolado correctamente y que el bloque está registrado con ese editor_script.
- Iconos que no se muestran: verificar que la prop icon recibe un string válido (dashicon) o un elemento SVG/Componente Icon.
- Los atributos no se almacenan: revisar la definición de attributes en registerBlockType (tipo correcto y source/selector si procede).
- Estilos no cargan en editor: asegurarse de registrar editor_style o encolar CSS con admin_enqueue_scripts para el editor.
Consejos y optimizaciones
- Mantén la toolbar compacta: solo las acciones más usadas. El resto en el Inspector.
- Reutiliza componentes: crea pequeñas funciones para botones repetidos.
- Versiona assets y usa filemtime en PHP para evitar caché de navegador durante desarrollo.
- Si el bloque tiene muchas opciones, considera un DropdownMenu en lugar de saturar la toolbar.
Conclusión
Agregar una toolbar personalizada a un bloque de Gutenberg es directo gracias a BlockControls y los componentes de la librería. Con los ejemplos de este artículo cubres los casos más habituales: botones toggle, dropdowns, iconos SVG, inyección en bloques existentes, y registro de assets desde PHP. Aplicando las buenas prácticas de accesibilidad y rendimiento tendrás una integración sólida con el editor.
Enlaces de interés
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |