其他主题¶

register 装饰器¶

register(*models, site=django.contrib.admin.sites.site)[source]¶

还有一个用于注册 ModelAdmin 类的装饰器

from django.contrib import admin
from .models import Author


@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    pass

它接收一个或多个要使用 ModelAdmin 注册的模型类。如果您使用自定义的 AdminSite，请使用 site 关键字参数传递它

from django.contrib import admin
from .models import Author, Editor, Reader
from myproject.admin_site import custom_admin_site


@admin.register(Author, Reader, Editor, site=custom_admin_site)
class PersonAdmin(admin.ModelAdmin):
    pass

如果您必须在模型管理员类的 __init__() 方法中引用它，则不能使用此装饰器，例如 super(PersonAdmin, self).__init__(*args, **kwargs)。您可以使用 super().__init__(*args, **kwargs)。

管理员文件的发现¶

当您将 'django.contrib.admin' 放入您的 INSTALLED_APPS 设置中时，Django 会自动在每个应用程序中查找 admin 模块并导入它。

class apps.AdminConfig¶

这是管理员的默认 AppConfig 类。它在 Django 启动时调用 autodiscover()。

class apps.SimpleAdminConfig¶

此类的工作方式类似于 AdminConfig，但它不会调用 autodiscover()。

default_site¶

指向默认管理站点类的点分隔导入路径，或指向返回站点实例的可调用对象。默认为 'django.contrib.admin.sites.AdminSite'。有关用法，请参阅 覆盖默认管理站点。

autodiscover()[source]¶

此函数尝试在每个已安装的应用中导入一个admin模块。这些模块预计会将模型注册到管理员中。

通常，您不需要直接调用此函数，因为AdminConfig在 Django 启动时会调用它。

如果您正在使用自定义的AdminSite，通常的做法是将所有ModelAdmin子类导入到您的代码中，并将它们注册到自定义的AdminSite。在这种情况下，为了禁用自动发现，您应该将'django.contrib.admin.apps.SimpleAdminConfig'而不是'django.contrib.admin'放在您的INSTALLED_APPS设置中。

ModelAdmin 选项¶

ModelAdmin非常灵活。它有几个选项用于自定义界面。所有选项都在ModelAdmin子类上定义

from django.contrib import admin


class AuthorAdmin(admin.ModelAdmin):
    date_hierarchy = "pub_date"

ModelAdmin.actions¶

要在更改列表页面上提供的操作列表。有关详细信息，请参见管理员操作。

ModelAdmin.actions_on_top¶

ModelAdmin.actions_on_bottom¶

控制操作栏在页面上的显示位置。默认情况下，管理员更改列表会在页面顶部显示操作（actions_on_top = True; actions_on_bottom = False）。

ModelAdmin.actions_selection_counter¶

控制是否在操作下拉菜单旁边显示选择计数器。默认情况下，管理员更改列表会显示它（actions_selection_counter = True）。

ModelAdmin.date_hierarchy¶

将date_hierarchy设置为模型中DateField或DateTimeField的名称，更改列表页面将包含基于该字段的日期细化导航。

示例

date_hierarchy = "pub_date"

您还可以使用__查找指定相关模型上的字段，例如

date_hierarchy = "author__pub_date"

它会根据可用数据智能地填充自身，例如，如果所有日期都在一个月内，它只会显示日级细化。

注意

date_hierarchy在内部使用QuerySet.datetimes()。启用时区支持时，请参阅其文档了解一些注意事项（USE_TZ = True）。

ModelAdmin.empty_value_display¶

此属性覆盖记录字段为空（None、空字符串等）时的默认显示值。默认值为-（破折号）。例如

from django.contrib import admin


class AuthorAdmin(admin.ModelAdmin):
    empty_value_display = "-empty-"

您还可以使用AdminSite.empty_value_display覆盖所有管理员页面的empty_value_display，或者像这样覆盖特定字段

from django.contrib import admin


class AuthorAdmin(admin.ModelAdmin):
    list_display = ["name", "title", "view_birth_date"]

    @admin.display(empty_value="???")
    def view_birth_date(self, obj):
        return obj.birth_date

ModelAdmin.exclude¶

如果给出，此属性应为要从表单中排除的字段名称列表。

例如，让我们考虑以下模型

from django.db import models


class Author(models.Model):
    name = models.CharField(max_length=100)
    title = models.CharField(max_length=3)
    birth_date = models.DateField(blank=True, null=True)

如果您想要一个仅包含name和title字段的Author模型表单，则可以像这样指定fields或exclude

from django.contrib import admin


class AuthorAdmin(admin.ModelAdmin):
    fields = ["name", "title"]


class AuthorAdmin(admin.ModelAdmin):
    exclude = ["birth_date"]

由于 Author 模型只有三个字段，name、title和birth_date，因此上述声明产生的表单将包含完全相同的字段。

ModelAdmin.fields¶

使用fields选项可以在“添加”和“更改”页面上的表单中进行简单的布局更改，例如仅显示可用字段的子集、修改其顺序或将它们分组到行中。例如，您可以为django.contrib.flatpages.models.FlatPage模型定义一个更简单的管理员表单版本，如下所示

class FlatPageAdmin(admin.ModelAdmin):
    fields = ["url", "title", "content"]

在上面的示例中，只有url、title和content字段将按顺序显示在表单中。fields可以包含在ModelAdmin.readonly_fields中定义的值，以只读方式显示。

对于更复杂的布局需求，请参见fieldsets选项。

fields选项接受与list_display相同类型的值，但它不接受可调用对象和相关字段的__查找。模型和模型管理员方法的名称仅在它们列在readonly_fields中时才会使用。

要在同一行上显示多个字段，请将这些字段包装在它们自己的元组中。在此示例中，url和title字段将显示在同一行上，而content字段将显示在其下方。

class FlatPageAdmin(admin.ModelAdmin):
    fields = [("url", "title"), "content"]

与ModelAdmin.fieldsets选项可能产生的混淆

此fields选项不应与fieldsets选项中包含的fields字典键混淆，如下一节所述。

如果fields和fieldsets选项都不存在，Django 将默认显示每个不是AutoField并且具有editable=True的字段，在一个字段集中，字段的顺序与模型中定义的字段顺序相同。

ModelAdmin.fieldsets¶

设置fieldsets以控制管理员“添加”和“更改”页面的布局。

fieldsets是一个 2 元组列表，其中每个 2 元组代表管理员表单页面上的一个<fieldset>。（<fieldset>是表单的“部分”。）

2 元组的格式为(name, field_options)，其中name是表示字段集标题的字符串，field_options是有关字段集的信息字典，包括要在其中显示的字段列表。

一个完整的示例，取自 django.contrib.flatpages.models.FlatPage 模型

from django.contrib import admin


class FlatPageAdmin(admin.ModelAdmin):
    fieldsets = [
        (
            None,
            {
                "fields": ["url", "title", "content", "sites"],
            },
        ),
        (
            "Advanced options",
            {
                "classes": ["collapse"],
                "fields": ["registration_required", "template_name"],
            },
        ),
    ]

这将生成一个看起来像这样的管理页面

