Bloc Boucle de requête WordPress : listes d'articles sur mesure

Le bloc Boucle de requête (Query Loop) affiche une liste d’articles n’importe où dans un thème de blocs WordPress, ailleurs que sur la page principale du blogue. Voici comment les créateurs de sites et les auteurs de thèmes le configurent pour qu’il montre les bons articles. Les cas typiques sont une page Nouvelles qui affiche une seule catégorie, les trois derniers articles sur la page d’accueil, ou une grille d’études de cas. Un thème de blocs n’a pas de gabarit PHP où écrire une boucle WP_Query à la main. Vous construisez donc la liste avec des blocs dans l’Éditeur de site (Apparence > Éditeur, l’écran où les thèmes de blocs modifient leurs modèles). Un seul réglage décide si elle fonctionne : le type de requête. Choisissez Valeur par défaut (Default) dans les modèles d’archives et de recherche pour que la liste suive l’URL, et Personnalisé (Custom) partout ailleurs pour que le bloc applique ses propres filtres.

Ce que vous allez accomplir

Construire une page Nouvelles qui liste les articles d’une catégorie, six par page, du plus récent au plus ancien.
Présenter chaque article avec une image, un titre cliquable et une date, dans une grille de trois colonnes.
Ajouter une pagination qui fonctionne et un message pour une catégorie vide.
Savoir quand choisir le type de requête Valeur par défaut et quand choisir Personnalisé.
Prouver, numéro d’article à l’appui, que la page affiche exactement les articles attendus.

Prérequis

WordPress 6.5 ou plus récent avec un thème de blocs actif, comme Twenty Twenty-Four ou Twenty Twenty-Five. Les libellés de l’Éditeur de site cités ici sont ceux de WordPress 6.7 et des versions suivantes, 7.x comprises, en français du Canada. En français de France, quelques-uns diffèrent : Par défaut au lieu de Valeur par défaut, et Personnalisée au lieu de Personnalisé.
Un compte avec le rôle Administrateur, ou un autre rôle autorisé à modifier les pages et les modèles.
Une catégorie qui contient déjà quelques articles publiés. Les exemples utilisent une catégorie dont le slug est news.
WP-CLI sur le serveur pour les vérifications, et curl sur n’importe quel poste.

WordPress 6.5 et 6.6 présentent le type de requête sous forme d’interrupteur nommé Hériter de la requête du modèle (Inherit query from template). Activé, il correspond à Valeur par défaut ; désactivé, à Personnalisé. Le reste de l’article fonctionne de la même façon.

Comment ça fonctionne

Le bloc Boucle de requête est un conteneur qui joue trois rôles. Il garde les réglages de la requête : type de publication, filtres, ordre et nombre d’éléments par page. À l’intérieur, le bloc Modèle de publication (Post Template) est une mise en page que WordPress répète une fois pour chaque article trouvé. Les blocs que vous y placez, comme Titre de la publication ou Date de la publication, lisent leur contenu dans l’article en cours de répétition. À côté se trouvent deux blocs optionnels. Pagination mène aux pages de résultats suivantes, et Aucun résultat (No Results) ne s’affiche que si la requête ne trouve rien.

Le type de requête décide d’où vient la liste d’articles. Valeur par défaut réutilise la requête principale, celle que WordPress a déjà exécutée pour répondre à l’URL. Sur /category/news/page/2/, cela donne la deuxième page des articles Nouvelles, sans aucun réglage dans le bloc. Personnalisé ignore l’URL et applique les filtres définis dans le bloc. Sa pagination utilise son propre paramètre d’URL, query-4-page, où 4 est l’attribut queryId du bloc ; il change d’un bloc à l’autre.

Cette division explique les deux bogues les plus fréquents. Une requête de type Personnalisé placée dans le modèle des archives de catégorie affiche les mêmes articles pour toutes les catégories. Une requête de type Valeur par défaut placée sur une page ordinaire n’affiche que cette page, car la page est le seul résultat de la requête principale.

Étapes

