---
title: "Filtres de listes ModelAdmin"
version: 6.0
locale: fr
source: https://docs.djangoproject.com/fr/6.0/ref/contrib/admin/filters/
canonical: https://djangodocs.dev/fr/6.0/ref/contrib/admin/filters/
---
# Filtres de listes `ModelAdmin`

Les classes `ModelAdmin` peuvent définir des filtres de listes apparaissant dans la barre de droite de la page de liste pour modification de l’administration, comme illustré dans la capture d’écran suivante :

![](ref/contrib/admin/_images/list_filter.png)

Pour activer le filtrage par champ, définissez [`ModelAdmin.list_filter`](/fr/6.0/ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_filter) à une liste ou un tuple d’éléments, où le type de chaque élément est l’un des suivants :

- Un nom de champ.
- Une sous-classe de `django.contrib.admin.SimpleListFilter`.
- Un tuple binaire contenant un nom de champ et une sous-classe de `django.contrib.admin.FieldListFilter`.

Consultez les exemples ci-dessous pour une discussion de chacune de ces options pour définir `list_filter`.

## Utilisation d’un nom de champ

L’option la plus simple est de définir les noms de champ requis d’après votre modèle.

Chaque champ indiqué doit être soit un `BooleanField`, `CharField`, `DateField`, `DateTimeField`, `IntegerField`, `ForeignKey` ou un `ManyToManyField`; par exemple :

```
class PersonAdmin(admin.ModelAdmin):
    list_filter = ["is_staff", "company"]
```

Les noms de champ dans `list_filter` peuvent également s’étendre aux relations à l’aide de la syntaxe de recherche `__`, par exemple :

```
class PersonAdmin(admin.UserAdmin):
    list_filter = ["company__name"]
```

## Utilisation de `SimpleListFilter`

Pour un filtrage personnalisé, vous pouvez définir votre propre filtre de liste en créant une sous-classe de `django.contrib.admin.SimpleListFilter`. Celle-ci devra contenir les attributs `title` et `parameter_name` ainsi que surcharger les méthodes `lookups` et `queryset`, par ex. :

```
from datetime import date

from django.contrib import admin
from django.utils.translation import gettext_lazy as _

class DecadeBornListFilter(admin.SimpleListFilter):
    # Human-readable title which will be displayed in the
    # right admin sidebar just above the filter options.
    title = _("decade born")

    # Parameter for the filter that will be used in the URL query.
    parameter_name = "decade"

    def lookups(self, request, model_admin):
        """
        Returns a list of tuples. The first element in each
        tuple is the coded value for the option that will
        appear in the URL query. The second element is the
        human-readable name for the option that will appear
        in the right sidebar.
        """
        return [
            ("80s", _("in the eighties")),
            ("90s", _("in the nineties")),
        ]

    def queryset(self, request, queryset):
        """
        Returns the filtered queryset based on the value
        provided in the query string and retrievable via
        `self.value()`.
        """
        # Compare the requested value (either '80s' or '90s')
        # to decide how to filter the queryset.
        if self.value() == "80s":
            return queryset.filter(
                birthday__gte=date(1980, 1, 1),
                birthday__lte=date(1989, 12, 31),
            )
        if self.value() == "90s":
            return queryset.filter(
                birthday__gte=date(1990, 1, 1),
                birthday__lte=date(1999, 12, 31),
            )

class PersonAdmin(admin.ModelAdmin):
    list_filter = [DecadeBornListFilter]
```

> **Note**
>
> Par commodité, l’objet `HttpRequest` est transmis aux méthodes `lookups` et `queryset`, par exemple :
>
> ```
> class AuthDecadeBornListFilter(DecadeBornListFilter):
>     def lookups(self, request, model_admin):
>         if request.user.is_superuser:
>             return super().lookups(request, model_admin)
>
>     def queryset(self, request, queryset):
>         if request.user.is_superuser:
>             return super().queryset(request, queryset)
> ```
>
> Aussi par commodité, l’objet `ModelAdmin` est transmis à la méthode `lookups`, par exemple si vous souhaitez établir les filtres à partir des données disponibles :
>
> ```
> class AdvancedDecadeBornListFilter(DecadeBornListFilter):
>     def lookups(self, request, model_admin):
>         """
>         Only show the lookups if there actually is
>         anyone born in the corresponding decades.
>         """
>         qs = model_admin.get_queryset(request)
>         if qs.filter(
>             birthday__gte=date(1980, 1, 1),
>             birthday__lte=date(1989, 12, 31),
>         ).exists():
>             yield ("80s", _("in the eighties"))
>         if qs.filter(
>             birthday__gte=date(1990, 1, 1),
>             birthday__lte=date(1999, 12, 31),
>         ).exists():
>             yield ("90s", _("in the nineties"))
> ```

