Dépréciation des blocs Gutenberg : mise à jour sans casser le contenu

Résumé

Mettre à jour un bloc Gutenberg casse souvent les articles existants qui utilisent l'ancienne version. Cet article vous montre comment utiliser la propriété deprecated dans block.json pour maintenir la rétrocompatibilité. Vous apprendrez les étapes exactes pour capturer le balisage actuel du bloc, définir une ou plusieurs versions dépréciées, et mapper correctement les attributs. Nous couvrirons les blocs statiques et dynamiques, avec des exemples pratiques. L'article remet également en question l'hypothèse selon laquelle la dépréciation est toujours la meilleure approche, en discutant quand une rupture nette pourrait être préférable. À la fin, vous serez en mesure de mettre à jour vos blocs en toute confiance sans casser le contenu de vos utilisateurs.

Le scénario de changement cassant

Vous avez lancé un bloc de témoignage personnalisé il y a six mois. Il produit un simple <div> avec une citation et un nom d'auteur. Maintenant, votre client souhaite un nouveau design : l'auteur doit apparaître au-dessus de la citation, avec une classe CSS différente. Vous mettez à jour la fonction save du bloc et render_callback. Vous testez sur un nouvel article—c'est parfait. Puis vous naviguez vers un ancien article qui utilise le bloc. Catastrophe : le texte de la citation a disparu, l'auteur est au mauvais endroit, et le style est décalé. Vous venez de casser toutes les pages qui utilisent le bloc.

C'est le problème classique de "changement cassant" dans le développement de blocs Gutenberg. Les blocs sont essentiellement des structures de données combinées à du balisage. Lorsque vous modifiez le balisage, l'éditeur ne peut pas mapper automatiquement l'ancien contenu à la nouvelle structure. Le résultat est soit une erreur de validation (le bloc devient invalide), soit—pire—une corruption silencieuse où le bloc s'affiche incorrectement.

Qu'est-ce que la dépréciation de bloc ?

La dépréciation de bloc est le mécanisme intégré de Gutenberg pour gérer les changements de version. En définissant un tableau deprecated dans le block.json de votre bloc, vous dites à l'éditeur : "Si vous rencontrez un bloc qui correspond à l'une de ces anciennes versions, transformez-le en version actuelle." Chaque entrée dépréciée spécifie les attributes, supports et la fonction save (ou render_callback) précédents. Lorsque l'éditeur charge un ancien bloc, il parcourt le tableau déprécié dans l'ordre et applique la première transformation correspondante.

Cette fonctionnalité est souvent sous-utilisée car les développeurs supposent qu'ils n'auront jamais besoin de modifier le balisage d'un bloc. Mais dans les projets réels, les exigences évoluent. Si vous sautez la dépréciation, vous forcez soit les utilisateurs à supprimer et réinsérer les blocs (mauvaise expérience), soit à maintenir deux versions séparées du bloc (désordonné). Le manuel officiel du développeur WordPress couvre cela dans le Manuel de l'éditeur de blocs, mais les tutoriels pratiques manquent.

Étape 1 : Capturer l'état actuel

Avant d'apporter des modifications, enregistrez exactement la sortie save (ou render_callback pour les blocs dynamiques) et les attributes que votre bloc utilise actuellement. Considérez cela comme une capture d'écran. Pour les blocs statiques, sauvegardez le JSX renvoyé par la fonction save. Pour les blocs dynamiques, sauvegardez le balisage PHP généré par render_callback.

Créez un nouveau fichier dans votre plugin appelé deprecated.js (ou similaire) et stockez-y l'ancienne fonction save. Alternativement, conservez les versions dépréciées directement dans le fichier JavaScript principal du bloc. L'essentiel est de préserver ce code exactement tel qu'il était lors du premier déploiement du bloc.

Étape 2 : Définir vos versions dépréciées

Dans votre block.json, ajoutez un tableau deprecated. Chaque entrée est un objet qui peut inclure :

• attributes (objet) : Les définitions d'attributs précédentes.
• supports (objet) : Tout paramètre de support précédent qui a changé.
• save (fonction ou chaîne) : La fonction save précédente. Pour les blocs JavaScript uniquement, vous importerez l'ancienne fonction. Pour les blocs dynamiques rendus en PHP, vous pouvez utiliser migrate et render_callback à la place.
• migrate (fonction) : Une fonction qui mappe les anciens attributs aux nouveaux (optionnel).

Exemple :

"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>"
  }
]

Remarque : La fonction save dans block.json est généralement définie en JavaScript. Si vous utilisez un script externe, vous devrez le mettre en file d'attente et référencer le nom de la fonction. Alternativement, vous pouvez intégrer la fonction sous forme de chaîne (bien que cela ne soit pas recommandé pour les blocs complexes).