如果既没有 fieldsets 也没有 fields 选项，Django 将默认显示每个不是 AutoField 且 editable=True 的字段，并将这些字段放在一个字段集中，字段顺序与模型中定义的字段顺序相同。

field_options 字典可以包含以下键

• fields

  要在该字段集中显示的字段名称列表或元组。此键是必需的。

  示例

  {
      "fields": ["first_name", "last_name", "address", "city", "state"],
  }
  

  与 fields 选项一样，要在同一行上显示多个字段，请将这些字段包装在它们自己的元组中。在此示例中，first_name 和 last_name 字段将显示在同一行上。

  {
      "fields": [("first_name", "last_name"), "address", "city", "state"],
  }
  

  fields 可以包含在 readonly_fields 中定义的值，以只读方式显示。

  如果将可调用对象的名称添加到 fields 中，则与 fields 选项相同：可调用对象必须列在 readonly_fields 中。

• classes

  包含要应用于字段集的额外 CSS 类的列表或元组。这可以包括项目中定义的任何自定义 CSS 类，以及 Django 提供的任何 CSS 类。在默认的管理站点 CSS 样式表中，定义了两个特别有用的类：collapse 和 wide。

  示例

  {
      "classes": ["wide", "collapse"],
  }
  

  具有 wide 样式的字段集将在管理界面中获得额外的水平空间。具有名称和 collapse 样式的字段集将最初处于折叠状态，使用可扩展的小部件和一个切换按钮来切换它们的可见性。

  Django 5.1 中的更改

  使用 collapse 类的 fieldsets 现在使用 <details> 和 <summary> 元素，前提是它们定义了 name。

• description

  一个可选的额外文本字符串，显示在每个字段集的顶部，位于字段集标题下方。

  请注意，此值在管理界面中显示时不会进行 HTML 转义。这允许您根据需要包含 HTML。或者，您可以使用纯文本和 django.utils.html.escape() 来转义任何 HTML 特殊字符。

TabularInline 对 fieldsets 的支持有限

在 TabularInline 中使用 fieldsets 功能有限。您可以通过在 field_options 字典中定义 fields 来指定将在 TabularInline 布局中显示的字段及其顺序。

所有其他功能都不受支持。这包括使用 name 为一组字段定义标题。

ModelAdmin.filter_horizontal¶

默认情况下，ManyToManyField 在管理站点中使用 <select multiple> 显示。但是，当选择许多项目时，多选框可能难以使用。将 ManyToManyField 添加到此列表将改为使用一个巧妙的、不显眼的 JavaScript“筛选器”界面，允许在选项中进行搜索。未选中的选项和已选中的选项并排显示在两个框中。请参阅 filter_vertical 以使用垂直界面。

ModelAdmin.filter_vertical¶

与 filter_horizontal 相同，但使用筛选器界面的垂直显示，未选中的选项框显示在已选中的选项框上方。

ModelAdmin.form¶

默认情况下，会为您的模型动态创建 ModelForm。它用于创建在添加/更改页面上显示的表单。您可以轻松地提供自己的 ModelForm 来覆盖添加/更改页面上的任何默认表单行为。或者，您可以自定义默认表单，而不是指定一个全新的表单，方法是使用 ModelAdmin.get_form() 方法。

有关示例，请参阅部分 向管理添加自定义验证。

省略 Meta.model 属性

如果在 ModelForm 上定义了 Meta.model 属性，则还必须定义 Meta.fields 属性（或 Meta.exclude 属性）。但是，由于管理具有自己的定义字段的方式，因此将忽略 Meta.fields 属性。

如果 ModelForm 仅用于管理，则最简单的解决方案是省略 Meta.model 属性，因为 ModelAdmin 将提供要使用的正确模型。或者，您可以在 Meta 类中设置 fields = [] 以满足对 ModelForm 的验证。

ModelAdmin.exclude 优先

如果您的 ModelForm 和 ModelAdmin 都定义了 exclude 选项，则 ModelAdmin 优先

from django import forms
from django.contrib import admin
from myapp.models import Person


class PersonForm(forms.ModelForm):
    class Meta:
        model = Person
        exclude = ["name"]


class PersonAdmin(admin.ModelAdmin):
    exclude = ["age"]
    form = PersonForm

在上面的示例中，“age”字段将被排除，但“name”字段将包含在生成的表单中。

ModelAdmin.formfield_overrides¶

这提供了一种快速简便的方法来覆盖一些 Field 选项以在管理中使用。formfield_overrides 是一个字典，它将字段类映射到要在构造时传递给字段的参数的字典。

由于这有点抽象，让我们来看一个具体的例子。formfield_overrides 最常见的用途是为特定类型的字段添加自定义小部件。因此，假设我们编写了一个 RichTextEditorWidget，我们希望将其用于大型文本字段而不是默认的 <textarea>。以下是如何做到这一点

from django.contrib import admin
from django.db import models

# Import our custom widget and our model from where they're defined
from myapp.models import MyModel
from myapp.widgets import RichTextEditorWidget


class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        models.TextField: {"widget": RichTextEditorWidget},
    }

请注意，字典中的键是实际的字段类，而不是字符串。该值是另一个字典；这些参数将传递给表单字段的 __init__() 方法。有关详细信息，请参阅 表单 API。

警告

如果要将自定义小部件与关系字段（即 ForeignKey 或 ManyToManyField）一起使用，请确保您没有将该字段的名称包含在 raw_id_fields、radio_fields 或 autocomplete_fields 中。

formfield_overrides 不会允许您更改已设置 raw_id_fields、radio_fields 或 autocomplete_fields 的关系字段上的小部件。这是因为 raw_id_fields、radio_fields 和 autocomplete_fields 本身暗示了自定义小部件。

ModelAdmin.inlines¶

请参阅下面的 InlineModelAdmin 对象以及 ModelAdmin.get_formsets_with_inlines()。

ModelAdmin.list_display¶

设置 list_display 来控制在管理员的更改列表页面上显示哪些字段。

示例

list_display = ["first_name", "last_name"]

如果不设置 list_display，管理员站点将显示一个单列，其中显示每个对象的 __str__() 表示形式。

可以在 list_display 中使用五种类型的值。除了最简单的之外，其他值都可以使用 display() 装饰器，该装饰器用于自定义字段的呈现方式。

• 模型字段的名称。例如

  class PersonAdmin(admin.ModelAdmin):
      list_display = ["first_name", "last_name"]
  

• 相关字段的名称，使用 __ 符号。例如

  class PersonAdmin(admin.ModelAdmin):
      list_display = ["city__name"]
  

• 一个可调用对象，它接受一个参数，即模型实例。例如

  @admin.display(description="Name")
  def upper_case_name(obj):
      return f"{obj.first_name} {obj.last_name}".upper()
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = [upper_case_name]
  

• 一个字符串，表示一个 ModelAdmin 方法，该方法接受一个参数，即模型实例。例如

  class PersonAdmin(admin.ModelAdmin):
      list_display = ["upper_case_name"]
  
      @admin.display(description="Name")
      def upper_case_name(self, obj):
          return f"{obj.first_name} {obj.last_name}".upper()
  

