--- title: "ModelAdmin リストフィルタ" version: 5.1 locale: ja source: https://docs.djangoproject.com/ja/5.1/ref/contrib/admin/filters/ canonical: https://djangodocs.dev/ja/5.1/ref/contrib/admin/filters/ --- # `ModelAdmin` リストフィルタ `ModelAdmin` クラスは、以下のスクリーンショットのように、admin アプリケーションの変更一覧ページの右サイドバーに表示されるリストフィルタを定義できます: ![](ref/contrib/admin/_images/list_filter.png) フィールドごとのフィルタリングを有効にするには、[`ModelAdmin.list_filter`](/ja/5.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.list_filter) を要素のリストまたはタプルに設定し、各要素が以下のいずれかのタイプでなければなりません: - フィールド名。 - `django.contrib.admin.SimpleListFilter` のサブクラス。 - フィールド名と `django.contrib.admin.FieldListFilter` のサブクラスを含む 2値タプル。 `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] ``` > **Note** > > 利便性のため、`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` を使用する 最後に、フィールドに使用する明示的なフィルタタイプを指定したい場合は、2値タプルとして `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` が `User` モデルの `ForeignKey` であるとすると、これは `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] ``` > **Note** > > [`GenericForeignKey`](/ja/5.1/ref/contrib/contenttypes/#django.contrib.contenttypes.fields.GenericForeignKey) フィールドはサポートされていません。 リストフィルタは通常、フィルタに複数の選択肢がある場合にのみ表示されます。フィルタの `has_output()` メソッドは、フィルタが表示されるかどうかを制御します。 リストフィルタのレンダリングにはカスタムテンプレートを指定できます: ``` class FilterWithCustomTemplate(admin.SimpleListFilter): template = "custom_template.html" ``` 具体的な例については、Django により提供されるデフォルトのテンプレート (`admin/filter.html`) を参照してください。 ## ファセット (Facet) > **New in Django 5.0** デフォルトでは、ファセット (facet) と呼ばれる各フィルタのカウントは、admin UIからトグルで表示できます。これらのカウントは現在適用されているフィルタに応じて更新されます。詳細は [`ModelAdmin.show_facets`](/ja/5.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.show_facets) を参照してください。