## Utilisation d’un nom de champ et d’un `FieldListFilter` explicite

Pour terminer, si vous souhaitez indiquer explicitement un type de filtre à utiliser pour un champ, vous pouvez indiquer un élément `list_filter` sous forme de tuple binaire, où le première élément est un nom de champ et le second une classe héritant de `django.contrib.admin.FieldListFilter`, par exemple

```
class PersonAdmin(admin.ModelAdmin):
    list_filter = [
        ("is_staff", admin.BooleanFieldListFilter),
    ]
```

Ici, le champ `is_staff` utilisera le filtre `BooleanFieldListFilter`. En indiquant uniquement le nom du champ, le filtre approprié sera sélectionné dans la plupart des cas, mais ce format vous permet de contrôler le filtre qui sera choisi.

Les exemples suivants montrent les classes de filtre disponibles qu’il faut indiquer explicitement si on veut les utiliser.

Vous pouvez limiter les choix d’un modèle lié aux objets concernés par la relation en utilisant `RelatedOnlyFieldListFilter`:

```
class BookAdmin(admin.ModelAdmin):
    list_filter = [
        ("author", admin.RelatedOnlyFieldListFilter),
    ]
```

En supposant que `author` est une clé `ForeignKey` vers un modèle `User`, cela va limiter les choix de `list_filter` aux utilisateurs qui ont écrit un livre, au lieu d’énumérer tous les utilisateurs.

Vous pouvez filtrer les valeurs vides avec `EmptyFieldListFilter`, qui est capable de filtrer à la fois les chaînes vides et les valeurs nulles, en fonction de ce que le champ permet de stocker

```
class BookAdmin(admin.ModelAdmin):
    list_filter = [
        ("title", admin.EmptyFieldListFilter),
    ]
```

By defining a filter using the `__in` lookup, it is possible to filter for
any of a group of values. You need to override the `expected_parameters`
method, and then specify the `lookup_kwargs` attribute with the appropriate
field name. By default, multiple values in the query string will be separated
with commas, but this can be customized via the `list_separator` attribute.
The following example shows such a filter using the vertical-pipe character as
the separator:

```
class FilterWithCustomSeparator(admin.FieldListFilter):
    # custom list separator that should be used to separate values.
    list_separator = "|"

    def __init__(self, field, request, params, model, model_admin, field_path):
        self.lookup_kwarg = "%s__in" % field_path
        super().__init__(field, request, params, model, model_admin, field_path)

    def expected_parameters(self):
        return [self.lookup_kwarg]
```

> **Note**
>
> Le champ [`GenericForeignKey`](/fr/6.0/ref/contrib/contenttypes/#django.contrib.contenttypes.fields.GenericForeignKey) n’est pas pris en charge.

Les filtres de listes n’apparaissent que lorsque le filtre présente plus d’un choix. La méthode `has_output()` du filtre vérifie cette condition.

Il est possible de spécifier un gabarit personnalisé pour le rendu d’un filtre de liste :

```
class FilterWithCustomTemplate(admin.SimpleListFilter):
    template = "custom_template.html"
```

Voir le gabarit par défaut fourni par Django (`admin/filter.html`) pour un exemple concret.

## Facettes

Par défaut, le nombre total pour chaque filtre, appelé facette, peut être affiché ou masqué par l’interface du site d’administration. Ces nombres se mettent à jour en fonction du filtres actuellement appliqué. Voir [`ModelAdmin.show_facets`](/fr/6.0/ref/contrib/admin/#django.contrib.admin.ModelAdmin.show_facets) pour plus de détails.