• 一个字符串，表示模型属性或方法（无需任何必需参数）。例如

  from django.contrib import admin
  from django.db import models
  
  
  class Person(models.Model):
      name = models.CharField(max_length=50)
      birthday = models.DateField()
  
      @admin.display(description="Birth decade")
      def decade_born_in(self):
          decade = self.birthday.year // 10 * 10
          return f"{decade}’s"
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = ["name", "decade_born_in"]
  

Django 5.1 中的更改

在针对相关字段时，添加了对使用 __ 查找的支持。

关于 list_display 需要注意的一些特殊情况

• 如果字段是 ForeignKey，Django 将显示相关对象的 __str__()。

• ManyToManyField 字段不受支持，因为这需要为表中的每一行执行单独的 SQL 语句。如果您仍然想这样做，请为您的模型提供一个自定义方法，并将该方法的名称添加到 list_display 中。（有关 list_display 中自定义方法的更多信息，请参见下文。）

• 如果字段是 BooleanField，Django 将显示一个漂亮的“是”、“否”或“未知”图标，而不是 True、False 或 None。

• 如果给定的字符串是模型、ModelAdmin 或可调用对象的方法，Django 默认情况下会对输出进行 HTML 转义。要转义用户输入并允许您自己的未转义标签，请使用 format_html()。

  这是一个完整的模型示例

  from django.contrib import admin
  from django.db import models
  from django.utils.html import format_html
  
  
  class Person(models.Model):
      first_name = models.CharField(max_length=50)
      last_name = models.CharField(max_length=50)
      color_code = models.CharField(max_length=6)
  
      @admin.display
      def colored_name(self):
          return format_html(
              '<span style="color: #{};">{} {}</span>',
              self.color_code,
              self.first_name,
              self.last_name,
          )
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = ["first_name", "last_name", "colored_name"]
  

• 如一些示例已经演示的那样，在使用可调用对象、模型方法或 ModelAdmin 方法时，您可以通过使用 display() 装饰器包装可调用对象并传递 description 参数来自定义列的标题。

• 如果字段的值为 None、空字符串或没有元素的可迭代对象，Django 将显示 -（破折号）。您可以使用 AdminSite.empty_value_display 覆盖此行为。

  from django.contrib import admin
  
  admin.site.empty_value_display = "(None)"
  

  您也可以使用 ModelAdmin.empty_value_display

  class PersonAdmin(admin.ModelAdmin):
      empty_value_display = "unknown"
  

  或在字段级别上

  class PersonAdmin(admin.ModelAdmin):
      list_display = ["name", "birth_date_view"]
  
      @admin.display(empty_value="unknown")
      def birth_date_view(self, obj):
          return obj.birth_date
  

• 如果给定的字符串是模型、ModelAdmin 或返回 True、False 或 None 的可调用对象的方法，如果您使用 display() 装饰器包装该方法并将 boolean 参数的值设置为 True，Django 将显示一个漂亮的“是”、“否”或“未知”图标。

  from django.contrib import admin
  from django.db import models
  
  
  class Person(models.Model):
      first_name = models.CharField(max_length=50)
      birthday = models.DateField()
  
      @admin.display(boolean=True)
      def born_in_fifties(self):
          return 1950 <= self.birthday.year < 1960
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = ["name", "born_in_fifties"]
  

• __str__() 方法在 list_display 中与任何其他模型方法一样有效，因此完全可以这样做。

  list_display = ["__str__", "some_other_field"]
  

• 通常，list_display 中不是实际数据库字段的元素不能用于排序（因为 Django 在数据库级别执行所有排序操作）。

  但是，如果 list_display 的某个元素表示某个数据库字段，则可以通过在方法上使用 display() 装饰器并传递 ordering 参数来指示此事实。

  from django.contrib import admin
  from django.db import models
  from django.utils.html import format_html
  
  
  class Person(models.Model):
      first_name = models.CharField(max_length=50)
      color_code = models.CharField(max_length=6)
  
      @admin.display(ordering="first_name")
      def colored_first_name(self):
          return format_html(
              '<span style="color: #{};">{}</span>',
              self.color_code,
              self.first_name,
          )
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = ["first_name", "colored_first_name"]
  

  以上操作将告诉 Django 在尝试通过管理员中的 colored_first_name 进行排序时，按 first_name 字段排序。

  要使用 ordering 参数指示降序，可以在字段名称前使用连字符前缀。使用上面的示例，这将如下所示：

  @admin.display(ordering="-first_name")
  def colored_first_name(self): ...
  

  ordering 参数支持查询查找，以便根据相关模型上的值进行排序。此示例在列表显示中包含一个“作者姓名”列，并允许按姓名进行排序。

  class Blog(models.Model):
      title = models.CharField(max_length=255)
      author = models.ForeignKey(Person, on_delete=models.CASCADE)
  
  
  class BlogAdmin(admin.ModelAdmin):
      list_display = ["title", "author", "author_first_name"]
  
      @admin.display(ordering="author__first_name")
      def author_first_name(self, obj):
          return obj.author.first_name
  

  可以使用 ordering 参数中的 查询表达式。

  from django.db.models import Value
  from django.db.models.functions import Concat
  
  
  class Person(models.Model):
      first_name = models.CharField(max_length=50)
      last_name = models.CharField(max_length=50)
  
      @admin.display(ordering=Concat("first_name", Value(" "), "last_name"))
      def full_name(self):
          return self.first_name + " " + self.last_name
  

• list_display 的元素也可以是属性。

  class Person(models.Model):
      first_name = models.CharField(max_length=50)
      last_name = models.CharField(max_length=50)
  
      @property
      @admin.display(
          ordering="last_name",
          description="Full name of the person",
          boolean=False,
      )
      def full_name(self):
          return self.first_name + " " + self.last_name
  
  
  class PersonAdmin(admin.ModelAdmin):
      list_display = ["full_name"]
  

  请注意，@property 必须位于 @display 上方。如果您使用旧方法（直接设置与显示相关的属性而不是使用 display() 装饰器）– 请注意，必须使用 property() 函数，而不是 @property 装饰器。

  def my_property(self):
      return self.first_name + " " + self.last_name
  
  
  my_property.short_description = "Full name of the person"
  my_property.admin_order_field = "last_name"
  my_property.boolean = False
  
  full_name = property(my_property)
  

  Django 5.0 中的更改

  添加了对属性上的 boolean 属性的支持。

• list_display 中的字段名称也将作为 CSS 类出现在 HTML 输出中，形式为 column-<field_name>，位于每个 <th> 元素上。例如，这可以用于在 CSS 文件中设置列宽。

• Django 将尝试按以下顺序解释 list_display 的每个元素。

  • 模型的字段或来自相关字段的字段。

  • 可调用对象。

  • 表示 ModelAdmin 属性的字符串。

  • 表示模型属性的字符串。

  例如，如果您具有 first_name 作为模型字段和 ModelAdmin 属性，则将使用模型字段。

ModelAdmin.list_display_links¶

使用 list_display_links 来控制 list_display 中的哪些字段（如果存在）应链接到对象的“更改”页面。

