Face contre face : useEntityProp et useEntityRecords portent des noms proches, vivent tous deux dans @wordpress/core-data, et pourtant répondent à deux problèmes distincts. Confondre les deux mène soit à un bloc qui recharge une collection entière pour lire une seule valeur, soit à un bricolage d’apiFetch manuel là où un hook existant suffirait.
Le cas d’usage qui tranche la question : un bloc doit afficher, dans l’éditeur, un aperçu de trois billets d’un blog partenaire liés à l’article en cours. Faut-il passer par un champ meta contenant les identifiants, ou interroger directement la collection des billets ? La réponse dépend de ce que le bloc manipule réellement : une valeur unique appartenant à une entité déjà chargée, ou un ensemble d’entités à récupérer séparément.
Ce que fait réellement chacun des deux hooks
useEntityProp( kind, name, prop, id ) lit et écrit une propriété précise d’une entité déjà identifiée (typiquement l’article en cours d’édition). Il ne déclenche pas de requête REST supplémentaire pour un article déjà chargé dans l’éditeur : la donnée provient de l’état déjà présent dans le store core. À l’inverse, useEntityRecords( kind, name, query ) va chercher une liste d’enregistrements correspondant à des critères (type de contenu, taxonomie, statut, nombre), avec sa propre gestion du chargement et de la mise en cache.
Comparatif direct
| Critère | useEntityProp | useEntityRecords |
|---|---|---|
| Ce qu’il retourne | Une valeur unique (et son setter) | Un tableau d’enregistrements |
| Déclenche une requête REST | Rarement, si l’entité est déjà chargée | Oui, à chaque changement de critère |
| Cas d’usage typique | Champ meta, titre, statut d’un article connu | Articles liés, taxonomie, recherche filtrée |
| Permet l’écriture | Oui, via le setter renvoyé | Non, lecture seule |
Gestion du chargement (hasResolved) | Peu utile, la donnée est quasi immédiate | Indispensable pour l’affichage d’un état d’attente |
Le cas des trois billets liés, en pratique
Pour afficher trois billets liés, la bonne combinaison consiste à stocker les identifiants choisis dans un attribut du bloc (ou un champ meta si la relation concerne l’article entier), puis à utiliser useEntityRecords pour récupérer les enregistrements correspondants :
import { useEntityRecords } from '@wordpress/core-data';
const { records, hasResolved } = useEntityRecords( 'postType', 'post', {
include: attributes.billetsLies,
per_page: 3,
} );
if ( ! hasResolved ) {
return <p>Chargement des billets liés…</p>;
}Tenter de faire la même chose avec useEntityProp obligerait à lire un champ meta contenant un tableau d’identifiants, puis à effectuer soi-même une requête apiFetch vers l’endpoint des articles pour résoudre chaque identifiant en titre et extrait affichables. Le code serait plus long, sans bénéficier de la mise en cache et de la gestion de chargement déjà intégrées à useEntityRecords.
Le contre-exemple : forcer useEntityRecords pour une seule valeur
À l’inverse, utiliser useEntityRecords pour récupérer un unique article déjà ouvert dans l’éditeur (pour lire son statut de publication, par exemple) revient à déclencher une requête REST superflue vers une collection, alors que cette information est déjà disponible via useEntityProp( 'postType', 'post', 'status' ) sans le moindre appel réseau. C’est un gaspillage discret mais réel, surtout si le bloc est présent en plusieurs exemplaires sur la même page.
- Une donnée déjà portée par l’article en cours d’édition :
useEntityProp. - Une donnée qui vit ailleurs et doit être recherchée séparément :
useEntityRecords. - Un besoin d’écriture direct sur l’entité en cours : seul
useEntityProple permet nativement.
Verdict
Le choix ne se fait pas au nom du hook mais à la nature de la donnée manipulée. Une valeur simple, rattachée à une entité déjà chargée dans l’éditeur, relève de useEntityProp. Une collection d’entités à interroger séparément, avec ses propres critères de filtre, relève de useEntityRecords. Utiliser le second pour économiser l’écriture d’un apiFetch quand une simple lecture locale suffirait revient à payer en requêtes réseau ce qu’on gagne en confort de code, ce qui n’est jamais un bon calcul sur une page contenant plusieurs blocs similaires.
Pour aller plus loin
Les deux hooks partagent le même store sous-jacent (core) et peuvent parfaitement cohabiter dans le même composant : lire une propriété de l’article en cours avec useEntityProp pour construire les critères, puis interroger une collection avec useEntityRecords à partir de ces critères. C’est d’ailleurs le schéma le plus courant dès qu’un bloc doit croiser une donnée locale avec un contenu lié.
