ModelAdmin List Filters

    To activate per-field filtering, set ModelAdmin.list_filter to a list or tuple of elements, where each element is one of the following types:

    • A field name.
    • A subclass of django.contrib.admin.SimpleListFilter.
    • A 2-tuple containing a field name and a subclass of django.contrib.admin.FieldListFilter.

    See the examples below for discussion of each of these options for defining list_filter.

    The simplest option is to specify the required field names from your model.

    Each specified field should be either a BooleanField, CharField, DateField, DateTimeField, IntegerField, ForeignKey or ManyToManyField, for example:

    list_filter 中的字段名也可以使用 __ 查找来跨越关系，例如：

    1. class PersonAdmin(admin.UserAdmin):
    2.     list_filter = ('company__name',)
    1. from datetime import date
    3. from django.contrib import admin
    4. from django.utils.translation import gettext_lazy as _
    6. class DecadeBornListFilter(admin.SimpleListFilter):
    7.     # Human-readable title which will be displayed in the
    8.     # right admin sidebar just above the filter options.
    9.     title = _('decade born')
    11.     # Parameter for the filter that will be used in the URL query.
    12.     parameter_name = 'decade'
    14.     def lookups(self, request, model_admin):
    15.         """
    16.         Returns a list of tuples. The first element in each
    17.         tuple is the coded value for the option that will
    18.         appear in the URL query. The second element is the
    20.         in the right sidebar.
    21.         """
    22.             ('80s', _('in the eighties')),
    23.             ('90s', _('in the nineties')),
    24.         )
    26.     def queryset(self, request, queryset):
    27.         """
    28.         Returns the filtered queryset based on the value
    29.         provided in the query string and retrievable via
    30.         `self.value()`.
    31.         """
    32.         # Compare the requested value (either '80s' or '90s')
    33.         # to decide how to filter the queryset.
    34.         if self.value() == '80s':
    35.             return queryset.filter(
    36.                 birthday__gte=date(1980, 1, 1),
    37.                 birthday__lte=date(1989, 12, 31),
    38.             )
    39.         if self.value() == '90s':
    40.             return queryset.filter(
    41.                 birthday__gte=date(1990, 1, 1),
    42.                 birthday__lte=date(1999, 12, 31),
    43.             )
    45. class PersonAdmin(admin.ModelAdmin):
    46.     list_filter = (DecadeBornListFilter,)

    备注

    为方便起见，HttpRequest 对象被传递给 lookups 和 queryset 方法，例如：

    另外，为了方便起见，ModelAdmin 对象被传递给 lookups 方法，例如，如果你想根据现有数据进行查找：

    1. class AdvancedDecadeBornListFilter(DecadeBornListFilter):
    3.     def lookups(self, request, model_admin):
    4.         """
    5.         anyone born in the corresponding decades.
    6.         """
    7.         qs = model_admin.get_queryset(request)
    8.         if qs.filter(
    10.             birthday__lte=date(1989, 12, 31),
    11.         ).exists():
    12.             yield ('80s', _('in the eighties'))
    13.         if qs.filter(
    14.             birthday__gte=date(1990, 1, 1),
    15.             birthday__lte=date(1999, 12, 31),
    16.         ).exists():
    17.             yield ('90s', _('in the nineties'))

    Finally, if you wish to specify an explicit filter type to use with a field you may provide a list_filter item as a 2-tuple, where the first element is a field name and the second element is a class inheriting from django.contrib.admin.FieldListFilter, for example:

    1. class PersonAdmin(admin.ModelAdmin):
    2.     list_filter = (
    3.         ('is_staff', admin.BooleanFieldListFilter),
    4.     )

    Here the is_staff field will use the BooleanFieldListFilter. Specifying only the field name, fields will automatically use the appropriate filter for most cases, but this format allows you to control the filter used.

    The following examples show available filter classes that you need to opt-in to use.

    Assuming author is a ForeignKey to a User model, this will limit the list_filter choices to the users who have written a book, instead of listing all users.

    你可以使用 EmptyFieldListFilter 来过滤空值，它既可以过滤空字符串也可以过滤空值，这取决于字段允许存储的内容：

    1. class BookAdmin(admin.ModelAdmin):
    2.     list_filter = (
    3.         ('title', admin.EmptyFieldListFilter),
    4.     )

    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 the 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:

    1. class FilterWithCustomSeparator(admin.FieldListFilter):
    2.     # custom list separator that should be used to separate values.
    3.     list_separator = '|'
    5.     def __init__(self, field, request, params, model, model_admin, field_path):
    6.         self.lookup_kwarg = '%s__in' % field_path
    7.         super().__init__(field, request, params, model, model_admin, field_path)
    9.         return [self.lookup_kwarg]

    备注

    不支持 GenericForeignKey 字段。

    List filters typically appear only if the filter has more than one choice. A filter’s method controls whether or not it appears.

    具体的例子请看 Django 提供的默认模板（admin/filter.html）。