Cómo crear un bloque Gutenberg personalizado — Paso a Paso#

🛠 Requisitos previos#

• Entorno local de WordPress
• Node.js y npm instalados
• Conocimientos básicos de JavaScript (ES6+), React y JSX
• Editor de código (VSCode, Sublime, etc.)

🔧 Paso 1: Generar estructura inicial#

1. Abre tu terminal y dirígete a wp-content/plugins/

2. Ejecuta:

   npx @wordpress/create-block@latest my-custom-block
   

3. Esto creará una carpeta con archivos base del bloque.

📁 Paso 2: Estructura de archivos#

Revisa que tu plugin tenga carpetas como:

• src/ — código JS y CSS
• block.json — metadatos del bloque
• render.php — si usas render dinámico

⚙️ Paso 3: Configurar block.json#

{
  "apiVersion": 3,
  "name": "namespace/my-custom-block",
  "title": "Mi Bloque Personalizado",
  "category": "widgets",
  "icon": "smiley",
  "description": "Un bloque que hace X cosa.",
  "supports": {
    "html": false,
    "color": { "text": true },
    "typography": { "fontSize": true }
  },
  "attributes": {
    "texto": { "type": "string", "default": "Hola mundo" },
    "mostrarSubtitulo": { "type": "boolean", "default": false }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./editor.css",
  "style": "file:./style.css",
  "render": "file:./render.php"
}

🖊 Paso 4: Editar el bloque (edit.js)#

import { useBlockProps, RichText, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, ToggleControl, TextControl } from '@wordpress/components';

export default function Edit({ attributes, setAttributes }) {
  const { texto, mostrarSubtitulo } = attributes;

  return (
    <>
      <InspectorControls>
        <PanelBody title="Ajustes adicionales">
          <ToggleControl
            label="Mostrar subtítulo"
            checked={ mostrarSubtitulo }
            onChange={ (val) => setAttributes({ mostrarSubtitulo: val }) }
          />
          { mostrarSubtitulo && (
            <TextControl
              label="Texto del subtítulo"
              value={ attributes.subtitulo || '' }
              onChange={ (val) => setAttributes({ subtitulo: val }) }
            />
          )}
        </PanelBody>
      </InspectorControls>
      <div {...useBlockProps()}>
        <RichText
          tagName="h2"
          value={ texto }
          onChange={ (val) => setAttributes({ texto: val }) }
          placeholder="Escribe el texto principal..."
        />
        { mostrarSubtitulo && attributes.subtitulo && (
          <RichText
            tagName="h3"
            value={ attributes.subtitulo }
            onChange={ (val) => setAttributes({ subtitulo: val }) }
          />
        )}
      </div>
    
  );
}

💾 Paso 5: Guardar (bloque estático o dinámico)#

Si es estático, define la función save en JS. Si es dinámico, usa render.php para la salida HTML en el servidor.

🎨 Paso 6: Estilos y scripts#

Agrega CSS para editor y frontend. Puedes hacerlo desde editorStyle y style en block.json.

🚀 Paso 7: Compilar#

npm run start   // modo desarrollo
npm run build   // modo producción

✅ Paso 8: Activar y usar el bloque#

Ve a «Plugins» en WordPress y activa el plugin. Luego inserta tu bloque personalizado desde el editor Gutenberg.

📚 Recursos útiles#

• Block Editor Handbook (oficial)
• Guía de bloques personalizados (Kinsta)
• Comparativa con ACF Blocks

📌 Conclusión#

Los bloques personalizados de Gutenberg te ofrecen control total sobre la edición en WordPress. Domina su estructura y potencia tus desarrollos.

Meta descripción:#

Crea tu bloque personalizado de Gutenberg en WordPress con esta guía completa: estructura, atributos, edición, guardado, estilos y despliegue. Paso a paso fácil.

Etiquetas:#

#WordPress #Gutenberg #BloquePersonalizado #DesarrolloWeb #TutorialWP #React #JavaScript #PluginWP #DesarrolloWordPress