默认情况下，更改列表页面将链接第一列（在 list_display 中指定的第一个字段）到每个项目的更改页面。但是 list_display_links 允许您更改此行为。

• 将其设置为 None 以完全取消链接。

• 将其设置为字段列表或元组（与 list_display 格式相同），您希望将其列转换为链接。

  您可以指定一个或多个字段。只要这些字段出现在 list_display 中，Django 就不关心链接了多少（或多少）个字段。唯一的要求是，如果您想以这种方式使用 list_display_links，则必须定义 list_display。

在此示例中，first_name 和 last_name 字段将在更改列表页面上链接。

class PersonAdmin(admin.ModelAdmin):
    list_display = ["first_name", "last_name", "birthday"]
    list_display_links = ["first_name", "last_name"]

在此示例中，更改列表页面网格将没有链接。

class AuditEntryAdmin(admin.ModelAdmin):
    list_display = ["timestamp", "message"]
    list_display_links = None

ModelAdmin.list_editable¶

将 list_editable 设置为模型上允许在更改列表页面上编辑的字段名称列表。也就是说，在 list_editable 中列出的字段将作为表单窗口小部件显示在更改列表页面上，允许用户一次编辑和保存多行。

注意

list_editable 以特定的方式与其他几个选项交互；您应该注意以下规则。

• list_editable 中的任何字段也必须在 list_display 中。您不能编辑未显示的字段！

• 同一个字段不能同时列在 list_editable 和 list_display_links 中– 字段不能同时是表单和链接。

如果违反了这些规则中的任何一条，您将收到验证错误。

ModelAdmin.list_filter¶

设置 list_filter 以在管理员更改列表页面右侧边栏中激活过滤器。

最简单的用法是，list_filter 接受一个字段名称列表或元组，以激活这些字段的过滤功能，但还提供了许多更高级的选项。有关详细信息，请参阅 ModelAdmin 列表过滤器。

ModelAdmin.list_max_show_all¶

设置 list_max_show_all 以控制“显示全部”管理员更改列表页面上可以显示多少个项目。只有当总结果数小于或等于此设置时，管理员才会在更改列表上显示“显示全部”链接。默认情况下，此设置为 200。

ModelAdmin.list_per_page¶

设置 list_per_page 以控制每个分页的管理员更改列表页面上显示多少个项目。默认情况下，此设置为 100。

ModelAdmin.list_select_related¶

设置 list_select_related 以告诉 Django 在检索管理员更改列表页面上的对象列表时使用 select_related()。这可以节省大量数据库查询。

该值可以是布尔值、列表或元组。默认为 False。

当值为 True 时，将始终调用 select_related()。当值为 False 时，Django 将查看 list_display，如果存在任何 ForeignKey，则调用 select_related()。

如果您需要更细粒度的控制，请使用元组（或列表）作为 list_select_related 的值。空元组将完全阻止 Django 调用 select_related。任何其他元组都将作为参数直接传递给 select_related。例如

class ArticleAdmin(admin.ModelAdmin):
    list_select_related = ["author", "category"]

将调用 select_related('author', 'category')。

如果您需要根据请求指定动态值，则可以实现 get_list_select_related() 方法。

注意

当 select_related() 已经在更改列表的 QuerySet 上调用时，ModelAdmin 会忽略此属性。

ModelAdmin.ordering¶

设置 ordering 以指定在 Django 管理员视图中如何对对象列表进行排序。这应该是一个列表或元组，格式与模型的 ordering 参数相同。

如果未提供此参数，Django 管理员将使用模型的默认排序。

如果您需要指定动态排序（例如，取决于用户或语言），则可以实现 get_ordering() 方法。

排序和排序的性能注意事项

为了确保结果的确定性排序，如果更改列表找不到提供总排序的单个或唯一字段集，则会将 pk 添加到排序中。

例如，如果默认排序是按非唯一的 name 字段进行排序，则更改列表按 name 和 pk 进行排序。如果您有很多行并且没有对 name 和 pk 建立索引，这可能会导致性能下降。

ModelAdmin.paginator¶

用于分页的分页器类。默认情况下，使用 django.core.paginator.Paginator。如果自定义分页器类与 django.core.paginator.Paginator 具有不同的构造函数接口，则您还需要为 ModelAdmin.get_paginator() 提供实现。

ModelAdmin.prepopulated_fields¶

将 prepopulated_fields 设置为一个字典，将字段名称映射到它应该从中预填充的字段。

class ArticleAdmin(admin.ModelAdmin):
    prepopulated_fields = {"slug": ["title"]}

设置后，给定字段将使用一些 JavaScript 从分配的字段中填充。此功能的主要用途是从一个或多个其他字段自动生成 SlugField 字段的值。生成的值是通过连接源字段的值，然后将结果转换为有效的 slug（例如，用连字符替换空格并将 ASCII 字母小写）生成的。

保存值后，JavaScript 不会修改预填充的字段。通常不希望 slug 发生变化（如果 slug 用于对象 URL，则会导致对象的 URL 发生变化）。

prepopulated_fields 不接受 DateTimeField、ForeignKey、OneToOneField 和 ManyToManyField 字段。

ModelAdmin.preserve_filters¶

默认情况下，在创建、编辑或删除对象后，应用的过滤器会保留在列表视图中。您可以通过将此属性设置为 False 来清除过滤器。

ModelAdmin.show_facets¶

Django 5.0 中的新功能。

控制是否在管理员更改列表中显示过滤器的方面计数。默认为 ShowFacets.ALLOW。

显示时，方面计数会根据当前应用的过滤器进行更新。

class ShowFacets¶

Django 5.0 中的新功能。

ModelAdmin.show_facets 允许值的枚举。

ALWAYS¶

始终显示方面计数。

ALLOW¶

当提供 _facets 查询字符串参数时显示方面计数。

NEVER¶

从不显示方面计数。

将 show_facets 设置为所需的 ShowFacets 值。例如，要始终显示方面计数而无需提供查询参数

from django.contrib import admin


class MyModelAdmin(admin.ModelAdmin):
    ...
    # Have facets always shown for this model admin.
    show_facets = admin.ShowFacets.ALWAYS

方面性能注意事项

启用方面过滤器会增加管理员更改列表页面上的查询次数，具体取决于过滤器的数量。这些查询可能会导致性能问题，尤其是在大型数据集的情况下。在这些情况下，可以将 show_facets 设置为 ShowFacets.NEVER 以完全禁用方面功能。

ModelAdmin.radio_fields¶

默认情况下，Django 的 admin 使用选择框界面（<select>）来显示那些是 ForeignKey 或者设置了 choices 的字段。如果某个字段出现在 radio_fields 中，Django 将会使用单选按钮界面来代替。假设 group 是 Person 模型上的一个 ForeignKey

class PersonAdmin(admin.ModelAdmin):
    radio_fields = {"group": admin.VERTICAL}

您可以选择使用 HORIZONTAL 或 VERTICAL，它们来自 django.contrib.admin 模块。

除非某个字段是 ForeignKey 或者设置了 choices，否则不要将其包含在 radio_fields 中。

ModelAdmin.autocomplete_fields¶

