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

ModelAdmin классы могут определять фильтры списка, которые появляются в правой боковой панели страницы списка изменений в админке, как показано на следующем снимке экрана:

../../../../_images/list_filter.png

Чтобы активировать фильтрацию по каждому полю, установите ModelAdmin.list_filter в список или кортеж элементов, где каждый элемент является одним из следующих типов:

  • Имя поля.
  • Подкласс django.contrib.admin.SimpleListFilter.
  • Кортеж, содержащий имя поля и подкласс django.contrib.admin.FieldListFilter.

Обсуждение каждого из этих вариантов определения list_filter смотрите в примерах ниже.

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

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

Каждое указанное поле должно быть либо 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,)

Примечание

Для удобства объект HttpRequest передается методам lookups и queryset, например:

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)

Также в качестве удобства, объект ModelAdmin передается методу lookups, например, если вы хотите основывать поиск на доступных данных:

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 в виде кортежа, где первый элемент - имя поля, а второй - класс, наследуемый от 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, который может фильтровать как пустые строки, так и нули, в зависимости от того, что поле позволяет хранить:

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]

Примечание

Поле GenericForeignKey не поддерживается.

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

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

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

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

Действия администратора
Генератор документации для администраторов Django
Вернуться на верх