Trois lignes de code suffisent, dans bien des cas, à relier un champ meta existant à un contrôle affiché dans l’inspecteur d’un bloc. Pas d’appel apiFetch manuel, pas d’état local à synchroniser à la main avec l’enregistrement de l’article : le hook useEntityProp, fourni par @wordpress/core-data, fait le pont directement avec l’entité en cours d’édition.
Ce hook répond à un besoin précis : afficher et modifier une valeur qui vit dans les métadonnées de l’article (ou de tout autre type d’entité géré par WordPress), depuis l’intérieur d’un bloc, comme s’il s’agissait d’un simple état React local. La donnée reste pourtant bien celle de l’article, avec tout ce que cela implique en matière de sauvegarde et de gestion des révisions.
Déclarer le champ meta côté PHP avant toute chose
Avant d’utiliser useEntityProp, la métadonnée doit exister et être exposée à l’API REST. Cela passe par register_post_meta(), avec au minimum show_in_rest à true et un type déclaré :
register_post_meta( 'post', 'duree_lecture_minutes', array(
'show_in_rest' => true,
'single' => true,
'type' => 'integer',
'default' => 0,
'auth_callback' => function () {
return current_user_can( 'edit_posts' );
},
) );Sans cette déclaration, l’entité renvoyée par l’API REST ne contiendra tout simplement pas le champ, et useEntityProp ne pourra ni le lire ni le modifier. C’est l’oubli le plus fréquent lorsqu’un champ « n’apparaît pas » côté bloc alors que le code JavaScript semble correct.
Utiliser le hook dans le composant Edit
Une fois le champ exposé, l’appel côté bloc tient en une ligne pour la lecture et l’écriture combinées :
import { useBlockProps, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, RangeControl } from '@wordpress/components';
import { useEntityProp } from '@wordpress/core-data';
import { __ } from '@wordpress/i18n';
export default function Edit( { context: { postType, postId } } ) {
const [ meta, setMeta ] = useEntityProp( 'postType', postType, 'meta', postId );
const duree = meta?.duree_lecture_minutes ?? 0;
return (
<>
<InspectorControls>
<PanelBody title={ __( 'Durée de lecture', 'mon-extension' ) }>
<RangeControl
label={ __( 'Minutes', 'mon-extension' ) }
value={ duree }
min={ 0 }
max={ 60 }
onChange={ ( valeur ) =>
setMeta( { ...meta, duree_lecture_minutes: valeur } )
}
/>
</PanelBody>
</InspectorControls>
<p { ...useBlockProps() }>
{ duree > 0
? `${ duree } min de lecture`
: __( 'Durée non renseignée', 'mon-extension' ) }
</p>
</>
);
}Le hook retourne un tableau à trois éléments : la valeur courante de la propriété demandée, une fonction pour la modifier, et la valeur complète enregistrée. Ici, la propriété demandée est meta, c’est-à-dire l’objet qui regroupe toutes les métadonnées exposées à l’API REST pour cet article. L’écriture passe donc par un objet entier, d’où la copie avec l’opérateur de décomposition : sans elle, l’appel remplacerait l’ensemble des métadonnées éditées par une seule clé.
Les paramètres sont, dans l’ordre, le type d’entité (postType), son nom (le type de contenu), la propriété, puis un identifiant facultatif. Lorsque l’identifiant est omis, le hook s’appuie sur l’entité du contexte courant de l’éditeur. Dans l’exemple, le type et l’identifiant viennent du contexte du bloc, ce qui suppose de les déclarer dans le fichier block.json.
Déclarer le contexte dans block.json
{
"apiVersion": 2,
"name": "mon-extension/duree-lecture",
"title": "Durée de lecture",
"category": "widgets",
"usesContext": [ "postType", "postId" ],
"editorScript": "file:./index.js"
}La clé usesContext indique à l’éditeur quelles valeurs fournies par les blocs parents, ou par l’éditeur lui-même, doivent arriver dans la propriété context du composant. Un bloc placé dans un article, une page ou à l’intérieur d’une boucle de requête reçoit ainsi le bon type et le bon identifiant, sans aller les chercher dans le magasin de données. C’est aussi ce qui rend le bloc réutilisable dans un modèle du site, où le contexte change d’un affichage à l’autre.
Ce qui se passe à l’enregistrement
Modifier la valeur avec setMeta ne déclenche aucun appel réseau : le changement est tenu en mémoire, comme une modification du titre ou du contenu, et marque l’article comme modifié. L’envoi vers le serveur a lieu à la sauvegarde habituelle, avec le bouton « Mettre à jour » ou « Publier ». C’est une bonne nouvelle pour l’expérience de rédaction, car l’annulation et le rétablissement restent cohérents, mais c’est aussi un piège pour celui qui s’attend à une écriture immédiate en base.
Côté affichage public, le bloc peut être dynamique : une fonction de rendu PHP lit la valeur avec get_post_meta() et produit le balisage, de sorte que le résultat ne dépende pas d’un contenu sérialisé dans l’article :
register_block_type( __DIR__ . '/build', array(
'render_callback' => function ( $attributs, $contenu, $bloc ) {
$duree = (int) get_post_meta( $bloc->context['postId'], 'duree_lecture_minutes', true );
if ( $duree < 1 ) {
return '';
}
return sprintf( '<p class="duree-lecture">%d min de lecture</p>', $duree );
},
) );Un cas concret : la durée de lecture d’un magazine
Une rédaction veut afficher une durée de lecture sur chaque article, avec la possibilité de la corriger à la main lorsque le calcul automatique se trompe. Le bloc ci-dessus suffit : la valeur calculée à l’enregistrement sert de valeur par défaut, le rédacteur ajuste le curseur dans l’inspecteur, et le modèle d’affichage des articles place le bloc sous le titre. La même métadonnée alimente ensuite un tri dans l’administration ou un filtre dans une boucle de requête, sans duplication de données.
Le meilleur état partagé est celui qu’on n’a pas à synchroniser : la donnée reste dans l’article, le bloc ne fait que la regarder et la corriger.
Les pièges fréquents
- Oublier
show_in_rest: le champ n’apparaît jamais dans l’objetmeta, et le hook renvoieundefinedsans erreur visible. - Oublier que le type de contenu doit prendre en charge les champs personnalisés (
custom-fields) pour que les métadonnées soient exposées à l’API REST. - Écrire une clé seule dans
setMetasans conserver les autres : les valeurs déjà modifiées dans la même session sont écrasées. - Utiliser une clé préfixée par un tiret bas sans déclarer de fonction
auth_callback: les clés protégées refusent l’écriture par défaut. - Déclarer un type différent entre PHP et JavaScript : une chaîne envoyée pour un champ déclaré entier est rejetée à la sauvegarde.
Quand ne pas utiliser ce hook
Pour une donnée qui n’appartient pas à une entité WordPress, comme un réglage global de l’extension ou un compteur stocké dans une table personnalisée, useEntityProp ne convient pas. Il est conçu pour les entités que le magasin de données de l’éditeur connaît : articles, pages, utilisateurs, termes, réglages du site. Pour le reste, un appel apiFetch vers une route dédiée reste la bonne approche. De même, une valeur purement locale à un bloc, qui n’a pas à survivre hors de lui, relève des attributs du bloc, pas des métadonnées.
Conclusion
useEntityProp remplace un ensemble de mécanismes que l’on écrivait autrefois à la main : appel REST, état local, rapprochement avec l’enregistrement. À condition de déclarer correctement la métadonnée côté PHP, de transmettre le contexte du bloc et de ne jamais écraser l’objet complet, il offre un pont fiable entre l’inspecteur et les données de l’article.