Créez la page qui recevra la liste. Dans le tableau de bord, allez dans Pages > Ajouter une page et nommez-la « Nouvelles ». Vous construisez la liste dans le contenu de la page, elle ne s’applique donc qu’à cette page. Pour l’afficher sur toutes les pages d’un même type, par exemple le modèle de la page d’accueil, ouvrez plutôt Apparence > Éditeur > Modèles et modifiez ce modèle.
Trouvez l’identifiant de la catégorie. Il vous servira à la validation et il apparaît dans le balisage du bloc. Sur le serveur, depuis le répertoire de WordPress :
```
wp term get category news --by=slug --fields=term_id,name,count
```
Exemple de sortie :
```
+---------+-------+
| Field   | Value |
+---------+-------+
| term_id | 7     |
| name    | News  |
| count   | 14    |
+---------+-------+
```
Si WP-CLI répond Error: Term doesn't exist., le slug est différent. Lancez wp term list category --fields=term_id,slug,name pour le trouver.
Insérez un bloc Boucle de requête. Dans l’éditeur de la page, ajoutez un bloc Boucle de requête. Son espace réservé propose Choisir (Choose), qui ouvre des compositions toutes faites, et Partir de zéro (Start blank). Choisissez Partir de zéro, puis Titre et date (Title & Date). Vous avez maintenant un Modèle de publication contenant deux blocs, répétés pour les derniers articles.
Passez le type de requête à Personnalisé. Sélectionnez le bloc Boucle de requête lui-même, pas un bloc à l’intérieur. Le bouton Vue en liste de la barre d’outils du haut aide à choisir le bon niveau. Dans la barre latérale des réglages, réglez Type de requête (Query type) sur Personnalisé (Custom). Sur une page, c’est le seul réglage qui donne une vraie liste : faites-le en premier.
Réglez les filtres et l’ordre. Toujours dans les réglages de la Boucle de requête, indiquez :
- Type de publication : Articles.
- Ordonner par (Order by) : Des plus récents aux plus anciens.
- Éléments par page : 6.
- Filtres : ajoutez Taxonomies, tapez « News » dans le champ Catégories et choisissez-la.
Laissez Décalage (Offset) à 0 et Nombre max. de pages à afficher (Max pages to show) à 0, ce qui veut dire sans limite. L’aperçu de l’éditeur se met à jour à chaque changement. S’il montre des articles d’autres catégories, le filtre n’a pas été enregistré ; choisissez de nouveau la catégorie dans la liste de suggestions au lieu de taper son nom au complet.
Concevez la mise en page répétée. Sélectionnez le bloc Modèle de publication. Dans sa barre d’outils, choisissez Vue en grille (Grid view) et réglez le nombre de colonnes à 3 dans la barre latérale. Ajoutez ensuite un bloc Image mise en avant au-dessus du titre et, sur le bloc Titre de la publication, activez Créer un lien sur le titre (Make title a link). Tout ce que vous ajoutez ici se répète pour chaque article, alors n’ajoutez que ce dont chaque carte a besoin.
Ajoutez la pagination et un message pour la liste vide. Sélectionnez le bloc Boucle de requête. Avec l’outil d’insertion à l’intérieur du bloc, ajoutez un bloc Pagination sous le Modèle de publication. Il contient par défaut Précédent, les numéros de page et Suivant. Ajoutez ensuite un bloc Aucun résultat et placez-y un paragraphe, par exemple « Aucune nouvelle pour l’instant. Revenez bientôt. » Les visiteurs ne voient ce paragraphe que si la catégorie est vide.
Vérifiez le balisage du bloc. Ouvrez le menu Options (trois points, en haut à droite) et choisissez Éditeur de code. La partie Boucle de requête devrait ressembler à ceci, avec vos propres identifiants et le texte de votre paragraphe :

Exemple de sortie :
```

<div class="wp-block-query">













<p>No news yet. Check back soon.</p>

</div>

```
Trois valeurs portent tout le montage : "inherit":false correspond au type Personnalisé, "perPage":6 à la taille de page et "category":[7] à l’identifiant trouvé à l’étape 2. Votre copie peut contenir d’autres attributs, ou les placer dans un autre ordre. WordPress 6.x enregistre le filtre sans le niveau include, sous la forme "taxQuery":{"category":[7]} ; la clé include est arrivée avec la version 7.0, en même temps que l’exclusion de termes. Si vous voyez "inherit":true, retournez à l’étape 4. Sortez avec Sortir de l’éditeur de code et publiez la page.
Livrez-la dans le thème, si vous en êtes l’auteur. Pour réutiliser la liste d’un site à l’autre, collez le même balisage dans un fichier du thème. Ce peut être templates/home.html ou une composition du dossier patterns/. Remplacez l’identifiant de catégorie sur chaque site, car les identifiants de termes changent d’une installation à l’autre. Notre guide sur la structure de fichiers d’un thème de blocs montre où vont ces fichiers.

Valider que ça fonctionne

Demandez à WordPress les six articles que le bloc devrait afficher. category__in reproduit le comportement du bloc, qui n’inclut pas les sous-catégories :

wp post list --post_type=post --post_status=publish --category__in=7 --posts_per_page=6 --orderby=date --order=DESC --fields=ID,post_title,post_date

Exemple de sortie :

