Фильтры списка ModelAdmin

Использование имени поля

Самый простой вариант — указать необходимые имена полей модели.

Каждое указанное поле должно быть полем BooleanField, CharField, DateField, DateTimeField, IntegerField, ForeignKey или ManyToManyField, например:

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

Имена полей в list_filter также могут охватывать связи с помощью поиска __, например:

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

Использование SimpleListFilter

Для пользовательской фильтрации можно определить собственный фильтр списка, создав подкласс django.contrib.admin.SimpleListFilter. Необходимо задать атрибуты title и parameter_name, а также переопределить методы lookups и queryset, например:

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]

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)

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"))

Использование имени поля и явного FieldListFilter

Наконец, если вы хотите указать явный тип фильтра для поля, можно передать элемент list_filter в виде 2-кортежа, где первый элемент — имя поля, а второй — класс, наследующий django.contrib.admin.FieldListFilter, например:

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

В этом случае для поля is_staff будет использоваться BooleanFieldListFilter. Если указать только имя поля, для большинства случаев автоматически будет выбран подходящий фильтр, но такой формат позволяет управлять используемым фильтром.

В следующих примерах показаны доступные классы фильтров, которые необходимо явно включить.

Ограничить варианты выбора связанной модели объектами, участвующими в этой связи, можно с помощью RelatedOnlyFieldListFilter:

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

Предполагая, что author — это ForeignKey модели User, этот код ограничит варианты выбора list_filter пользователями, написавшими книгу, вместо отображения всех пользователей.

Фильтровать пустые значения можно с помощью EmptyFieldListFilter. Этот фильтр может отбирать как пустые строки, так и значения null — в зависимости от того, какие значения допускает поле:

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

Определив фильтр с помощью поиска __in, можно отбирать любое значение из группы. Необходимо переопределить метод expected_parameters и задать атрибут lookup_kwargs, указав подходящее имя поля. По умолчанию несколько значений в строке запроса разделяются запятыми, но это можно изменить с помощью атрибута list_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]

Фильтры списка обычно отображаются, только если у фильтра есть несколько вариантов выбора. Метод has_output() определяет, будет ли отображаться фильтр.

Для отображения фильтра списка можно указать собственный шаблон:

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

Конкретный пример см. в шаблоне Django по умолчанию (admin/filter.html).

Фасеты

По умолчанию количество объектов для каждого фильтра, называемое фасетами, можно показывать, включив эту функцию в интерфейсе админки. Эти значения будут обновляться с учётом применённых фильтров. Подробнее см. в разделе ModelAdmin.show_facets.