Le manuel du développeur de blocs distingue implicitement deux façons de stocker une donnée : dans les attributs propres au bloc, ou dans une entité partagée par plusieurs blocs, comme l’article lui-même. Cette distinction, rarement énoncée aussi clairement dans un cahier des charges, mène pourtant régulièrement à des bugs difficiles à diagnostiquer, notamment quand plusieurs blocs sont censés refléter la même information.
Ce billet pose une distinction claire entre ces deux mécanismes de stockage de données, avec un exemple concret pour chacun.
Définition : ce que stocke réellement un attribut de bloc
Un attribut de bloc classique, déclaré dans la définition JavaScript du bloc, est sérialisé directement dans le contenu HTML de l’article, sous forme de commentaire de bloc. Cette valeur appartient entièrement au bloc : elle existe uniquement là où le bloc est inséré, et se duplique si le bloc est copié ailleurs sur le même article ou sur un autre.
<!-- wp:mon-plugin/note-etoiles {"note":4} /-->Cette note de 4, dans cet exemple, n’existe que dans ce bloc précis. Si le même bloc est inséré une seconde fois sur la même page, il faudra saisir à nouveau la note : rien ne relie les deux instances entre elles.
Fonctionnement interne de useEntityProp
useEntityProp fonctionne très différemment : il lit et écrit directement une propriété de l’entité elle-même, généralement l’article en cours d’édition, via le magasin de données central de WordPress (@wordpress/core-data). La valeur n’appartient pas au bloc, mais à l’article, ce qui signifie que tout bloc utilisant ce même hook sur cette même propriété affiche et modifie la même donnée, en temps réel, sans aucune synchronisation manuelle à écrire.
import { useEntityProp } from '@wordpress/core-data';
function Editer( { context } ) {
const [ sousTitre, setSousTitre ] = useEntityProp(
'postType', 'article', 'meta'
);
return (
<RichText
value={ sousTitre.sous_titre_article }
onChange={ ( valeur ) =>
setSousTitre( { ...sousTitre, sous_titre_article: valeur } )
}
/>
);
}
Cas d’usage : quand choisir l’un plutôt que l’autre
Un attribut de bloc classique convient parfaitement à une donnée propre au bloc lui-même, sans équivalent ailleurs sur le site : une couleur de fond, un texte de bouton, une disposition en colonnes. Rien de cette donnée n’a de sens en dehors du bloc qui la porte.
useEntityProp, à l’inverse, s’impose dès qu’une donnée appartient conceptuellement à l’article lui-même, et doit rester cohérente quel que soit l’endroit où elle est affichée : un sous-titre affiché à la fois en haut de l’article et dans une liste d’articles liés, une note globale attribuée à l’article, un statut éditorial personnalisé.
Le piège le plus fréquent
Le piège classique consiste à stocker en attribut de bloc une donnée qui devrait en réalité être liée à l’article : une note affichée à la fois dans un bloc « avis » et dans un bloc « résumé » placé plus bas sur la même page. Avec un attribut classique, modifier la note dans un bloc ne met jamais à jour l’autre, ce qui finit toujours par produire un contenu incohérent aux yeux d’un rédacteur qui ne comprend pas pourquoi les deux chiffres divergent.
- Donnée propre à l’apparence du bloc : attribut sérialisé classique
- Donnée censée rester identique partout où elle apparaît sur l’article :
useEntityProp, adossé à une méta-donnée d’article - Donnée partagée entre un bloc parent et ses blocs enfants sur la même insertion : plutôt le contexte de bloc, sujet à part
Les pièges à connaître avant de se lancer
La méta-donnée ciblée par useEntityProp doit être enregistrée avec register_post_meta() et l’option show_in_rest activée, faute de quoi le hook ne trouvera simplement rien à lire ni à écrire. Un oubli fréquent consiste aussi à ne pas déclarer de valeur par défaut cohérente côté PHP, ce qui produit une valeur vide difficile à distinguer d’une véritable absence de donnée.
Avant d’écrire le moindre code, on pose toujours la question suivante en réunion de cadrage : « cette donnée doit-elle rester identique partout où elle apparaît sur l’article, ou appartient-elle uniquement à ce bloc précis ? » La réponse tranche immédiatement entre les deux approches.
En résumé
Attribut de bloc sérialisé et donnée liée par useEntityProp répondent à deux besoins différents, et les confondre produit des bugs de synchronisation difficiles à repérer sans comprendre cette distinction de fond. Poser la bonne question dès la conception du bloc évite la quasi-totalité de ces problèmes.
