Crear bloques personalizados con registerBlockType

Introducción

En el ecosistema de WordPress, el editor de bloques (Gutenberg) se ha convertido en la forma preferida para crear contenido dinámico y flexible. Una de sus mayores ventajas es la posibilidad de crear bloques personalizados ajustados a necesidades muy específicas. El núcleo de este proceso es la función registerBlockType, que permite registrar cada bloque con todas sus propiedades y comportamientos.

¿Qué es registerBlockType

registerBlockType es la API de JavaScript que proporciona WordPress para definir nuevos bloques en el editor. Está documentada en el repositorio oficial de desarrolladores de WordPress y es el punto de partida para la creación de bloques tanto simples como complejos.

Puede consultarse la documentación oficial en developer.wordpress.org.

Preparación del Entorno

Requisitos previos

• Node.js (>= 14.x) y npm o yarn
• WordPress 5.0 o superior con Gutenberg activado
• Conocimientos básicos de JavaScript moderno (ESNext) y React

Instalación de herramientas

1. Crear un plugin o un tema con carpeta src.
2. Ejecutar npm init -y y luego npm install @wordpress/scripts --save-dev.
3. En package.json, agregar un script:

  
scripts: {
  build: wp-scripts build,
  start: wp-scripts start
}

  

Estructura básica de un bloque

Un bloque se compone, esencialmente, de:

• registerBlockType: registro y configuración.
• edit: interfaz de edición en el editor.
• save: representación en el front-end.

Registrar un bloque con registerBlockType

La sintaxis básica es:

import { registerBlockType } from @wordpress/blocks

registerBlockType( mi-plugin/mi-bloque, {
  title: Mi Bloque,
  icon: smiley,
  category: widgets,
  attributes: {
    contenido: {
      type: string,
      source: html,
      selector: p
    }
  },
  edit: ( props ) => {
    // Interfaz de edición
  },
  save: ( props ) => {
    // Salida HTML
  }
} )

  

Parámetros principales

Campo	Descripción	Ejemplo
name	Identificador único del bloque.	mi-plugin/mi-bloque
title	Título que verá el usuario.	Mi Bloque Personalizado
icon	Icono en el selector de bloques.	format-image
category	Categoría donde aparece.	common
attributes	Propiedades que almacena el bloque.	Objeto JSON
edit	Componente de edición (React).	Función o clase
save	Función que devuelve HTML.	Función

Personalización avanzada

Más allá de la configuración básica, podemos:

• Atributos complejos: usar attribute.source=query para colecciones.
• InnerBlocks: permitir bloques anidados (layouts configurables).
• Bloque dinámico: usar PHP con render_callback.
• Variaciones: predefinir estilos o contenidos iniciales.
• Soporte de estilos: declarar supports: { color: true, spacing: true }.

Publicar y probar el bloque

1. Ejecutar npm run build para generar build/index.js y build/index.css.
2. Encolar los archivos en PHP (wp_enqueue_script y wp_enqueue_style) dentro de tu plugin o tema.
3. Acceder al editor y buscar tu bloque en la categoría asignada.
4. Probar su edición, atributos y guardado de contenido.

Buenas prácticas

• Namespace único: evita conflictos con otros plugins.
• Documentación interna: comenta tu código con JSDoc.
• Pruebas de PHP y JS: utiliza PHPUnit y Jest.
• Accesibilidad: asegúrate de cumplir WCAG en la interfaz del bloque.
• Internacionalización: utiliza funciones __ y _x con dominio de texto.

Recursos adicionales

• WordPress Block Editor Handbook
• Repositorio oficial de Gutenberg (GitHub)
• MDN Web Docs (JavaScript y CSS)