# Rechercher et trier la médiathèque par métadonnées personnalisées

> Étendez la requête AJAX de la médiathèque pour filtrer les médias par un champ personnalisé, comme un numéro de référence ou un crédit photo.

- Auteur : Clément Hadrot
- Publié le : 2026-08-27
- Mis à jour le : 2026-08-27
- Catégorie : Tips
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tips/rechercher-trier-mediatheque-metadonnees-personnalisees/

## L’essentiel

- Un filtre AJAX pour étendre la recherche native
- Fonctionne dans le sélecteur de média comme dans la grille classique
- Compatible avec des metas ajoutées par une extension maison

Un studio de photographie qui alimentait sa médiathèque WordPress avec plusieurs centaines de visuels par mois avait besoin de retrouver rapidement une image à partir de son numéro de référence interne, enregistré en meta lors de l'import. La recherche native de la médiathèque, elle, ne porte que sur le titre, la légende et le texte alternatif : un numéro de référence stocké en champ personnalisé restait invisible pour cette recherche, quel que soit le nombre de caractères tapés dans le champ.

La médiathèque, qu'elle soit affichée en grille dans l'écran dédié ou dans le sélecteur de média ouvert depuis l'éditeur, repose sur une requête AJAX qu'il est possible d'étendre pour inclure une recherche sur un champ personnalisé.

## Comprendre la requête concernée

La médiathèque en mode grille interroge le point d'entrée AJAX `query-attachments`, dont les arguments transitent par le filtre `ajax_query_attachments_args` avant l'exécution de la requête `WP_Query` sous-jacente :

```
add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( ! empty( $_REQUEST['query']['s'] ) ) {
        $recherche = sanitize_text_field( $_REQUEST['query']['s'] );

        // Recherche à la fois dans les champs natifs et dans la meta référence
        $args['meta_query'] = [
            'relation' => 'OR',
            [
                'key'     => 'reference_studio',
                'value'   => $recherche,
                'compare' => 'LIKE',
            ],
        ];
    }

    return $args;
} );
```

## Ne pas exclure la recherche native au passage

Le piège de cette approche : en ajoutant un `meta_query`, le mot-clé `s` reste actif dans `$args` et continue de filtrer sur le titre. Sur cette recherche combinée, WordPress applique une intersection (ET logique) entre la recherche texte native et le `meta_query` ajouté, ce qui exclut les résultats qui correspondent uniquement à la référence et pas au titre. La solution consiste à retirer le mot-clé natif et à reproduire sa logique dans le `meta_query` :

> L'essentiel à retenir : Un filtre AJAX pour étendre la recherche native ; Fonctionne dans le sélecteur de média comme dans la grille classique ; Compatible avec des metas ajoutées par une extension maison

```
add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( empty( $_REQUEST['query']['s'] ) ) {
        return $args;
    }

    $recherche = sanitize_text_field( $_REQUEST['query']['s'] );
    unset( $args['s'] ); // On retire la recherche native pour la reproduire nous-mêmes

    add_filter( 'posts_where', function ( $where ) use ( $recherche ) {
        global $wpdb;
        $where .= $wpdb->prepare(
            " OR ({$wpdb->posts}.post_title LIKE %s)",
            '%' . $wpdb->esc_like( $recherche ) . '%'
        );
        return $where;
    } );

    $args['meta_query'] = [
        [
            'key'     => 'reference_studio',
            'value'   => $recherche,
            'compare' => 'LIKE',
        ],
    ];

    return $args;
} );
```

## Trier par métadonnée plutôt que seulement filtrer

Au-delà de la recherche, un tri par référence peut aussi être utile, en s'appuyant sur `meta_key` et `orderby` dans les mêmes arguments, à condition que la médiathèque affiche une option de tri correspondante côté interface, ce qui demande un script supplémentaire pour ajouter cette option au menu déroulant de tri natif :

```
add_filter( 'ajax_query_attachments_args', function ( $args ) {
    if ( ! empty( $_REQUEST['query']['orderby'] ) && 'reference_studio' === $_REQUEST['query']['orderby'] ) {
        $args['meta_key'] = 'reference_studio';
        $args['orderby']  = 'meta_value';
        $args['order']    = 'ASC';
    }

    return $args;
} );
```

## Vérifier les deux points d'entrée de la médiathèque

- L'écran **Médiathèque** classique, accessible depuis le menu d'administration, utilise ce même filtre AJAX en mode grille.
- Le **sélecteur de média** ouvert depuis l'éditeur de blocs (bloc Image, Galerie) passe par le même point d'entrée, ce qui rend ce filtre utile aux deux endroits sans code supplémentaire.
- La médiathèque en mode liste, plus ancienne, repose sur une requête classique côté serveur et non sur cette requête AJAX : un filtre distinct sur `pre_get_posts` serait nécessaire pour ce mode d'affichage.

> Une médiathèque de plusieurs centaines de fichiers sans recherche par référence interne n'est plus une médiathèque, c'est une pile d'images qu'on retrouve à la mémoire ou pas du tout.

## En résumé

Le filtre `ajax_query_attachments_args` permet d'étendre la recherche native de la médiathèque à n'importe quel champ personnalisé, à condition de gérer soi-même la combinaison avec la recherche texte native pour ne pas exclure de résultats par inadvertance. Ce réglage, invisible pour l'utilisateur final, change concrètement la façon dont une équipe retrouve ses fichiers au quotidien.