+-----+--------------------------------+---------------------+
| ID  | post_title                     | post_date           |
+-----+--------------------------------+---------------------+
| 418 | Fall maintenance window        | 2026-10-21 09:40:12 |
| 405 | New support hours              | 2026-10-08 15:03:55 |
| 397 | Office closed for Thanksgiving | 2026-10-02 11:27:40 |
| 371 | Backup policy update           | 2026-09-17 08:58:06 |
| 366 | Team changes                   | 2026-09-09 16:12:31 |
| 352 | Quarterly review               | 2026-08-28 10:45:19 |
+-----+--------------------------------+---------------------+

Lisez maintenant les identifiants d’articles sur la page en ligne. Chaque carte est un élément li dont la classe contient post-<ID> :

curl -s https://www.example.com/news/ | grep -oE 'wp-block-post post-[0-9]+'

Exemple de sortie :

wp-block-post post-418
wp-block-post post-405
wp-block-post post-397
wp-block-post post-371
wp-block-post post-366
wp-block-post post-352

Les identifiants et leur ordre doivent correspondre au tableau de WP-CLI. Vérifiez ensuite la page 2 avec le paramètre propre au bloc, en reprenant le queryId de l’étape 8 :

curl -s 'https://www.example.com/news/?query-4-page=2' | grep -oE 'wp-block-post post-[0-9]+'

Vous devriez obtenir les six identifiants suivants, ceux que donne la commande WP-CLI quand vous y ajoutez --paged=2. C’est terminé quand les deux pages correspondent, que les liens de pagination pointent vers ?query-4-page=2 et que le texte d’Aucun résultat est absent tant que la catégorie contient des articles.

Dépannage

La page n’affiche qu’elle-même, ou rien du tout. Le type de requête est resté à Valeur par défaut, et le bloc a donc repris la requête principale de la page. Les versions récentes peuvent aussi afficher sous le réglage un avertissement indiquant que le bloc ne peut pas hériter ici de la requête du modèle. Sélectionnez la Boucle de requête et réglez Type de requête sur Personnalisé, ou cherchez "inherit":true dans l’éditeur de code.
Toutes les archives de catégorie affichent les mêmes articles. C’est le problème inverse : un modèle d’archive contient une requête de type Personnalisé. Ouvrez Apparence > Éditeur > Modèles, modifiez le modèle des catégories et réglez la Boucle de requête sur Valeur par défaut. Les modèles d’archives, de recherche et d’accueil du blogue devraient presque toujours utiliser Valeur par défaut.
La page 2 affiche les mêmes articles que la page 1. Un cache de pages qui ignore les paramètres d’URL sert la page 1 pour ?query-4-page=2. Ouvrez la page 2 dans un fureteur où vous êtes connecté, car la plupart des caches de pages ignorent les utilisateurs connectés. Si elle s’affiche correctement, ajoutez les paramètres query-*-page à la clé de cache de votre couche de mise en cache. Un décalage (Offset) différent de 0 déplace aussi chaque page : vérifiez-le.
Il manque les articles d’une sous-catégorie. Le filtre de catégorie du bloc n’inclut pas les catégories enfants. Ajoutez chaque sous-catégorie au filtre Catégories, ou déplacez ces articles dans la catégorie parente.
Les changements au fichier du thème n’ont aucun effet. Quelqu’un a enregistré ce modèle dans l’Éditeur de site. WordPress sert maintenant la copie en base de données au lieu du fichier. wp post list --post_type=wp_template --fields=ID,post_name,post_modified affiche les copies enregistrées. Notre article sur les conflits de parties de modèle explique comment les comparer et les réinitialiser.

Quand cette approche ne convient pas

Si vous voulez le blogue complet, toutes catégories confondues, ne le reconstruisez pas sur une page. Définissez une page des articles dans Réglages > Lecture et laissez la requête de type Valeur par défaut du modèle Index ou Accueil du thème s’en charger, pagination comprise.

Les réglages de la Boucle de requête couvrent le type de publication, la taxonomie, l’auteur, le mot-clé, l’ordre, le décalage et les articles épinglés. Ils ne peuvent pas filtrer ni trier selon un champ personnalisé, combiner plusieurs types de publication, ni trier selon un champ ajouté par une extension. Pour cela, enregistrez une variation de bloc de la Boucle de requête et ajustez ses variables de requête en PHP avec le filtre query_loop_block_query_vars. Le manuel WordPress montre la méthode dans Extending the Query Loop block. Pour les réglages côté éditeur, consultez la documentation du bloc Query Loop.

Avec un thème classique, la Boucle de requête ne fonctionne que dans le contenu des publications, et une boucle WP_Query dans un gabarit PHP reste l’outil le plus simple. Notre comparaison des thèmes de blocs et des thèmes classiques peut vous aider à décider si le passage en vaut la peine.

Un WordPress qui rapporte vraiment mérite un opérateur — Stack Harbor opère cette pile sous WordPress Entreprise ; réservez une consultation d’infrastructure.