autocomplete_fields 是一个 ForeignKey 和/或 ManyToManyField 字段的列表，您希望将其更改为 Select2 自动完成输入框。

默认情况下，admin 为这些字段使用选择框界面（<select>）。有时您不希望承担显示下拉菜单中所有相关实例的开销。

Select2 输入框看起来类似于默认输入框，但它带有一个异步加载选项的搜索功能。如果相关模型有很多实例，这会更快且更友好。

您必须在相关对象的 ModelAdmin 上定义 search_fields，因为自动完成搜索会使用它。

为了避免未经授权的数据泄露，用户必须拥有相关对象的 view 或 change 权限才能使用自动完成功能。

结果的排序和分页由相关 ModelAdmin 的 get_ordering() 和 get_paginator() 方法控制。

在以下示例中，ChoiceAdmin 具有一个指向 Question 的 ForeignKey 的自动完成字段。结果将根据 question_text 字段进行过滤，并按 date_created 字段排序。

class QuestionAdmin(admin.ModelAdmin):
    ordering = ["date_created"]
    search_fields = ["question_text"]


class ChoiceAdmin(admin.ModelAdmin):
    autocomplete_fields = ["question"]

大型数据集的性能注意事项

使用 ModelAdmin.ordering 进行排序可能会导致性能问题，因为对大型查询集进行排序会很慢。

此外，如果您的搜索字段包含数据库未索引的字段，则在超大型表上可能会遇到性能下降的问题。

对于这些情况，最好使用全文索引搜索编写您自己的 ModelAdmin.get_search_results() 实现。

您可能还需要在超大型表上更改 Paginator，因为默认分页器始终执行 count() 查询。例如，您可以覆盖 Paginator.count 属性的默认实现。

ModelAdmin.raw_id_fields¶

默认情况下，Django 的 admin 使用选择框界面（<select>）来显示那些是 ForeignKey 的字段。有时您不希望承担必须选择所有相关实例以在下拉菜单中显示的开销。

raw_id_fields 是一个字段列表，您希望将其更改为 Input 小部件，用于 ForeignKey 或 ManyToManyField。

class ArticleAdmin(admin.ModelAdmin):
    raw_id_fields = ["newspaper"]

如果字段是 ForeignKey，则 raw_id_fields Input 小部件应包含主键；如果字段是 ManyToManyField，则应包含以逗号分隔的值列表。 raw_id_fields 小部件在字段旁边显示一个放大镜按钮，允许用户搜索并选择一个值。

ModelAdmin.readonly_fields¶

默认情况下，admin 将所有字段显示为可编辑的。此选项中的任何字段（应为 list 或 tuple）都将按原样显示其数据，且不可编辑；它们也被排除在用于创建和编辑的 ModelForm 之外。请注意，当指定 ModelAdmin.fields 或 ModelAdmin.fieldsets 时，必须存在只读字段才能显示（否则将被忽略）。

如果使用 readonly_fields 且没有通过 ModelAdmin.fields 或 ModelAdmin.fieldsets 定义显式排序，则它们将被添加到所有可编辑字段之后。

只读字段不仅可以显示模型字段中的数据，还可以显示模型方法或 ModelAdmin 类本身的方法的输出。这与 ModelAdmin.list_display 的行为非常相似。这提供了一种方法，可以使用 admin 界面提供有关正在编辑的对象状态的反馈，例如。

from django.contrib import admin
from django.utils.html import format_html_join
from django.utils.safestring import mark_safe


class PersonAdmin(admin.ModelAdmin):
    readonly_fields = ["address_report"]

    # description functions like a model field's verbose_name
    @admin.display(description="Address")
    def address_report(self, instance):
        # assuming get_full_address() returns a list of strings
        # for each line of the address and you want to separate each
        # line by a linebreak
        return format_html_join(
            mark_safe("<br>"),
            "{}",
            ((line,) for line in instance.get_full_address()),
        ) or mark_safe("<span class='errors'>I can't determine this address.</span>")

ModelAdmin.save_as¶

将 save_as 设置为 True 以在 admin 修改表单上启用“另存为新文件”功能。

通常，对象有三个保存选项：“保存”、“保存并继续编辑”和“保存并添加另一个”。如果 save_as 为 True，“保存并添加另一个”将被“另存为新文件”按钮替换，该按钮会创建一个新对象（具有新 ID），而不是更新现有对象。

默认情况下，save_as 设置为 False。

ModelAdmin.save_as_continue¶

当 save_as=True 时，保存新对象后的默认重定向是到该对象的更改视图。如果将 save_as_continue 设置为 False，则重定向将到更改列表视图。

默认情况下，save_as_continue 设置为 True。

ModelAdmin.save_on_top¶

设置 save_on_top 以在 admin 修改表单的顶部添加保存按钮。

通常，保存按钮仅出现在表单底部。如果设置 save_on_top，则按钮将同时出现在顶部和底部。

默认情况下，save_on_top 设置为 False。

ModelAdmin.search_fields¶

设置 search_fields 以在 admin 更改列表页面上启用搜索框。这应设置为一个字段名称列表，每当有人在该文本框中提交搜索查询时，将搜索这些字段。

这些字段应为某种类型的文本字段，例如 CharField 或 TextField。您还可以使用查找 API 的“跟随”表示法对 ForeignKey 或 ManyToManyField 执行相关查找。

search_fields = ["foreign_key__related_fieldname"]

例如，如果您有一个带有作者的博客条目，以下定义将启用通过作者的电子邮件地址搜索博客条目。

search_fields = ["user__email"]

当用户在管理员搜索框中进行搜索时，Django 会将搜索查询拆分为单词，并返回包含每个单词的所有对象（不区分大小写，使用 icontains 查询），其中每个单词必须至少存在于 search_fields 中的一个字段中。例如，如果 search_fields 设置为 ['first_name', 'last_name']，并且用户搜索 john lennon，则 Django 会执行等效于以下 SQL WHERE 子句的操作

WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')

搜索查询可以包含带空格的带引号的短语。例如，如果用户搜索 "john winston" 或 'john winston'，则 Django 会执行等效于以下 SQL WHERE 子句的操作

WHERE (first_name ILIKE '%john winston%' OR last_name ILIKE '%john winston%')

如果您不想使用 icontains 作为查询，可以通过在字段后面附加查询来使用任何查询。例如，您可以通过将 search_fields 设置为 ['first_name__exact'] 来使用 exact。

还有一些（较旧的）指定字段查询的快捷方式可用。您可以在 search_fields 中的字段前缀添加以下字符，这等效于在字段中添加 __<lookup>

前缀	查询
^	istartswith
=	iexact
@	search
无	icontains

如果您需要自定义搜索，可以使用 ModelAdmin.get_search_results() 提供其他或替代的搜索行为。

ModelAdmin.search_help_text¶

设置 search_help_text 以指定搜索框的描述性文本，该文本将显示在其下方。

ModelAdmin.show_full_result_count¶

设置 show_full_result_count 以控制是否应在过滤后的管理员页面上显示对象的完整数量（例如 99 results (103 total)）。如果此选项设置为 False，则会显示类似 99 results (Show all) 的文本。

