Deprecación de Bloques Gutenberg: Actualiza Sin Romper el Contenido

Resumen

Actualizar un bloque Gutenberg a menudo rompe las publicaciones existentes que usan la versión anterior. Este artículo te muestra cómo usar la propiedad deprecated en block.json para mantener la compatibilidad hacia atrás. Aprenderás los pasos exactos para capturar el marcado actual del bloque, definir una o más versiones obsoletas y mapear atributos correctamente. Cubriremos tanto bloques estáticos como dinámicos, con ejemplos prácticos. El artículo también cuestiona la suposición de que la deprecación es siempre el mejor enfoque, discutiendo cuándo una ruptura limpia podría ser mejor. Al final, podrás actualizar tus bloques con confianza sin romper el contenido de tus usuarios.

El Escenario del Cambio Rupturista

Lanzaste un bloque de testimonio personalizado hace seis meses. Genera un simple <div> con una cita y un nombre de autor. Ahora tu cliente quiere un nuevo diseño: el autor debe aparecer sobre la cita, con una clase CSS diferente. Actualizas la función save y render_callback del bloque. Pruebas en una publicación nueva—se ve genial. Luego navegas a una publicación antigua que usa el bloque. Desastre: el texto de la cita ha desaparecido, el autor está en el lugar equivocado y el estilo está desalineado. Acabas de romper cada página que usa el bloque.

Este es el problema clásico de "cambio rupturista" en el desarrollo de bloques Gutenberg. Los bloques son esencialmente estructuras de datos combinadas con marcado. Cuando cambias el marcado, el editor no puede mapear automáticamente el contenido antiguo a la nueva estructura. El resultado es ya sea un error de validación (el bloque se vuelve inválido) o—peor—una corrupción silenciosa donde el bloque se renderiza incorrectamente.

¿Qué es la Deprecación de Bloques?

La deprecación de bloques es el mecanismo integrado de Gutenberg para manejar cambios de versión. Al definir un array deprecated en el block.json de tu bloque, le dices al editor: "Si encuentras un bloque que coincida con una de estas versiones antiguas, transfórmalo a la versión actual." Cada entrada obsoleta especifica los attributes, supports y la función save (o render_callback) anteriores. Cuando el editor carga un bloque antiguo, recorre el array de deprecated en orden y aplica la primera transformación que coincida.

Esta característica a menudo está infrautilizada porque los desarrolladores asumen que nunca necesitarán cambiar el marcado de un bloque. Pero en proyectos reales, los requisitos evolucionan. Si omites la deprecación, o fuerzas a los usuarios a eliminar y volver a insertar bloques (mala experiencia) o mantienes dos versiones separadas del bloque (desordenado). El manual oficial de desarrolladores de WordPress cubre esto en el Manual del Editor de Bloques, pero faltan tutoriales prácticos.

Paso 1: Capturar el Estado Actual

Antes de hacer cualquier cambio, registra la salida exacta de save (o render_callback para bloques dinámicos) y los attributes que tu bloque usa actualmente. Piénsalo como tomar una instantánea. Para bloques estáticos, guarda el JSX devuelto por la función save. Para bloques dinámicos, guarda el marcado PHP generado por render_callback.

Crea un nuevo archivo en tu plugin llamado deprecated.js (o similar) y almacena allí la función save antigua. Alternativamente, mantén las versiones obsoletas directamente en el archivo JavaScript principal del bloque. La clave es preservar este código exactamente como estaba cuando el bloque se implementó por primera vez.

Paso 2: Definir tus Versiones Obsoletas

En tu block.json, añade un array deprecated. Cada entrada es un objeto que puede incluir:

• attributes (objeto): Las definiciones de atributos anteriores.
• supports (objeto): Cualquier configuración de soporte anterior que haya cambiado.
• save (función o cadena): La función save anterior. Para bloques solo JavaScript, importarás la función antigua. Para bloques dinámicos renderizados en PHP, puedes usar migrate y render_callback en su lugar.
• migrate (función): Una función que mapea atributos antiguos a nuevos (opcional).

Ejemplo:

"deprecated": [
  {
    "attributes": {
      "quote": { "type": "string", "source": "html", "selector": ".quote" },
      "author": { "type": "string", "source": "html", "selector": ".author" }
    },
    "supports": {},
    "save": "() => <div className=\"testimonial-legacy\"><p className=\"quote\">{attributes.quote}</p><p className=\"author\">{attributes.author}</p></div>"
  }
]