Étape 3 : Mapper les attributs

Souvent, vous modifiez non seulement le balisage, mais aussi les noms ou sources d'attributs. Par exemple, vous pourriez passer du stockage de l'auteur sous forme de chaîne simple à un champ de texte enrichi. Dans de tels cas, utilisez la propriété migrate pour transformer les anciens attributs en nouveaux.

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

Si vous ne fournissez pas de fonction migrate, l'éditeur passera simplement les anciens attributs directement au nouveau bloc. Cela pourrait causer des erreurs si les noms d'attributs ont changé.

Étape 4 : Tester avec du contenu réel

Après avoir défini la version dépréciée, testez minutieusement. Créez un nouvel article, insérez l'ancien bloc (vous pouvez simuler en collant le code de bloc sérialisé d'un article existant), et vérifiez qu'il se convertit en nouvelle version sans erreurs de validation. Testez également la modification et l'enregistrement du bloc converti. Répétez pour plusieurs versions dépréciées si vous en avez.

Pour les blocs dynamiques, le processus est similaire mais avec une particularité : la fonction save d'un bloc dynamique renvoie généralement null (le bloc s'affiche via PHP). Dans l'entrée dépréciée, vous pouvez soit définir save sur l'ancien balisage statique qui était utilisé avant de passer au rendu dynamique, soit utiliser un render_callback en PHP qui gère à la fois les anciennes et nouvelles structures d'attributs. C'est plus complexe mais faisable.

Mises en garde et compromis

La dépréciation est puissante, mais elle a des inconvénients. Chaque version dépréciée ajoute du code à votre plugin. Au fil du temps, vous pouvez vous retrouver avec une chaîne de cinq ou six versions héritées rarement utilisées mais qui doivent être maintenues. L'équipe de base de WordPress recommande de conserver au moins deux versions en arrière, mais au-delà, vous pourriez envisager une rupture nette si le nombre d'articles concernés est faible.

Autre nuance : l'ordre des entrées dépréciées est important. L'éditeur parcourt le tableau de l'index 0 vers le haut et utilise la première correspondance. Si deux versions dépréciées sont similaires, la mauvaise pourrait être appliquée. Listez toujours la version dépréciée la plus récente en premier (celle qui précède directement la version actuelle).

Enfin, la dépréciation ne gère pas le contenu qui a été modifié par un changement de style à l'échelle du site (par exemple, via theme.json). Si l'apparence de votre bloc reposait sur des styles globaux qui ont depuis changé, la dépréciation ne s'adaptera pas. Vous devrez peut-être ajouter un script de migration qui s'exécute lors de la sauvegarde ou via un hook de mise à jour du plugin.

Quand la dépréciation n'est pas la réponse

La plupart des tutoriels présentent la dépréciation comme obligatoire. En réalité, il existe des situations où une rupture nette est préférable. Si votre bloc est nouveau et utilisé dans seulement une poignée d'articles, mettre à jour manuellement ces quelques instances peut être plus rapide que d'écrire et tester du code de dépréciation. De même, si le modèle de données sous-jacent du bloc est fondamentalement différent (par exemple, vous fusionnez deux blocs en un), la dépréciation peut ne pas être assez flexible. Dans ce cas, écrivez un script de migration unique qui s'exécute lors de la mise à jour du plugin, convertissant les anciens blocs au nouveau format.

Autre point iconoclaste : la dépréciation ne doit pas être utilisée comme substitut à une bonne conception. Si vous anticipez des changements fréquents, concevez votre bloc avec un versionnage en tête dès le départ—par exemple, en stockant un attribut version et en utilisant un rendu conditionnel. Cette approche, discutée dans Au-delà des blocs de base, est plus légère que la dépréciation mais nécessite de la prévoyance.

Conclusion

La dépréciation de bloc est un outil essentiel pour tout développeur Gutenberg sérieux. Elle vous permet de faire évoluer vos blocs sans casser le contenu des utilisateurs. Les étapes clés sont : capturer l'état actuel, définir la version dépréciée dans block.json, mapper les attributs si nécessaire, et tester avec du contenu réel. Mais rappelez-vous que la dépréciation a un coût de maintenance. Parfois, une rupture nette ou une conception de bloc versionnée est plus pragmatique. Utilisez la dépréciation de manière stratégique, pas automatique, et vos blocs resteront robustes à travers de nombreuses mises à jour.

Pour une perspective plus large sur la création de plugins maintenables, consultez Créer des plugins WordPress robustes. Et si vous débutez dans le développement de blocs, Au-delà des blocs de base vous aidera à démarrer.