默认的 show_full_result_count=True 会生成一个查询以对表执行完整计数，如果表包含大量行，则此操作可能会很昂贵。

ModelAdmin.sortable_by¶

默认情况下，更改列表页面允许按所有模型字段（以及使用 display() 装饰器的 ordering 参数或具有 admin_order_field 属性的可调用对象）进行排序，这些字段在 list_display 中指定。

如果要禁用某些列的排序，请将 sortable_by 设置为 list_display 的子集的集合（例如 list、tuple 或 set），您希望这些列可排序。空集合会禁用所有列的排序。

如果您需要动态指定此列表，请改为实现 get_sortable_by() 方法。

ModelAdmin.view_on_site¶

设置 view_on_site 以控制是否显示“在站点上查看”链接。此链接应将您带到一个 URL，您可以在其中显示已保存的对象。

此值可以是布尔标志或可调用对象。如果为 True（默认值），则对象的 get_absolute_url() 方法将用于生成 URL。

如果您的模型具有 get_absolute_url() 方法，但您不希望显示“在站点上查看”按钮，则只需将 view_on_site 设置为 False

from django.contrib import admin


class PersonAdmin(admin.ModelAdmin):
    view_on_site = False

如果它是一个可调用对象，则它接受模型实例作为参数。例如

from django.contrib import admin
from django.urls import reverse


class PersonAdmin(admin.ModelAdmin):
    def view_on_site(self, obj):
        url = reverse("person-detail", kwargs={"slug": obj.slug})
        return "https://example.com" + url

ModelAdmin 方法¶

ModelAdmin.save_model(request, obj, form, change)[source]¶

save_model 方法接收 HttpRequest、模型实例、ModelForm 实例和一个布尔值（表示是添加还是修改对象）。重写此方法允许执行保存前或保存后的操作。调用 super().save_model() 使用 Model.save() 保存对象。

例如，要在保存之前将 request.user 附加到对象上

from django.contrib import admin


class ArticleAdmin(admin.ModelAdmin):
    def save_model(self, request, obj, form, change):
        obj.user = request.user
        super().save_model(request, obj, form, change)

ModelAdmin.delete_model(request, obj)[source]¶

delete_model 方法接收 HttpRequest 和模型实例。重写此方法允许执行删除前或删除后的操作。调用 super().delete_model() 使用 Model.delete() 删除对象。

ModelAdmin.delete_queryset(request, queryset)[source]¶

delete_queryset() 方法接收 HttpRequest 和要删除的对象的 QuerySet。重写此方法可以自定义“删除选定对象”操作的删除过程。

ModelAdmin.save_formset(request, form, formset, change)[source]¶

save_formset 方法接收 HttpRequest、父 ModelForm 实例和一个布尔值（表示是添加还是修改父对象）。

例如，将 request.user 附加到每个已更改的 formset 模型实例上

class ArticleAdmin(admin.ModelAdmin):
    def save_formset(self, request, form, formset, change):
        instances = formset.save(commit=False)
        for obj in formset.deleted_objects:
            obj.delete()
        for instance in instances:
            instance.user = request.user
            instance.save()
        formset.save_m2m()

另见 在 formset 中保存对象。

class PersonAdmin(admin.ModelAdmin):
    readonly_fields = ["name"]

    def get_readonly_fields(self, request, obj=None):
        readonly = super().get_readonly_fields(request, obj)
        if not request.user.is_superuser:
            readonly.append("age")  # Edits the class attribute.
        return readonly

ModelAdmin.get_ordering(request)¶

get_ordering 方法以 request 作为参数，并期望返回一个用于排序的 list 或 tuple，类似于 ordering 属性。例如

class PersonAdmin(admin.ModelAdmin):
    def get_ordering(self, request):
        if request.user.is_superuser:
            return ["name", "rank"]
        else:
            return ["name"]

ModelAdmin.get_search_results(request, queryset, search_term)[source]¶

get_search_results 方法修改显示的对象列表，使其仅包含与提供的搜索词匹配的对象。它接收请求、应用当前过滤器的查询集和用户提供的搜索词。它返回一个元组，其中包含一个修改后的查询集以实现搜索，以及一个布尔值，指示结果是否可能包含重复项。

默认实现搜索 ModelAdmin.search_fields 中命名的字段。

此方法可以使用你自己的自定义搜索方法覆盖。例如，你可能希望按整数字段搜索，或使用外部工具（如 Solr 或 Haystack）。你必须确定你的搜索方法实现的查询集更改是否可能在结果中引入重复项，并在返回值的第二个元素中返回 True。

例如，要按 name 和 age 搜索，你可以使用

class PersonAdmin(admin.ModelAdmin):
    list_display = ["name", "age"]
    search_fields = ["name"]

    def get_search_results(self, request, queryset, search_term):
        queryset, may_have_duplicates = super().get_search_results(
            request,
            queryset,
            search_term,
        )
        try:
            search_term_as_int = int(search_term)
        except ValueError:
            pass
        else:
            queryset |= self.model.objects.filter(age=search_term_as_int)
        return queryset, may_have_duplicates

此实现比 search_fields = ('name', '=age') 更有效，后者会导致对数字字段进行字符串比较，例如在 PostgreSQL 上为 ... OR UPPER("polls_choice"."votes"::text) = UPPER('4')。

ModelAdmin.save_related(request, form, formsets, change)[source]¶

save_related 方法接收 HttpRequest、父 ModelForm 实例、内联 formset 列表和一个布尔值（表示父对象是正在添加还是修改）。在这里，你可以对与父对象相关的对象执行任何保存前或保存后的操作。请注意，此时父对象及其表单已保存。

ModelAdmin.get_autocomplete_fields(request)¶

get_autocomplete_fields() 方法接收 HttpRequest，并期望返回一个字段名称的 list 或 tuple，这些字段将使用自动完成小部件显示，如上面 ModelAdmin.autocomplete_fields 部分所述。

ModelAdmin.get_readonly_fields(request, obj=None)¶

get_readonly_fields 方法接收 HttpRequest 和正在编辑的 obj（在添加表单中为 None），并期望返回一个 list 或 tuple，其中包含将以只读方式显示的字段名称，如上文 ModelAdmin.readonly_fields 部分所述。

ModelAdmin.get_prepopulated_fields(request, obj=None)¶

get_prepopulated_fields 方法接收 HttpRequest 和正在编辑的 obj（在添加表单中为 None），并期望返回一个 dictionary，如上文 ModelAdmin.prepopulated_fields 部分所述。

ModelAdmin.get_list_display(request)[source]¶

get_list_display 方法接收 HttpRequest，并期望返回一个 list 或 tuple，其中包含将在更改列表视图中显示的字段名称，如上文 ModelAdmin.list_display 部分所述。

ModelAdmin.get_list_display_links(request, list_display)[source]¶

get_list_display_links 方法接收 HttpRequest 和 ModelAdmin.get_list_display() 返回的 list 或 tuple。它期望返回 None 或一个 list 或 tuple，其中包含更改列表中将链接到更改视图的字段名称，如 ModelAdmin.list_display_links 部分所述。

ModelAdmin.get_exclude(request, obj=None)¶

