# ACF et query_loop_block_query_vars : afficher un champ personnalisé

> Le bloc Query Loop natif ignore les champs ACF par défaut. Le filtre query_loop_block_query_vars permet d'injecter un champ personnalisé dans les arguments de la requête, sans bloc dynamique supplémentaire.

- Auteur : WordPress Développement
- Publié le : 2022-11-02
- Mis à jour le : 2026-09-30
- Catégorie : Éditeur de site (FSE)
- URL : https://www.wpmoderne.fr/fse/acf-query-loop-block-query-vars-champ-personnalise/

## L’essentiel

- Comprendre les arguments par défaut du Query Loop
- Injecter un meta_query via le filtre dédié
- Rendre le tri filtrable depuis l'éditeur

Comment trier une liste d'articles par un champ ACF personnalisé, comme une date d'événement ou un niveau de priorité, directement dans le bloc Query Loop du Site Editor, sans coder un bloc dynamique complet ? La réponse tient dans un seul filtre, `query_loop_block_query_vars`, introduit récemment dans le cœur de WordPress pour permettre justement ce type d'ajustement, sans réécrire le rendu du bloc.

Sur un projet où les articles d'un site immobilier devaient être triés par un champ ACF `prix_bien`, plutôt que par la date de publication par défaut, ce filtre a évité la création d'un bloc dynamique dédié, solution plus lourde à maintenir pour un besoin relativement simple de tri et de filtrage.

## Comprendre ce que génère le Query Loop par défaut

Le bloc Query Loop, configuré depuis l'éditeur, génère en arrière-plan un objet `WP_Query` classique, dont les arguments sont dérivés des réglages visibles dans le panneau latéral : type de contenu, nombre d'articles, ordre de tri, taxonomie de filtrage. Ces arguments ne couvrent, par défaut, aucun champ personnalisé ACF, puisque WordPress lui-même ignore tout des métadonnées ajoutées par cette extension tierce.

Le filtre `query_loop_block_query_vars` s'exécute juste avant la construction de la requête, et reçoit en paramètre le tableau d'arguments déjà préparé par le bloc, ainsi que l'instance du bloc lui-même, ce qui permet de conditionner l'ajout d'un critère à un contexte précis.

## Injecter un meta_query pour trier par un champ ACF

Le filtre permet d'ajouter, ou de modifier, n'importe quel argument de `WP_Query`, y compris `meta_key`, `orderby` et `meta_query`, exactement comme dans une requête personnalisée classique.

> L'essentiel à retenir : Comprendre les arguments par défaut du Query Loop ; Injecter un meta_query via le filtre dédié ; Rendre le tri filtrable depuis l'éditeur

```
add_filter( 'query_loop_block_query_vars', function ( $query_args, $block ) {
    if ( 'bien-immobilier' !== ( $query_args['post_type'] ?? '' ) ) {
        return $query_args;
    }

    $query_args['meta_key'] = 'prix_bien';
    $query_args['orderby']  = 'meta_value_num';
    $query_args['order']    = 'ASC';

    return $query_args;
}, 10, 2 );
```

La vérification du type de contenu, en tout début de fonction, est essentielle : sans elle, ce tri s'appliquerait à tous les blocs Query Loop du site, y compris ceux qui affichent des articles classiques, sans champ `prix_bien` associé, ce qui produirait un tri incohérent ou une requête silencieusement vide.

## Filtrer par une valeur, pas seulement trier

Le même filtre permet également d'ajouter une condition de filtrage, via une `meta_query` complète, pour n'afficher, par exemple, que les biens immobiliers dont le champ ACF `disponible` vaut vrai.

- Vérifier systématiquement le type de contenu avant d'appliquer un critère ACF.
- Utiliser `meta_value_num` plutôt que `meta_value` pour un tri numérique correct.
- Tester le rendu avec plusieurs valeurs de champ, y compris des champs vides, pour éviter les surprises de tri.

## Distinguer ce filtre de l'affichage de la valeur du champ

Ce filtre agit uniquement sur les arguments de la requête : il ne permet pas d'afficher directement la valeur du champ ACF dans le contenu de chaque carte du Query Loop. Pour cela, il faut encore, à cette date, recourir à un bloc ACF Blocks personnalisé ou à un shortcode inséré dans un bloc HTML : l'éditeur ne propose aucun mécanisme natif pour lier un attribut de bloc directement à un champ personnalisé.

> Ce filtre a un mérite trop souvent sous-estimé : il évite de sacrifier la simplicité du Query Loop natif pour un simple besoin de tri, sans obliger à recoder un bloc dynamique complet à partir de zéro.

## Rendre le tri configurable depuis l'éditeur

Pour éviter de coder en dur le nom du champ ACF dans le filtre PHP, une variante plus flexible consiste à lire un attribut personnalisé ajouté au bloc Query Loop via un filtre JavaScript sur ses `attributes`, puis à récupérer cette valeur côté PHP dans `$block->context`. Cette approche, plus avancée, demande une familiarité avec l'API de filtres côté client de Gutenberg, mais évite une modification du code à chaque nouveau besoin de tri.

## Ce que ce billet ne couvre pas

Les ACF Blocks et les shortcodes, deux approches distinctes pour afficher un champ personnalisé dans le rendu visuel d'un bloc, ne sont pas traités ici : ce billet se concentre uniquement sur l'ajustement de la requête sous-jacente au Query Loop, pas sur l'affichage de la donnée elle-même.

## En résumé

Le filtre `query_loop_block_query_vars` reste, pour un besoin de tri ou de filtrage par champ ACF, la solution la plus simple et la plus proche du fonctionnement natif du bloc Query Loop. Une vérification stricte du contexte (type de contenu, présence du champ) évite les effets de bord sur d'autres blocs Query Loop du même site.