# Afficher trois billets liés plutôt qu’un champ : quand préférer useEntityRecords

> Un champ meta et une collection d'articles liés ne se lisent pas avec le même hook. Comparatif entre useEntityProp et useEntityRecords pour éviter le mauvais choix dans l'éditeur.

- Auteur : WordPress Développement
- Publié le : 2023-03-23
- Mis à jour le : 2026-09-30
- Catégorie : Blocs Gutenberg
- URL : https://www.wpmoderne.fr/blocs/quand-preferer-useentityrecords-useentityprop/

## L’essentiel

- useEntityProp lit une seule valeur d'une entité déjà connue
- useEntityRecords interroge une collection d'entités
- Le mauvais choix produit des requêtes en trop ou du code fragile

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 |

> L'essentiel à retenir : useEntityProp lit une seule valeur d'une entité déjà connue ; useEntityRecords interroge une collection d'entités ; Le mauvais choix produit des requêtes en trop ou du code fragile

## 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 `useEntityProp` le 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é.