get_exclude 方法接收 HttpRequest 和正在编辑的 obj（在添加表单中为 None），并期望返回一个字段列表，如 ModelAdmin.exclude 中所述。

ModelAdmin.get_fields(request, obj=None)¶

get_fields 方法接收 HttpRequest 和正在编辑的 obj（在添加表单中为 None），并期望返回一个字段列表，如上文 ModelAdmin.fields 部分所述。

ModelAdmin.get_fieldsets(request, obj=None)¶

get_fieldsets 方法接收 HttpRequest 和正在编辑的 obj（在添加表单中为 None），并期望返回一个包含 2 元组的列表，其中每个 2 元组代表管理表单页面上的一个 <fieldset>，如上文 ModelAdmin.fieldsets 部分所述。

ModelAdmin.get_list_filter(request)[source]¶

get_list_filter 方法接收 HttpRequest，并期望返回与 list_filter 属性相同的序列类型。

ModelAdmin.get_list_select_related(request)[source]¶

get_list_select_related 方法接收 HttpRequest，并应返回布尔值或列表，就像 ModelAdmin.list_select_related 所做的那样。

ModelAdmin.get_search_fields(request)[source]¶

get_search_fields 方法接收 HttpRequest，并期望返回与 search_fields 属性相同的序列类型。

ModelAdmin.get_sortable_by(request)¶

get_sortable_by() 方法接收 HttpRequest，并期望返回一个集合（例如 list、tuple 或 set），其中包含将在更改列表页面中可排序的字段名称。

它的默认实现返回 sortable_by（如果已设置），否则委托给 get_list_display()。

例如，要阻止一个或多个列可排序

class PersonAdmin(admin.ModelAdmin):
    def get_sortable_by(self, request):
        return {*self.get_list_display(request)} - {"rank"}

ModelAdmin.get_inline_instances(request, obj=None)[source]¶

给定的 get_inline_instances 方法会接收 HttpRequest 和正在编辑的 obj（或在添加表单上为 None），并期望返回一个 list 或 tuple，其中包含 InlineModelAdmin 对象，如下面的 InlineModelAdmin 部分所述。例如，以下代码将返回不基于添加、更改、删除和查看权限的默认过滤的内联。

class MyModelAdmin(admin.ModelAdmin):
    inlines = [MyInline]

    def get_inline_instances(self, request, obj=None):
        return [inline(self.model, self.admin_site) for inline in self.inlines]

如果覆盖此方法，请确保返回的内联是 inlines 中定义的类的实例，否则在添加相关对象时可能会遇到“错误请求”错误。

ModelAdmin.get_inlines(request, obj)¶

给定的 get_inlines 方法会接收 HttpRequest 和正在编辑的 obj（或在添加表单上为 None），并期望返回一个可迭代的内联对象。您可以覆盖此方法，以便根据请求或模型实例动态添加内联，而不是在 ModelAdmin.inlines 中指定它们。

ModelAdmin.get_urls()[source]¶

ModelAdmin 上的 get_urls 方法返回要用于该 ModelAdmin 的 URL，方式与 URLconf 相同。因此，您可以按照 URL 分发器 中所述扩展它们，在您的视图上使用 AdminSite.admin_view() 包装器。

from django.contrib import admin
from django.template.response import TemplateResponse
from django.urls import path


class MyModelAdmin(admin.ModelAdmin):
    def get_urls(self):
        urls = super().get_urls()
        my_urls = [path("my_view/", self.admin_site.admin_view(self.my_view))]
        return my_urls + urls

    def my_view(self, request):
        # ...
        context = dict(
            # Include common variables for rendering the admin template.
            self.admin_site.each_context(request),
            # Anything else you want in the context...
            key=value,
        )
        return TemplateResponse(request, "sometemplate.html", context)

如果要使用管理员布局，请从 admin/base_site.html 扩展。

{% extends "admin/base_site.html" %}
{% block content %}
...
{% endblock %}

注意

请注意 self.my_view 函数是如何被包装在 self.admin_site.admin_view 中的。这很重要，因为它确保了两件事。

1. 运行权限检查，确保只有活动的工作人员用户可以访问该视图。

2. 应用了 django.views.decorators.cache.never_cache() 装饰器以防止缓存，确保返回的信息是最新的。

注意

请注意，自定义模式包含在常规管理员 URL *之前*：管理员 URL 模式非常宽松，几乎可以匹配任何内容，因此您通常希望将自定义 URL 预置到内置 URL。

在此示例中，my_view 将可以通过 /admin/myapp/mymodel/my_view/ 访问（假设管理员 URL 包含在 /admin/ 中）。

如果页面可缓存，但您仍希望执行权限检查，则可以将 cacheable=True 参数传递给 AdminSite.admin_view()。

path("my_view/", self.admin_site.admin_view(self.my_view, cacheable=True))

ModelAdmin 视图具有 model_admin 属性。其他 AdminSite 视图具有 admin_site 属性。

ModelAdmin.get_form(request, obj=None, **kwargs)[source]¶

返回一个用于管理员添加和更改视图的 ModelForm 类，请参见 add_view() 和 change_view()。

基本实现使用 modelform_factory() 来对 form 进行子类化，并通过 fields 和 exclude 等属性进行修改。因此，例如，如果您想为超级用户提供其他字段，则可以像这样交换不同的基本表单。

class MyModelAdmin(admin.ModelAdmin):
    def get_form(self, request, obj=None, **kwargs):
        if request.user.is_superuser:
            kwargs["form"] = MySuperuserForm
        return super().get_form(request, obj, **kwargs)

您也可以直接返回自定义的 ModelForm 类。

ModelAdmin.get_formsets_with_inlines(request, obj=None)[source]¶

为管理员添加和更改视图生成 (FormSet, InlineModelAdmin) 对。

例如，如果您只想在更改视图中显示特定的内联，则可以按如下方式覆盖 get_formsets_with_inlines。

class MyModelAdmin(admin.ModelAdmin):
    inlines = [MyInline, SomeOtherInline]

    def get_formsets_with_inlines(self, request, obj=None):
        for inline in self.get_inline_instances(request, obj):
            # hide MyInline in the add view
            if not isinstance(inline, MyInline) or obj is not None:
                yield inline.get_formset(request, obj), inline

ModelAdmin.formfield_for_foreignkey(db_field, request, **kwargs)¶

ModelAdmin 上的 formfield_for_foreignkey 方法允许您覆盖外键字段的默认表单字段。例如，要根据用户返回此外键字段的对象子集。

class MyModelAdmin(admin.ModelAdmin):
    def formfield_for_foreignkey(self, db_field, request, **kwargs):
        if db_field.name == "car":
            kwargs["queryset"] = Car.objects.filter(owner=request.user)
        return super().formfield_for_foreignkey(db_field, request, **kwargs)

这使用 HttpRequest 实例过滤 Car 外键字段，仅显示 User 实例拥有的汽车。

对于更复杂的过滤器，您可以使用 ModelForm.__init__() 方法根据模型的 instance 进行过滤（请参见 处理关系的字段）。例如。

class CountryAdminForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["capital"].queryset = self.instance.cities.all()


class CountryAdmin(admin.ModelAdmin):
    form = CountryAdminForm

