Dépréciation de blocs (Block Deprecation)

Définition : La dépréciation de blocs permet à un type de reconnaître ses anciens formats d’attributs ou de HTML. Elle facilite la migration des contenus déjà publiés lors d’une évolution compatible.

Comprendre et utiliser

À quoi cela sert ?

Elle protège l’historique éditorial : un bloc ancien doit pouvoir être relu et, si nécessaire, converti vers la nouvelle structure sans exiger la réécriture des articles.

Comment cela fonctionne ?

La propriété deprecated énumère d’anciennes définitions comprenant notamment attributes, save et éventuellement migrate. Le moteur essaie les versions déclarées selon ses règles de validation.

Dans quel contexte l’utiliser ?

À envisager dès qu’un bloc statique change de balisage ou de contrat de données et que des articles créés avec l’ancienne version existent encore.

Cas concret : ATOOLPHA

Une carte ATOOLPHA utilisait une balise div puis adopte section : les anciens articles doivent être relus sans erreur de bloc invalide.

Exemple de code commenté

Extrait documentaire : le contexte WordPress du plugin/éditeur et les dépendances décrites sont nécessaires ; ne pas coller dans le contenu d’une page.

const oldVersion = {
    attributes: { text: { type: 'string', default: '' } },
    save: ( { attributes } ) => wp.element.createElement(
        'div', {}, attributes.text
    ),
};
// À inclure dans deprecated: [ oldVersion ] du type de bloc.

Décryptage de l’exemple

L’ancienne fonction save décrit la sortie historique attendue. La définition courante du bloc doit fournir sa nouvelle version, avec migrate si les attributs ou enfants doivent être transformés.

Résultat attendu

L’éditeur peut reconnaître le balisage historique, puis sauvegarder le contenu selon la définition actuelle, sous réserve d’une migration correcte.

Atelier pratique de vérification

Conserver une publication enregistrée avec une ancienne structure HTML, puis modifier la fonction save du bloc dans un environnement local. Déclarer la définition historique dans deprecated et réouvrir l’article. Tester une migration et noter si les attributs sont préservés. Ajouter ce contenu aux fixtures de régression.

Précautions et limites

Les dépréciations ne constituent pas une chaîne automatique d’étapes successives. Tester chaque ancienne représentation sur des contenus réels ou fixtures reproductibles.

Contrôle avant intégration dans un plugin

Conserver une fixture par ancien format significatif. Tester que l’ouverture de l’article historique ne détruit pas ses données et que la migration vers la version courante produit une sortie stable.

À ne pas confondre

Déprécier un format de bloc ne signifie pas désactiver immédiatement la fonctionnalité ; il s’agit ici d’un mécanisme de compatibilité des contenus sauvegardés.