« Ce bloc contient une erreur inattendue » : ce message, familier de tout développeur qui a fait évoluer un bloc en production, apparaît quand le save actuel ne parvient plus à reproduire fidèlement le HTML enregistré pour du contenu ancien. Le tableau deprecated existe précisément pour éviter ce message. Ce guide s’adresse aux mainteneurs de blocs distribués qui doivent faire évoluer une structure sans casser le contenu déjà publié ; il ne traite pas des mythes généraux de maintenance logicielle, qui relèvent d’un autre sujet.
Le mécanisme repose sur un principe simple : quand WordPress charge un contenu de bloc et que le save actuel ne produit pas exactement le même HTML que celui enregistré, l’éditeur parcourt les entrées du tableau deprecated, dans l’ordre, jusqu’à trouver une version dont le save correspond au contenu existant.
Ce que contient une entrée deprecated
Chaque entrée du tableau reproduit la structure attendue au moment où le bloc portait cette ancienne forme : les attributs tels qu’ils étaient déclarés alors, et la fonction save qui produisait le HTML correspondant. Prenons un bloc qui, à sa création, enregistrait un simple texte dans un attribut libelle, avant de migrer vers une structure à deux champs distincts, titre et description :
const deprecated = [
{
attributes: {
libelle: {
type: 'string',
source: 'html',
selector: 'p',
},
},
save( { attributes } ) {
return <p>{ attributes.libelle }</p>;
},
},
];La fonction migrate pour convertir les anciennes valeurs
Une entrée deprecated peut aller plus loin qu’une simple compatibilité d’affichage, grâce à une fonction migrate qui convertit les anciens attributs vers le nouveau schéma, de façon à ce que le contenu ancien profite lui aussi, une fois converti, des nouvelles fonctionnalités du bloc :
const deprecated = [
{
attributes: {
libelle: {
type: 'string',
source: 'html',
selector: 'p',
},
},
migrate( attributes ) {
return {
titre: attributes.libelle,
description: '',
};
},
save( { attributes } ) {
return <p>{ attributes.libelle }</p>;
},
},
];
Une fois la correspondance trouvée et la migration appliquée, WordPress réenregistre automatiquement le bloc avec le save actuel, dès la prochaine sauvegarde de l’article concerné, sans intervention manuelle de l’utilisateur.
L’ordre des entrées, un détail qui compte
WordPress teste les entrées du tableau deprecated dans l’ordre où elles apparaissent, la plus récente étant conventionnellement placée en premier. Cet ordre a une importance réelle sur un bloc qui a connu plusieurs migrations successives : placer une ancienne entrée avant une plus récente peut, dans de rares cas de chevauchement de structure, faire correspondre le contenu à la mauvaise version.
Quand aucune entrée ne correspond
Si aucune entrée du tableau deprecated, ni le save actuel, ne parvient à reproduire le HTML enregistré, WordPress affiche le bloc en état invalide, avec une proposition de récupération ou de conversion en HTML brut. C’est le signal qu’une entrée deprecated manque, ou que sa condition isEligible optionnelle ne couvre pas correctement le cas rencontré.
- Toujours ajouter une entrée
deprecatedavant de modifier lesaved’un bloc déjà utilisé en production. - Tester la migration sur un contenu réel exporté du site concerné, pas seulement sur un exemple minimal.
- Vérifier que la fonction
migrate, si présente, couvre bien tous les champs de l’ancien schéma, y compris ceux laissés vides.
Un conseil qui évite bien des messages d’erreur en production : ne jamais supprimer une entrée
deprecatedtant qu’un contenu publié peut encore s’appuyer sur elle, même des années après son ajout.
En résumé
Le tableau deprecated transforme une modification potentiellement destructrice du save d’un bloc en une évolution transparente pour l’utilisateur final, à condition de documenter fidèlement chaque ancienne structure et, si nécessaire, de fournir une fonction migrate qui convertit les anciens attributs vers le nouveau schéma. Négliger cette étape expose directement le contenu existant à un état invalide dès la prochaine modification du bloc.