Nota: La función save en block.json normalmente se define en JavaScript. Si estás usando un script externo, necesitarás encolarlo y referenciar el nombre de la función. Alternativamente, puedes incluir la función como una cadena (aunque esto no se recomienda para bloques complejos).

Paso 3: Mapear Atributos

A menudo, cambias no solo el marcado sino también los nombres o fuentes de los atributos. Por ejemplo, podrías pasar de almacenar el autor como una cadena simple a un campo de texto enriquecido. En tales casos, usa la propiedad migrate para transformar atributos antiguos a nuevos.

migrate: (attributes) => {
  return {
    quote: attributes.quote,
    author: { content: attributes.author, level: 2 }
  };
}

Si no proporcionas una función migrate, el editor simplemente pasará los atributos antiguos directamente al nuevo bloque. Esto podría causar errores si los nombres de los atributos cambiaron.

Paso 4: Probar con Contenido Real

Después de definir la versión obsoleta, prueba a fondo. Crea una nueva publicación, inserta el bloque antiguo (puedes simularlo pegando el código de bloque serializado de una publicación existente) y verifica que se convierta a la nueva versión sin errores de validación. También prueba editar y guardar el bloque convertido. Repite para múltiples versiones obsoletas si las tienes.

Para bloques dinámicos, el proceso es similar pero con un giro: la función save para un bloque dinámico normalmente devuelve null (el bloque se renderiza vía PHP). En la entrada obsoleta, puedes establecer save al marcado estático anterior que se usaba antes de cambiar a renderizado dinámico, o usar un render_callback en PHP que maneje tanto estructuras de atributos antiguas como nuevas. Esto es más complejo pero factible.

Advertencias y Compensaciones

La deprecación es poderosa, pero tiene inconvenientes. Cada versión obsoleta agrega código a tu plugin. Con el tiempo, puedes terminar con una cadena de cinco o seis versiones heredadas que rara vez se usan pero deben mantenerse. El equipo central de WordPress recomienda mantener al menos dos versiones atrás, pero más allá de eso, podrías considerar una ruptura limpia si el número de publicaciones afectadas es pequeño.

Otro matiz: el orden de las entradas obsoletas importa. El editor itera a través del array desde el índice 0 hacia arriba y usa la primera coincidencia. Si dos versiones obsoletas son similares, podría aplicarse la incorrecta. Siempre lista la versión obsoleta más reciente primero (la que precede directamente a la versión actual).

Finalmente, la deprecación no maneja contenido que fue editado usando un cambio de estilo en todo el sitio (por ejemplo, a través de theme.json). Si la apariencia de tu bloque dependía de estilos globales que han cambiado, la deprecación no se ajustará a eso. Puede que necesites agregar un script de migración que se ejecute al guardar o mediante un hook de actualización del plugin.

Cuando la Deprecación no es la Respuesta

La mayoría de los tutoriales presentan la deprecación como obligatoria. En realidad, hay situaciones donde una ruptura limpia es mejor. Si tu bloque es nuevo y se usa solo en un puñado de publicaciones, actualizar manualmente esas pocas instancias podría ser más rápido que escribir y probar código de deprecación. De manera similar, si el modelo de datos subyacente del bloque es fundamentalmente diferente (por ejemplo, estás fusionando dos bloques en uno), la deprecación puede no ser lo suficientemente flexible. En ese caso, escribe un script de migración único que se ejecute cuando el plugin se actualice, convirtiendo bloques antiguos al nuevo formato.

Otro punto contrario: la deprecación no debe usarse como sustituto de un buen diseño. Si anticipas cambios frecuentes, diseña tu bloque con versionado en mente desde el principio—por ejemplo, almacenando un atributo version y usando renderizado condicional. Este enfoque, discutido en Más Allá de los Bloques Básicos, es más liviano que la deprecación pero requiere previsión.

Conclusión

La deprecación de bloques es una herramienta esencial para cualquier desarrollador serio de Gutenberg. Te permite evolucionar tus bloques sin romper el contenido de los usuarios. Los pasos clave son: capturar el estado actual, definir la versión obsoleta en block.json, mapear atributos si es necesario, y probar con contenido real. Pero recuerda que la deprecación conlleva costos de mantenimiento. A veces una ruptura limpia o un diseño de bloque versionado es más pragmático. Usa la deprecación estratégicamente, no automáticamente, y tus bloques se mantendrán robustos a través de muchas actualizaciones.

Para una perspectiva más amplia sobre la construcción de plugins mantenibles, consulta Construyendo Plugins de WordPress Robusto. Y si eres nuevo en el desarrollo de bloques, Más Allá de los Bloques Básicos te ayudará a comenzar.