save (fonction de bloc)

Définition : La fonction save d’un bloc statique décrit le HTML sauvegardé dans le contenu d’une publication. Elle reçoit les attributs et doit produire un résultat déterministe pour éviter les invalidations.

Comprendre et utiliser

À quoi cela sert ?

Elle constitue le contrat de sérialisation du bloc. WordPress peut comparer la représentation sauvegardée à celle que le type de bloc courant régénère lors de l’ouverture d’un article.

Comment cela fonctionne ?

save doit dépendre uniquement des attributs persistants pertinents. Pour des données actualisées à chaque consultation, préférer un bloc dynamique et un rendu serveur.

Dans quel contexte l’utiliser ?

À utiliser lorsque le bloc a une sortie HTML stable qui doit demeurer visible même si le plugin est momentanément désactivé.

Cas concret : ATOOLPHA

Une carte ATOOLPHA affiche une phrase enregistrée dans une balise p, avec un HTML identique lors des éditions successives.

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 { createElement } = wp.element;
const { useBlockProps } = wp.blockEditor;
function SaveCard( { attributes } ) {
    return createElement(
        'p', useBlockProps.save(), attributes.message || ''
    );
}

Décryptage de l’exemple

L’appel useBlockProps.save() ajoute les propriétés d’enveloppe nécessaires. La valeur message est fournie par les attributs sauvegardés ; aucune information extérieure n’est demandée.

Résultat attendu

Le paragraphe est sérialisé dans post_content lorsque le bloc statique est sauvegardé par l’éditeur.

Atelier pratique de vérification

Créer un bloc statique à HTML stable, enregistrer, puis inspecter le HTML sérialisé. Ajouter temporairement à save une date calculée à chaque rendu et constater le risque d’invalidation. Revenir à une sortie déterministe et conserver l’ancien article comme fixture pour les futures mises à jour.

Précautions et limites

Ne pas utiliser Date.now(), des valeurs aléatoires ou des lectures réseau dans save : le HTML recalculé pourrait ne plus correspondre au contenu ancien.

Contrôle avant intégration dans un plugin

Conserver une fixture du HTML historique et tester l’ouverture sous la nouvelle version du bloc. Les sorties de save doivent rester déterministes et les modifications structurelles doivent être accompagnées d’une dépréciation compatible.

À ne pas confondre

save produit la structure persistante côté éditeur ; render_callback exécute une fonction PHP au rendu public pour les blocs dynamiques.

Diagnostic et dépannage avancés

Face à une erreur de validation, comparer le HTML réellement enregistré à la sortie de save et examiner les changements de classe ou de structure du composant.