ModelAdmin.formfield_for_manytomany(db_field, request, **kwargs)¶

与 formfield_for_foreignkey 方法类似，可以覆盖 formfield_for_manytomany 方法来更改多对多字段的默认表单字段。例如，如果所有者可以拥有多辆汽车，而汽车可以属于多个所有者（多对多关系），则可以过滤 Car 外键字段，仅显示 User 拥有的汽车。

class MyModelAdmin(admin.ModelAdmin):
    def formfield_for_manytomany(self, db_field, request, **kwargs):
        if db_field.name == "cars":
            kwargs["queryset"] = Car.objects.filter(owner=request.user)
        return super().formfield_for_manytomany(db_field, request, **kwargs)

ModelAdmin.formfield_for_choice_field(db_field, request, **kwargs)¶

与 formfield_for_foreignkey 和 formfield_for_manytomany 方法类似，可以覆盖 formfield_for_choice_field 方法来更改已声明选择的字段的默认表单字段。例如，如果超级用户可用的选择应该与普通工作人员可用的选择不同，则可以按如下方式进行。

class MyModelAdmin(admin.ModelAdmin):
    def formfield_for_choice_field(self, db_field, request, **kwargs):
        if db_field.name == "status":
            kwargs["choices"] = [
                ("accepted", "Accepted"),
                ("denied", "Denied"),
            ]
            if request.user.is_superuser:
                kwargs["choices"].append(("ready", "Ready for deployment"))
        return super().formfield_for_choice_field(db_field, request, **kwargs)

choices 限制

表单字段上设置的任何choices属性都将仅限于该表单字段。如果模型上的对应字段设置了choices，则提供给表单的choices必须是这些choices的有效子集，否则表单提交将失败，并在保存前模型本身进行验证时引发ValidationError。

ModelAdmin.get_changelist(request, **kwargs)[source]¶

返回用于列表显示的Changelist类。默认情况下，使用django.contrib.admin.views.main.ChangeList。通过继承此类，您可以更改列表的行为。

ModelAdmin.get_changelist_form(request, **kwargs)[source]¶

返回在更改列表页面上的Formset中使用的ModelForm类。要使用自定义表单，例如

from django import forms


class MyForm(forms.ModelForm):
    pass


class MyModelAdmin(admin.ModelAdmin):
    def get_changelist_form(self, request, **kwargs):
        return MyForm

省略 Meta.model 属性

如果在ModelForm上定义了Meta.model属性，则还必须定义Meta.fields属性（或Meta.exclude属性）。但是，ModelAdmin会忽略此值，并使用ModelAdmin.list_editable属性覆盖它。最简单的解决方案是省略Meta.model属性，因为ModelAdmin将提供要使用的正确模型。

ModelAdmin.get_changelist_formset(request, **kwargs)[source]¶

如果使用了list_editable，则返回在更改列表页面上使用的ModelFormSet类。要使用自定义表单集，例如

from django.forms import BaseModelFormSet


class MyAdminFormSet(BaseModelFormSet):
    pass


class MyModelAdmin(admin.ModelAdmin):
    def get_changelist_formset(self, request, **kwargs):
        kwargs["formset"] = MyAdminFormSet
        return super().get_changelist_formset(request, **kwargs)

ModelAdmin.lookup_allowed(lookup, value, request)¶

更改列表页面中的对象可以通过URL查询字符串中的查找进行过滤。例如，list_filter就是这样工作的。查找类似于QuerySet.filter()中使用的查找（例如user__email=user@example.com）。由于查询字符串中的查找可以由用户操纵，因此必须对其进行清理以防止未经授权的数据泄露。

给定lookup_allowed()方法来自查询字符串的查找路径（例如'user__email'），相应的value（例如'user@example.com'）以及请求，并返回一个布尔值，指示是否允许使用这些参数过滤更改列表的QuerySet。如果lookup_allowed()返回False，则会引发DisallowedModelAdminLookup（SuspiciousOperation的子类）。

默认情况下，lookup_allowed()允许访问模型的本地字段、list_filter中使用的字段路径（但不包括来自get_list_filter()的路径）以及limit_choices_to在raw_id_fields中正常工作所需的查找。

覆盖此方法以自定义您的ModelAdmin子类允许的查找。

Django 5.0 中的更改

添加了request参数。

ModelAdmin.has_view_permission(request, obj=None)¶

如果允许查看obj，则应返回True，否则返回False。如果obj为None，则应返回True或False以指示是否通常允许查看此类型的对象（例如，False将被解释为表示当前用户不允许查看此类型的任何对象）。

默认实现如果用户具有“更改”或“查看”权限，则返回True。

ModelAdmin.has_add_permission(request)¶

如果允许添加对象，则应返回True，否则返回False。

ModelAdmin.has_change_permission(request, obj=None)¶

如果允许编辑obj，则应返回True，否则返回False。如果obj为None，则应返回True或False以指示是否通常允许编辑此类型的对象（例如，False将被解释为表示当前用户不允许编辑此类型的任何对象）。

ModelAdmin.has_delete_permission(request, obj=None)¶

如果允许删除obj，则应返回True，否则返回False。如果obj为None，则应返回True或False以指示是否通常允许删除此类型的对象（例如，False将被解释为当前用户不允许删除此类型的任何对象）。

ModelAdmin.has_module_permission(request)¶

如果允许在管理索引页面上显示模块并访问模块的索引页面，则应返回True，否则返回False。默认情况下使用User.has_module_perms()。覆盖它不会限制对视图、添加、更改或删除视图的访问，has_view_permission()、has_add_permission()、has_change_permission()和has_delete_permission()应用于此目的。

ModelAdmin.get_queryset(request)¶

ModelAdmin上的get_queryset方法返回一个QuerySet，其中包含管理站点可以编辑的所有模型实例。覆盖此方法的一个用例是显示登录用户拥有的对象

class MyModelAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        qs = super().get_queryset(request)
        if request.user.is_superuser:
            return qs
        return qs.filter(author=request.user)

ModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False)[source]¶

使用django.contrib.messages后端向用户发送消息。请参阅自定义 ModelAdmin 示例。

关键字参数允许您更改消息级别、添加额外的 CSS 标记，或者如果未安装contrib.messages框架则静默失败。这些关键字参数与django.contrib.messages.add_message()的参数相匹配，请参阅该函数的文档以获取更多详细信息。一个区别是级别可以作为字符串标签传递，除了整数/常量之外。

ModelAdmin.get_paginator(request, queryset, per_page, orphans=0, allow_empty_first_page=True)[source]¶

返回要为此视图使用的分页器的实例。默认情况下，实例化paginator的实例。

class MyModelAdmin(admin.ModelAdmin):
    # A template for a very customized change view:
    change_form_template = "admin/myapp/extras/openstreetmap_change_form.html"

    def get_osm_info(self):
        # ...
        pass

    def change_view(self, request, object_id, form_url="", extra_context=None):
        extra_context = extra_context or {}
        extra_context["osm_data"] = self.get_osm_info()
        return super().change_view(
            request,
            object_id,
            form_url,
            extra_context=extra_context,
        )