ModelAdmin 对象Link to this heading#
\n- \n
- \nclass ModelAdminLink to this definition# \n
\nModelAdmin类是管理界面中模型的表示。通常，这些都存储在你的应用程序中一个名为admin.py的文件中。让我们来看看ModelAdmin的一个例子：\n\nfrom django.contrib import admin\nfrom myapp.models import Author\n\nclass AuthorAdmin(admin.ModelAdmin):\n pass\nadmin.site.register(Author, AuthorAdmin)\n
register 装饰器Link to this heading#
\n- \n
- \nregister(*models, site=django.contrib.admin.sites.site)Link to this definition# \n
还有一个装饰器用于注册你的
\nModelAdmin类：\nfrom django.contrib import admin\nfrom .models import Author\n\n@admin.register(Author)\nclass AuthorAdmin(admin.ModelAdmin):\n pass\n它接受一个或多个模型类，让它在
\nModelAdmin注册。如果你使用的是自定义的AdminSite，请使用site关键字参数传递它：\nfrom django.contrib import admin\nfrom .models import Author, Editor, Reader\nfrom myproject.admin_site import custom_admin_site\n\n@admin.register(Author, Reader, Editor, site=custom_admin_site)\nclass PersonAdmin(admin.ModelAdmin):\n pass\n如果你必须在你的模型管理类的
\n__init__()方法中引用你的模型管理类，例如super(PersonAdmin, self).__init__(*args, **kwargs)，你就不能使用这个装饰器。你可以使用super().__init__(*args, **kwargs)。
发现管理文件Link to this heading#
\n当你在 INSTALLED_APPS 配置中放入 'django.contrib.admin' 时，Django 会自动在每个应用程序中寻找 admin 模块并导入它。
- \n
- \nclass apps.AdminConfigLink to this definition# \n
这是管理员默认的
\nAppConfig类。当 Django 启动时，它会调用autodiscover()。
- \n
- \nclass apps.SimpleAdminConfigLink to this definition# \n
这个类的工作原理和
\nAdminConfig一样，只是没有调用autodiscover()。- \n
- \ndefault_siteLink to this definition# \n
一个点分隔的导入路径，用于导入默认的管理站点类，或者导入一个返回站点实例的可调用类。默认为
\n'django.contrib.admin.sites.AdminSite'。使用方法参见 覆盖默认的管理站点。
- \n
- \nautodiscover()Link to this definition# \n
该函数试图在每个已安装的应用程序中导入一个
\nadmin模块。这些模块将向管理注册模型。通常情况下，你不需要直接调用这个函数，因为
\nAdminConfig会在 Django 启动时调用它。
如果你使用的是自定义的 AdminSite，通常会将所有的 ModelAdmin 子类导入到你的代码中，并将它们注册到自定义的 AdminSite。在这种情况下，为了禁止自动发现，你应该在你的 INSTALLED_APPS 配置中加入 'django.contrib.admin.apps.SimpleAdminConfig' 而不是 'django.contrib.admin'。
ModelAdmin 选项Link to this heading#
\nModelAdmin 非常灵活。它有几个选项用于处理自定义界面。所有选项都在 ModelAdmin 子类中定义：
from django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n date_hierarchy = 'pub_date'\n- \n
- \nModelAdmin.actionsLink to this definition# \n
要在变更列表页上提供的动作列表。详见 管理动作。
\n
- \n
- \nModelAdmin.actions_on_topLink to this definition# \n
- \n
- \nModelAdmin.actions_on_bottomLink to this definition# \n
控制动作栏在页面的哪个位置出现。默认情况下，管理员更改列表在页面顶部显示动作（
\nactions_on_top = True; actions_on_bottom = False）。
- \n
- \nModelAdmin.actions_selection_counterLink to this definition# \n
控制是否在动作下拉菜单旁边显示选择计数器。默认情况下，管理员变更列表会显示它（
\nactions_selection_counter = True）。
- \n
- \nModelAdmin.date_hierarchyLink to this definition# \n
将
\ndate_hierarchy设置为你的模型中DateField或DateTimeField的名称，变化列表页将包括一个基于日期的向下扩展。举例：
\n\ndate_hierarchy = 'pub_date'\n你也可以使用
\n__查找来指定相关模型上的字段，例如：\ndate_hierarchy = 'author__pub_date'\n这将根据可用的数据智能地填充自己，例如，如果所有的日期都在一个月内，它将只显示日级的向下扩展。
\n\n
- \n
- \nModelAdmin.empty_value_displayLink to this definition# \n
该属性覆盖记录字段为空（
\nNone、空字符串等）的默认显示值。默认值是-（破折号）。例如：\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n empty_value_display = '-empty-'\n你也可以用
\nAdminSite.empty_value_display覆盖所有管理页面的empty_value_display，或者像这样覆盖特定字段：\n\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n fields = ('name', 'title', 'view_birth_date')\n\n @admin.display(empty_value='???')\n def view_birth_date(self, obj):\n return obj.birth_date\n
- \n
- \nModelAdmin.excludeLink to this definition# \n
如果给定了这个属性，那么这个属性应该是一个要从表单中排除的字段名列表。
\n例如，我们考虑以下模型：
\n\nfrom django.db import models\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n title = models.CharField(max_length=3)\n birth_date = models.DateField(blank=True, null=True)\n如果你想让
\nAuthor模型的表格只包括name和title字段，你可以指定fields或exclude，如：\nfrom django.contrib import admin\n\nclass AuthorAdmin(admin.ModelAdmin):\n fields = ('name', 'title')\n\nclass AuthorAdmin(admin.ModelAdmin):\n exclude = ('birth_date',)\n由于 Author 模型只有三个字段，即
\nname、title和birth_date，因此上述声明所产生的表单将包含完全相同的字段。
- \n
- \nModelAdmin.fieldsLink to this definition# \n
使用
\nfields选项在 “添加” 和 “更改” 页面的表单中进行简单的布局修改，比如只显示可用字段的子集，修改它们的顺序，或者将它们分成几行。例如，你可以为django.contrib.flatpages.models.FlatPage模型定义一个更简单的管理表单版本，如下所示：\nclass FlatPageAdmin(admin.ModelAdmin):\n fields = ('url', 'title', 'content')\n在上面的例子中，只有
\nurl、title和content等字段会依次显示。fields可以包含ModelAdmin.readonly_fields中定义的值，以只读方式显示。对于更复杂的布局需求，请参阅
\nfieldets选项。
\nfields选项接受与list_display相同类型的值，只是不接受作为可调用对象的值。模型和模型管理方法的名称只有在readonly_fields中列出时才会被使用。要在同一行显示多个字段，将这些字段包在自己的元组中。在这个例子中，
\nurl和title字段将显示在同一行，content字段将显示在它们下面的一行：\n\nclass FlatPageAdmin(admin.ModelAdmin):\n fields = (('url', 'title'), 'content')\n如果
\nfields或fieldsets选项都不存在，Django 将默认在一个单一的字段集中显示每个非AutoField且有editable=True的字段，顺序与模型中定义的字段相同。
- \n
- \nModelAdmin.fieldsetsLink to this definition# \n
设置
\nfieldsets来控制管理员 “添加” 和 “更改” 页面的布局。
\nfieldsets是一个由两个元组组成的列表，其中每个元组代表管理表单页面上的一个<fieldset>。（一个<fieldset>是表单的一个 “部分”。)这两个元组的格式是
\n(name, field_options)，其中name是代表字段集标题的字符串，field_options是关于字段集的信息字典，包括要在其中显示的字段列表。一个完整的例子，取自
\ndjango.contrib.flatpages.models.FlatPage模型：\nfrom django.contrib import admin\n\nclass FlatPageAdmin(admin.ModelAdmin):\n fieldsets = (\n (None, {\n 'fields': ('url', 'title', 'content', 'sites')\n }),\n ('Advanced options', {\n 'classes': ('collapse',),\n 'fields': ('registration_required', 'template_name'),\n }),\n )\n这样一来，管理页面就变成了这样：
\n![\"/zh-hans/3.2/_images/fieldsets.png\"](\"/zh-hans/3.2/_images/fieldsets.png\")
\n如果
\nfieldsets或fields选项都不存在，Django 将默认在一个单一的表单集中显示每个非AutoField且有editable=True的字段，顺序与模型中定义的字段相同。
\nfield_options字典可以有以下键：- \n
- \n
fields要在该字段集中显示的字段名元组。这个键是必需的。
\n举例：
\n\n{\n'fields': ('first_name', 'last_name', 'address', 'city', 'state'),\n}\n与
\nfields选项一样，要在同一行显示多个字段，请将这些字段封装在自己的元组中。在这个例子中，first_name和last_name字段将显示在同一行：\n{\n'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),\n}\n
\nfields可以包含readonly_fields中定义的值，以只读方式显示。如果你将可调用的名称添加到
\nfields中，与fields选项的规则相同：可调用的名称必须列在readonly_fields中。 \n
\n- \n
classes一个包含额外 CSS 类的列表或元组，用于应用到字段集。
\n举例：
\n\n{\n'classes': ('wide', 'extrapretty'),\n}\n默认的管理网站样式表定义的两个有用的类是
\ncollapse和wide。collapse风格的字段集将在管理中被初始折叠，并被一个小的 “点击展开” 链接所取代；wide风格的字段集将被赋予额外的水平空间。wide风格的字段集将获得额外的水平空间。 \n
\n- \n
description一串可选的额外文本，显示在每个字段集的顶部，在字段集的标题下。这个字符串在
\nTabularInline中由于其布局的原因而无法显示。请注意，当这个值在管理界面显示时，它不是 HTML 转义后的。如果你愿意的话，这可以让你包含 HTML。或者你可以使用纯文本和
\ndjango.utils.html.escape()来转义任何 HTML 特殊字符。 \n
\n
- \n
- \nModelAdmin.filter_horizontalLink to this definition# \n
默认情况下，在管理网站中显示一个
\nManyToManyField是<select multiple>。但是，多选框在选择很多项目时，会很难用。在这个列表中添加一个ManyToManyField，就可以改用一个不显眼的 JavaScript “过滤器” 界面，在选项中进行搜索。未选择和选择的选项并排出现在两个框中。参见filter_vertical来使用垂直界面。
- \n
- \nModelAdmin.filter_verticalLink to this definition# \n
与
\nfilter_horizontal相同，但使用垂直显示过滤界面，未选择的选项框出现在选择选项框的上方。
- \n
- \nModelAdmin.formLink to this definition# \n
默认情况下，会为你的模型动态创建一个
\nModelForm。它用于创建在添加／更改页面上显示的表单。你可以很容易地提供你自己的ModelForm来覆盖添加／更改页面上的任何默认表单行为。另外，你可以使用ModelAdmin.get_form()方法来定制默认的表单，而不是指定一个全新的表单。示例请参见 在管理中添加自定义验证 一节。
\n\n\n
- \n
- \nModelAdmin.formfield_overridesLink to this definition# \n
这提供了一个快速而简单的方法来覆盖一些
\nField选项，以便在管理中使用。formfield_overrides是一个字典，它将字段类映射成一个参数的字典，以便在构造时传递给字段。由于这有点抽象，我们来看一个具体的例子。
\nformfield_overrides最常见的用法是为某一类型的字段添加一个自定义部件。所以，想象一下，我们写了一个RichTextEditorWidget，我们想用于大文本字段，而不是默认的<textarea>。下面是我们要做的：\nfrom django.contrib import admin\nfrom django.db import models\n\n# Import our custom widget and our model from where they're defined\nfrom myapp.models import MyModel\nfrom myapp.widgets import RichTextEditorWidget\n\nclass MyModelAdmin(admin.ModelAdmin):\n formfield_overrides = {\n models.TextField: {'widget': RichTextEditorWidget},\n }\n注意，字典中的键是实际的字段类，不是 字符串。值是另一个字典；这些参数将被传递给表单字段的
\n\n__init__()方法。详见 表单 API。
- \n
- \nModelAdmin.inlinesLink to this definition# \n
参见下面的
\nInlineModelAdmin对象以及ModelAdmin.get_formsets_with_inlines()。
- \n
- \nModelAdmin.list_displayLink to this definition# \n
设置
\nlist_display来控制哪些字段显示在管理的变更列表页面。举例：
\n\nlist_display = ('first_name', 'last_name')\n如果你不设置
\nlist_display，管理网站将显示一个单列，显示每个对象的__str__()表示。有四种类型的值可以在
\nlist_display中使用。除了最简单的可以使用display()装饰器用于自定义字段的显示方式：- \n
模型字段的名称。例如：
\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name')\n\n一个接受一个参数的可调用对象，即模型实例。例如：
\n\n@admin.display(description='Name')\ndef upper_case_name(obj):\n return ("%s %s" % (obj.first_name, obj.last_name)).upper()\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = (upper_case_name,)\n\n表示
\nModelAdmin方法的字符串，该方法接受一个参数，即模型实例。例如：\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('upper_case_name',)\n\n @admin.display(description='Name')\n def upper_case_name(self, obj):\n return ("%s %s" % (obj.first_name, obj.last_name)).upper()\n\n代表模型属性或方法的字符串（没有任何必要的参数）。例如：
\n\nfrom django.contrib import admin\nfrom django.db import models\n\nclass Person(models.Model):\n name = models.CharField(max_length=50)\n birthday = models.DateField()\n\n @admin.display(description='Birth decade')\n def decade_born_in(self):\n return '%d’s' % (self.birthday.year // 10 * 10)\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'decade_born_in')\n\n
关于
\nlist_display要注意的几个特殊情况：- \n
如果字段是
ForeignKey，Django 会显示相关对象的__str__()。 \nManyToManyField字段不被支持，因为这需要为表中的每一行单独执行一条 SQL 语句。如果你还是想这样做，请给你的模型一个自定义方法，并将该方法的名称添加到list_display中。（更多关于list_display中的自定义方法，请参见下文）。 \n如果字段是
BooleanField，Django 会显示一个漂亮的 “是”、“否” 或 “未知” 图标，而不是True、False或None。 \n如果给定的字符串是模型的一个方法，
\nModelAdmin或者是一个可调用的方法，Django 默认会对输出进行 HTML 转义。如果要转义用户的输入，并允许你自己使用未转义的标签，可以使用format_html()。下面是一个完整的示例模型：
\n\nfrom django.contrib import admin\nfrom django.db import models\nfrom django.utils.html import format_html\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n color_code = models.CharField(max_length=6)\n\n @admin.display\n def colored_name(self):\n return format_html(\n '<span style="color: #{};">{} {}</span>',\n self.color_code,\n self.first_name,\n self.last_name,\n )\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'colored_name')\n\n正如一些例子已经证明的那样，当使用一个可调用对象、一个模型方法或一个
\n\nModelAdmin方法时，你可以通过用display()装饰器包装可调用对象，并传递description参数来自定义列的标题。 \n如果一个字段的值是
\nNone，一个空字符串，或者一个没有元素的可迭代字段，Django 将显示-（破折号）。你可以用AdminSite.empty_value_display来覆盖这一点：\nfrom django.contrib import admin\n\nadmin.site.empty_value_display = '(None)'\n你也可以使用
\nModelAdmin.empty_value_display：\nclass PersonAdmin(admin.ModelAdmin):\n empty_value_display = 'unknown'\n或在字段级别：
\n\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'birth_date_view')\n\n @admin.display(empty_value='unknown')\n def birth_date_view(self, obj):\n return obj.birth_date\n\n如果给定的字符串是模型的一个方法，
\nModelAdmin或一个返回True、False或None的可调用对象，如果你用display()装饰器包装该方法，传递boolean参数，并将其值设置为True：\n\nfrom django.contrib import admin\nfrom django.db import models\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n birthday = models.DateField()\n\n @admin.display(boolean=True)\n def born_in_fifties(self):\n return 1950 <= self.birthday.year < 1960\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'born_in_fifties')\n\n
\n__str__()方法在list_display中和其他模型方法一样有效，所以完全可以这样做：\nlist_display = ('__str__', 'some_other_field')\n\n通常情况下，
\nlist_display的元素如果不是实际的数据库字段，就不能用于排序（因为 Django 在数据库层面进行了所有的排序）。但是，如果
\nlist_display的元素代表某个数据库字段，你可以通过在方法上使用display()装饰器，传递ordering参数来表明这个事实：\nfrom django.contrib import admin\nfrom django.db import models\nfrom django.utils.html import format_html\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n color_code = models.CharField(max_length=6)\n\n @admin.display(ordering='first_name')\n def colored_first_name(self):\n return format_html(\n '<span style="color: #{};">{}</span>',\n self.color_code,\n self.first_name,\n )\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'colored_first_name')\n上面会告诉 Django 在管理中按
\ncolored_first_name排序时，按first_name字段排序。要用
\nordering参数表示降序，可以在字段名上使用连字符前缀。使用上面的例子，它看起来像：\n@admin.display(ordering='-first_name')\n
\nordering参数支持查询查找，在相关模型上按值排序。这个例子在列表显示中包含了一个 “作者的姓” 列，并允许按姓排序：\nclass Blog(models.Model):\n title = models.CharField(max_length=255)\n author = models.ForeignKey(Person, on_delete=models.CASCADE)\n\nclass BlogAdmin(admin.ModelAdmin):\n list_display = ('title', 'author', 'author_first_name')\n\n @admin.display(ordering='author__first_name')\n def author_first_name(self, obj):\n return obj.author.first_name\n查询表达式 可与
\nordering参数一起使用：\n\nfrom django.db.models import Value\nfrom django.db.models.functions import Concat\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n\n @admin.display(ordering=Concat('first_name', Value(' '), 'last_name'))\n def full_name(self):\n return self.first_name + ' ' + self.last_name\n\n
\nlist_display的元素也可以是属性：\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n\n @property\n @admin.display(\n ordering='last_name',\n description='Full name of the person',\n )\n def full_name(self):\n return self.first_name + ' ' + self.last_name\n\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('full_name',)\n注意
\n@property必须在@display之上。如果你使用老方法 —— 直接设置与 display 相关的属性，而不是使用display()装饰器 —— 请注意，必须使用property()函数，而 不是@property装饰器：\ndef my_property(self):\n return self.first_name + ' ' + self.last_name\nmy_property.short_description = "Full name of the person"\nmy_property.admin_order_field = 'last_name'\n\nfull_name = property(my_property)\n\nlist_display中的字段名也会以 CSS 类的形式出现在 HTML 输出中，在每个<th>元素上以column-<field_name>的形式出现。例如，这可以用来在 CSS 文件中设置列宽。 \nDjango 会尝试按照这个顺序解释
\nlist_display的每个元素：- \n
一个模型的字段。
\n一个可调用对象。
\n一个代表
ModelAdmin属性的字符串。 \n一个代表模型属性的字符串。
\n
例如，如果你有
\nfirst_name作为一个模型字段和ModelAdmin属性，将使用模型字段。 \n
- \n
- \nModelAdmin.list_display_linksLink to this definition# \n
使用
\nlist_display_links来控制list_display中的字段是否以及哪些字段应该被链接到对象的 “更改” 页面。默认情况下，更改列表页将把第一列 ——
\nlist_display中指定的第一个字段 —— 链接到每个项目的更改页面。但是list_display_links让你改变这一点：- \n
将其设置为
None，则完全没有链接。 \n将它设置为一个列表或元组字段（格式与
\nlist_display相同），你希望将其列转换为链接。你可以指定一个或多个字段。只要字段出现在
\nlist_display中，Django 就不会关心链接了多少（或多少）字段。唯一的要求是，如果你想以这种方式使用list_display_links，你必须定义list_display。 \n
在这个例子中，
\nfirst_name和last_name字段将在更改列表页面上被链接：\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('first_name', 'last_name', 'birthday')\n list_display_links = ('first_name', 'last_name')\n在这个例子中，更改列表页网格将没有链接：
\n\nclass AuditEntryAdmin(admin.ModelAdmin):\n list_display = ('timestamp', 'message')\n list_display_links = None\n
- \n
- \nModelAdmin.list_editableLink to this definition# \n
将
\n\nlist_editable设置为模型上允许在更改列表页上编辑的字段名称列表。也就是说，在list_editable中列出的字段将作为表单部件显示在变更列表页上，允许用户一次编辑和保存多行。
- \n
- \nModelAdmin.list_filterLink to this definition# \n
设置
\nlist_filter来激活管理更改列表页面右侧侧栏的过滤器，如下截图所示：![\"/zh-hans/3.2/_images/list_filter.png\"](\"/zh-hans/3.2/_images/list_filter.png\")
\n
\nlist_filter应是一个元素的列表或元组，其中每个元素应是下列类型之一：- \n
一个字段名，其中指定的字段应该是
\nBooleanField`、CharField`、DateField、DateTimeField、IntegerField、ForeignKey或ManyToManyField，例如：\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = ('is_staff', 'company')\n
\nlist_filter中的字段名也可以使用__查找来跨越关系，例如：\nclass PersonAdmin(admin.UserAdmin):\n list_filter = ('company__name',)\n\n继承自
\ndjango.contrib.admin.SimpleListFilter的类，你需要为其提供title和parameter_name属性，并覆盖lookups和queryset方法，例如：\n\nfrom datetime import date\n\nfrom django.contrib import admin\nfrom django.utils.translation import gettext_lazy as _\n\nclass DecadeBornListFilter(admin.SimpleListFilter):\n # Human-readable title which will be displayed in the\n # right admin sidebar just above the filter options.\n title = _('decade born')\n\n # Parameter for the filter that will be used in the URL query.\n parameter_name = 'decade'\n\n def lookups(self, request, model_admin):\n """\n Returns a list of tuples. The first element in each\n tuple is the coded value for the option that will\n appear in the URL query. The second element is the\n human-readable name for the option that will appear\n in the right sidebar.\n """\n return (\n ('80s', _('in the eighties')),\n ('90s', _('in the nineties')),\n )\n\n def queryset(self, request, queryset):\n """\n Returns the filtered queryset based on the value\n provided in the query string and retrievable via\n `self.value()`.\n """\n # Compare the requested value (either '80s' or '90s')\n # to decide how to filter the queryset.\n if self.value() == '80s':\n return queryset.filter(birthday__gte=date(1980, 1, 1),\n birthday__lte=date(1989, 12, 31))\n if self.value() == '90s':\n return queryset.filter(birthday__gte=date(1990, 1, 1),\n birthday__lte=date(1999, 12, 31))\n\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = (DecadeBornListFilter,)\n\n一个元组，其中第一个元素是字段名，第二个元素是继承自
\ndjango.contrib.admin.FieldListFilter的类，例如：\nclass PersonAdmin(admin.ModelAdmin):\n list_filter = (\n ('is_staff', admin.BooleanFieldListFilter),\n )\n你可以使用
\nRelatedOnlyFieldListFilter将相关模型的选择限制在该关系所涉及的对象上：\nclass BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('author', admin.RelatedOnlyFieldListFilter),\n )\n假设
\nauthor是ForeignKey到User模型，这将会把list_filter的选择限制在写过书的用户，而不是列出所有用户。你可以使用
\nEmptyFieldListFilter来过滤空值，它既可以过滤空字符串也可以过滤空值，这取决于字段允许存储的内容：\n\n\n\nclass BookAdmin(admin.ModelAdmin):\n list_filter = (\n ('title', admin.EmptyFieldListFilter),\n )\n\n
列表过滤器通常只有在过滤器有多个选择时才会出现。过滤器的
\nhas_output()方法控制它是否出现。可以指定一个自定义模板来呈现列表过滤器：
\n\nclass FilterWithCustomTemplate(admin.SimpleListFilter):\n template = "custom_template.html"\n具体的例子请看 Django 提供的默认模板（
\nadmin/filter.html）。
- \n
- \nModelAdmin.list_max_show_allLink to this definition# \n
设置
\nlist_max_show_all来控制 “全部显示” 的管理员更改列表页面上可以出现多少个项目。只有当总结果数小于或等于此配置时，管理才会在更改列表中显示 “全部显示” 链接。默认情况下，这个配置为200。
- \n
- \nModelAdmin.list_per_pageLink to this definition# \n
设置
\nlist_per_page来控制每个分页的管理变更列表页面上出现多少个项目。默认情况下，设置为100。
- \n\n
设置
\nlist_select_related告诉 Django 在检索管理变更列表页的对象列表时使用select_related()。这样可以省去一堆数据库查询。该值应是布尔值、列表或元组。默认值是
\nFalse。当值为
\nTrue时，select_related()总是会被调用。当值设置为False时，Django 将查看list_display，如果有ForeignKey，则调用select_related()。如果你需要更精细的控制，可以使用元组（或列表）作为
\nlist_select_related的值。空元组将阻止 Django 调用select_related。任何其他元组将直接传递给select_related作为参数。例如：\nclass ArticleAdmin(admin.ModelAdmin):\n list_select_related = ('author', 'category')\n将调用
\nselect_related('author', 'category')。如果需要根据请求指定一个动态值，可以实现一个
\n\nget_list_select_related()方法。
- \n
- \nModelAdmin.orderingLink to this definition# \n
设置
\nordering来指定对象列表在 Django 管理视图中的排序方式。这应该是一个列表或元组，格式与模型的ordering参数相同。如果没有提供，Django 管理员将使用模型的默认排序。
\n如果你需要指定一个动态的顺序（例如取决于用户或语言），你可以实现一个
\n\nget_ordering()方法。
- \n
- \nModelAdmin.paginatorLink to this definition# \n
用于分页的分页器类。默认情况下，使用
\ndjango.core.paginator.Paginator。如果自定义的分页器类没有和django.core.paginator.Paginator一样的构造函数接口，你还需要为ModelAdmin.get_paginator()提供一个实现。
- \n
- \nModelAdmin.prepopulated_fieldsLink to this definition# \n
将
\nprepopulated_fields设置为一个字典，将字段名称映射到它应该预先填充的字段：\nclass ArticleAdmin(admin.ModelAdmin):\n prepopulated_fields = {"slug": ("title",)}\n当设置时，给定的字段将使用一点 JavaScript 从分配的字段中填充。这个功能的主要用途是从一个或多个其他字段自动生成
\nSlugField字段的值。生成的值是通过连接源字段的值，然后将结果转化为有效的 slug（例如，用破折号代替空格，使用 ASCII 字母的小写字母）。预填充的字段在保存值后不会被 JavaScript 修改。通常情况下，不希望 slug 发生变化（如果对象中使用了 slug，会导致对象的 URL 发生变化）。
\n
\n\nprepopulated_fields不接受DateTimeField、ForeignKey、OneToOneField和ManyToManyField字段。
- \n
- \nModelAdmin.preserve_filtersLink to this definition# \n
默认情况下，在创建、编辑或删除对象后，应用的过滤器会被保存在列表视图中。您可以通过将此属性设置为
\nFalse来清除过滤器。
- \n
- \nModelAdmin.radio_fieldsLink to this definition# \n
默认情况下，Django 的管理对于
\nForeignKey或设置了choices的字段使用选择框界面（<select>）。如果字段存在于radio_fields中，Django 将使用单选按钮接口代替。假设group是Person模型上的一个ForeignKey：\nclass PersonAdmin(admin.ModelAdmin):\n radio_fields = {"group": admin.VERTICAL}\n你可以在
\ndjango.contrib.admin模块中选择使用HORIZONTAL或VERTICAL。不要在
\nradio_fields中包含一个字段，除非它是ForeignKey或已设置choices。
- \n
- \nModelAdmin.autocomplete_fieldsLink to this definition# \n
\nautocomplete_fields是一个ForeignKey和／或ManyToManyField字段的列表，你想将其改为 Select2 自动完成输入。
\nautocomplete_fields是一个ForeignKey和／或的列表，默认情况下，管理对这些字段使用选择框接口（<select>）。有时你不想产生选择所有相关实例在下拉中显示的开销。ManyToManyField字段你想改成 Select2 自动完成输入。Select2 输入看起来与默认输入类似，但自带搜索功能，异步加载选项。如果相关模型有很多实例，这样会更快、更方便用户使用。
\n你必须在相关对象的
\nModelAdmin上定义search_fields，因为自动完成搜索使用它。为了避免未经授权的数据泄露，用户必须拥有相关对象的
\nview或change权限才能使用自动完成。结果的排序和分页由相关的
\nModelAdmin的get_ordering()和get_paginator()方法控制。在下面的例子中，
\nChoiceAdmin对Question有一个ForeignKey的自动完成字段。结果由question_text字段过滤，并由date_created字段排序：\n\nclass QuestionAdmin(admin.ModelAdmin):\n ordering = ['date_created']\n search_fields = ['question_text']\n\nclass ChoiceAdmin(admin.ModelAdmin):\n autocomplete_fields = ['question']\n
- \n
- \nModelAdmin.raw_id_fieldsLink to this definition# \n
默认情况下，Django 的管理员对
\nForeignKey的字段使用选择框接口（<select>）。有时候，你不想产生必须选择所有相关的实例来显示在下拉框中的开销。
\nraw_id_fields是你想改变为ForeignKey或ManyToManyField的Input部件的字段列表：\nclass ArticleAdmin(admin.ModelAdmin):\n raw_id_fields = ("newspaper",)\n
\nraw_id_fields的Input部件应该包含一个主键，如果该字段是`ForeignKey`。或者是一个逗号分隔的值列表，如果该字段是ManyToManyField。raw_id_fields部件在字段旁边显示一个放大镜按钮，允许用户搜索和选择一个值：![\"/zh-hans/3.2/_images/raw_id_fields.png\"](\"/zh-hans/3.2/_images/raw_id_fields.png\")
\n
- \n
- \nModelAdmin.readonly_fieldsLink to this definition# \n
默认情况下，管理会将所有字段显示为可编辑。该选项中的任何字段（应该是
\nlist或tuple）将按原样显示其数据，不可编辑；它们也被排除在用于创建和编辑的ModelForm中。请注意，当指定ModelAdmin.fields或ModelAdmin.fieldsets时，只读字段必须存在才能显示（否则将被忽略）。如果没有通过
\nModelAdmin.fields或ModelAdmin.fielets定义明确的顺序就使用readonly_fields，它们将在所有可编辑字段之后最后添加。一个只读字段不仅可以显示模型字段的数据，还可以显示模型的方法或
\nModelAdmin类本身的方法的输出。这与ModelAdmin.list_display的行为方式非常相似。这提供了一种方法来使用管理员接口来提供被编辑对象的状态反馈，例如：\nfrom django.contrib import admin\nfrom django.utils.html import format_html_join\nfrom django.utils.safestring import mark_safe\n\nclass PersonAdmin(admin.ModelAdmin):\n readonly_fields = ('address_report',)\n\n # description functions like a model field's verbose_name\n @admin.display(description='Address')\n def address_report(self, instance):\n # assuming get_full_address() returns a list of strings\n # for each line of the address and you want to separate each\n # line by a linebreak\n return format_html_join(\n mark_safe('<br>'),\n '{}',\n ((line,) for line in instance.get_full_address()),\n ) or mark_safe("<span class='errors'>I can't determine this address.</span>")\n
- \n
- \nModelAdmin.save_asLink to this definition# \n
设置
\nsave_as，在管理更改表格时启用 “另存为新” 功能。通常情况下，对象有三个保存选项。“保存”、“保存并继续编辑” 和 “保存并添加另一个”。如果
\nsave_as为True，则 “保存并添加另一个” 将被 “另存为新” 按钮所取代，该按钮将创建一个新的对象（具有新的 ID），而不是更新现有的对象。默认情况下，
\nsave_as被设置为False。
- \n
- \nModelAdmin.save_as_continueLink to this definition# \n
当
\nsave_as=True时，保存新对象后默认重定向到该对象的变更视图。如果设置save_as_continue=False，则重定向到变更列表视图。默认情况下，
\nsave_as_continue被设置为True。
- \n
- \nModelAdmin.save_on_topLink to this definition# \n
设置
\nsave_on_top来在你的管理更改表格的顶部添加保存按钮。通常情况下，保存按钮只出现在表格的底部。如果设置
\nsave_on_top，按钮将同时出现在顶部和底部。默认情况下，
\nsave_on_top被设置为False。
- \n
- \nModelAdmin.search_fieldsLink to this definition# \n
设置
\nsearch_fields，在管理更改列表页面上启用搜索框。这应该被设置为字段名的列表，每当有人在该文本框中提交搜索查询时，就会被搜索到。这些字段应该是某种文本字段，如
\nCharField或TextField。你也可以对ForeignKey或ManyToManyField进行相关查询，并使用查找 API “follow” 符号：\nsearch_fields = ['foreign_key__related_fieldname']\n例如，如果你有一个有作者的博客条目，下面的定义将可以通过作者的电子邮件地址搜索博客条目：
\n\nsearch_fields = ['user__email']\n当有人在管理搜索框中进行搜索时，Django 会将搜索查询拆分成多个词，并返回所有包含这些词的对象，不区分大小写（使用
\nicontains查找），其中每个词必须在search_fields中至少有一个。例如，如果search_fields设置为['first_name', 'last_name']，用户搜索john lennon'，Django 会做相当于这个 SQLWHERE子句。\nWHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')\nAND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')\n搜索查询可以包含带空格的引号短语。例如，如果用户搜索
\n"john winston"或'john winston'，Django 会做相当于这个 SQL 的WHERE子句：\nWHERE (first_name ILIKE '%john winston%' OR last_name ILIKE '%john winston%')\n如果你不想使用
\nicontains作为查找，你可以通过附加字段来使用任何查找。例如，你可以通过设置search_fields为['first_name__exact']来使用exact。还可以使用一些（较老的）快捷方式来指定字段查找。你可以在
\nsearch_fields中的字段前加上以下字符，相当于在字段中加上__<lookup>。\n\n\n
\n前缀
查找
^
\n =
\n @
\n None
\n 如果你需要自定义搜索，你可以使用
\n\nModelAdmin.get_search_results()来提供额外的或替代的搜索行为。
- \n
- \nModelAdmin.show_full_result_countLink to this definition# \n
设置
\nshow_full_result_count来控制是否应该在过滤后的管理页面上显示全部对象的数量（例如：99 results (103 total)）。如果这个选项被设置为False，则会显示99 results (Show all)这样的文字。默认的
\nshow_full_result_count=True会生成一个对表进行完整计数的查询，如果表包含大量的行，那么这个查询可能会很昂贵。
- \n
- \nModelAdmin.sortable_byLink to this definition# \n
默认情况下，变更列表页面允许按
\nlist_display中指定的所有模型字段（以及使用display()装饰器的ordering参数或具有admin_order_field属性的可调用对象）进行排序。如果你想禁止对某些列进行排序，请将
\nsortable_by设置为你想排序的list_display子集的一个集合（例如list`、tuple或set）。一个空的集合会禁用所有列的排序。如果你需要动态地指定这个列表，可以实现一个
\nget_sortable_by()方法来代替。
- \n
- \nModelAdmin.view_on_siteLink to this definition# \n
设置
\nview_on_site来控制是否显示 “在站点上查看” 链接。这个链接应该把你带到一个可以显示保存对象的 URL。这个值可以是一个布尔标志，也可以是一个可调用对象。如果
\nTrue（默认），对象的get_absolute_url()方法将被用来生成网址。如果你的模型有一个
\nget_absolute_url()方法，但你不想让 “在站点上查看” 按钮出现，你只需要将view_on_site设置为False：\nfrom django.contrib import admin\n\nclass PersonAdmin(admin.ModelAdmin):\n view_on_site = False\n如果它是一个可调用对象，它接受模型实例作为参数。例如：
\n\nfrom django.contrib import admin\nfrom django.urls import reverse\n\nclass PersonAdmin(admin.ModelAdmin):\n def view_on_site(self, obj):\n url = reverse('person-detail', kwargs={'slug': obj.slug})\n return 'https://example.com' + url\n
自定义模板选项Link to this heading#
\n覆盖管理模板 部分描述了如何覆盖或扩展默认的管理模板。 使用以下选项来覆盖 ModelAdmin 视图使用的默认模板。
- \n
- \nModelAdmin.add_form_templateLink to this definition# \n
自定义模板的路径，由
\nadd_view()使用。
- \n
- \nModelAdmin.change_form_templateLink to this definition# \n
自定义模板的路径，由
\nchange_view()使用。
- \n
- \nModelAdmin.change_list_templateLink to this definition# \n
自定义模板的路径，由
\nchangelist_view()使用。
- \n
- \nModelAdmin.delete_confirmation_templateLink to this definition# \n
自定义模板的路径，由
\ndelete_view()用于在删除一个或多个对象时显示确认页面。
- \n
- \nModelAdmin.delete_selected_confirmation_templateLink to this definition# \n
自定义模板的路径，由
\ndelete_selected动作方法使用，在删除一个或多个对象时显示确认页面。参见 动作文档。
- \n
- \nModelAdmin.object_history_templateLink to this definition# \n
自定义模板的路径，由
\nhistory_view()使用。
- \n
- \nModelAdmin.popup_response_templateLink to this definition# \n
\nresponse_add()、response_change()和response_delete()使用的自定义模板的路径。
ModelAdmin 方法Link to this heading#
\n\n- \n
- \nModelAdmin.save_model(request, obj, form, change)Link to this definition# \n
\nsave_model方法被赋予HttpRequest、一个模型实例、一个ModelForm实例和一个基于是否添加或更改对象的布尔值。覆盖这个方法可以进行保存前或保存后的操作。调用super().save_model()使用Model.save()保存对象。例如，在保存之前将
\nrequest.user附加到对象上：\nfrom django.contrib import admin\n\nclass ArticleAdmin(admin.ModelAdmin):\n def save_model(self, request, obj, form, change):\n obj.user = request.user\n super().save_model(request, obj, form, change)\n
- \n
- \nModelAdmin.delete_model(request, obj)Link to this definition# \n
\ndelete_model方法被赋予HttpRequest和一个模型实例。覆盖该方法可以进行删除前或删除后的操作。调用super().delete_model()使用Model.delete`()删除对象。
- \n
- \nModelAdmin.delete_queryset(request, queryset)Link to this definition# \n
\ndelete_queryset()方法是给定HttpRequest和一个QuerySet要删除的对象。重写该方法，可以自定义 “删除选定对象” 的删除过程 动作。
- \n
- \nModelAdmin.save_formset(request, form, formset, change)Link to this definition# \n
\nsave_formset方法被赋予HttpRequest、父ModelForm实例和一个基于是否添加或更改父对象的布尔值。例如，将
\nrequest.user附加到每一个改变了的表单集模型实例：\nclass ArticleAdmin(admin.ModelAdmin):\n def save_formset(self, request, form, formset, change):\n instances = formset.save(commit=False)\n for obj in formset.deleted_objects:\n obj.delete()\n for instance in instances:\n instance.user = request.user\n instance.save()\n formset.save_m2m()\n另见 在表单集中保存对象。
\n
- \n
- \nModelAdmin.get_ordering(request)Link to this definition# \n
\nget_ordering方法以request为参数，并期望返回一个类似于ordering属性的list或tuple的排序。例如：\nclass PersonAdmin(admin.ModelAdmin):\n\n def get_ordering(self, request):\n if request.user.is_superuser:\n return ['name', 'rank']\n else:\n return ['name']\n
- \n
- \nModelAdmin.get_search_results(request, queryset, search_term)Link to this definition# \n
\nget_search_results方法将显示的对象列表修改为符合所提供的搜索词的对象。它接受请求、应用当前过滤器的查询集和用户提供的搜索词。它返回一个元组，其中包含一个修改后实现搜索的查询集，以及一个布尔值，表示结果是否包含重复。默认的实现是搜索
\nModelAdmin.search_fields中命名的字段。这个方法可以用你自己的自定义搜索方法来覆盖。例如，你可能希望通过一个整数字段进行搜索，或使用外部工具，如 Solr 或 Haystack。你必须确定由你的搜索方法实现的查询集变化是否会在结果中引入重复，并在返回值的第二个元素中返回
\nTrue。例如，如果要按
\nname和age进行搜索，你可以使用：\nclass PersonAdmin(admin.ModelAdmin):\n list_display = ('name', 'age')\n search_fields = ('name',)\n\n def get_search_results(self, request, queryset, search_term):\n queryset, may_have_duplicates = super().get_search_results(\n request, queryset, search_term,\n )\n try:\n search_term_as_int = int(search_term)\n except ValueError:\n pass\n else:\n queryset |= self.model.objects.filter(age=search_term_as_int)\n return queryset, may_have_duplicates\n这个实现比
\nsearch_fields = ('name', '=age')更有效，因为后者的结果是对数字字段进行字符串比较，例如... OR UPPER("polls_choice"."votes"::text) = UPPER('4')在 PostgreSQL 上。
- \n\n
\nsave_related方法被赋予HttpRequest、父ModelForm实例、内联表单集列表和一个基于父对象是否被添加或更改的布尔值。在这里可以对父对象相关的对象进行任何保存前或保存后的操作。请注意，此时父对象及其窗体已经被保存。
- \n
- \nModelAdmin.get_autocomplete_fields(request)Link to this definition# \n
\nget_autocomplete_fields()方法被赋予HttpRequest，预计将返回一个list或tuple字段名，这些字段名将与自动完成部件一起显示，如上面ModelAdmin.autocomplete_fields部分所述。
- \n
- \nModelAdmin.get_readonly_fields(request, obj=None)Link to this definition# \n
\nget_readonly_fields方法是给定HttpRequest和被编辑的obj``（或者在添加表单中给定 ``None），并期望返回一个list或tuple的字段名，这些字段名将被显示为只读，如上面ModelAdmin.readonly_fields部分所述。
- \n
- \nModelAdmin.get_prepopulated_fields(request, obj=None)Link to this definition# \n
\nget_prepopulated_fields方法是给定HttpRequest和被编辑的obj（或者在添加表单中给定None），并期望返回一个dictionary，如上面ModelAdmin.prepopulated_fields一节所述。
- \n
- \nModelAdmin.get_list_display(request)Link to this definition# \n
\nget_list_display方法被赋予HttpRequest，预计将返回一个list或tuple的字段名，这些字段名将显示在变更列表视图上，如上面ModelAdmin.list_display一节所述。
- \n
- \nModelAdmin.get_list_display_links(request, list_display)Link to this definition# \n
\nget_list_display_links方法被赋予HttpRequest和由ModelAdmin.get_list_display()返回的list或tuple。如ModelAdmin.list_display_links一节所述，预计它将返回变化列表中的None或list或tuple字段名，这些字段名将被链接到变化视图。
- \n
- \nModelAdmin.get_exclude(request, obj=None)Link to this definition# \n
\nget_exclude方法是给定HttpRequest和被编辑的obj（或者在添加表单中给定None），并期望返回一个字段列表，如ModelAdmin.exclude中所述。
- \n
- \nModelAdmin.get_fields(request, obj=None)Link to this definition# \n
\nget_fields方法是给定HttpRequest和被编辑的obj（或者在添加表单中给定None），并期望返回一个字段列表，如上面ModelAdmin.fields一节所述。
- \n
- \nModelAdmin.get_fieldsets(request, obj=None)Link to this definition# \n
\nget_fieldsets方法是给定HttpRequest和被编辑的obj（或者在添加表单中给定None），预计将返回一个双元组列表，其中每个双元组代表管理表单页面上的<fieldset>，如上面ModelAdmin.fieldsets部分所述。
- \n
- \nModelAdmin.get_list_filter(request)Link to this definition# \n
\nget_list_filter方法被赋予HttpRequest，并期望返回与list_filter属性相同的序列类型。
- \n\n
\nget_list_select_related方法被赋予HttpRequest，应该像ModelAdmin.list_select_related那样返回一个布尔值或列表。
- \n
- \nModelAdmin.get_search_fields(request)Link to this definition# \n
\nget_search_fields方法被赋予HttpRequest，并期望返回与search_fields属性相同的序列类型。
- \n
- \nModelAdmin.get_sortable_by(request)Link to this definition# \n
\nget_sortable_by()方法被传递给HttpRequest，并期望返回一个字段名的集合（例如list、tuple或set），这些字段名将在更改列表页中被排序。如果设置了，它的默认实现将返回
\nsortable_by，否则将服从get_list_display()。例如，要防止一列或多列无法排序：
\n\nclass PersonAdmin(admin.ModelAdmin):\n\n def get_sortable_by(self, request):\n return {*self.get_list_display(request)} - {'rank'}\n
- \n
- \nModelAdmin.get_inline_instances(request, obj=None)Link to this definition# \n
\nget_inline_instances方法是给定HttpRequest和被编辑的obj（或者在添加表单中给定None），并期望返回一个list或tuple的 :class:``~django.contrib.admin.InlineModelAdmin` 对象，如下文InlineModelAdmin部分所述。例如，以下内容将返回没有基于添加、更改、删除和查看权限的默认过滤的内联：\nclass MyModelAdmin(admin.ModelAdmin):\n inlines = (MyInline,)\n\n def get_inline_instances(self, request, obj=None):\n return [inline(self.model, self.admin_site) for inline in self.inlines]\n如果你覆盖了这个方法，请确保返回的内联是
\ninlines中定义的类的实例，否则在添加相关对象时可能会遇到 “Bad Request” 错误。
- \n
- \nModelAdmin.get_inlines(request, obj)Link to this definition# \n
\nget_inlines方法是给定HttpRequest和被编辑的obj（或在添加表单中给定None），并期望返回一个可迭代对象的内联。你可以覆盖这个方法，根据请求或模型实例动态添加内联，而不是在ModelAdmin.inlines中指定它们。
- \n
- \nModelAdmin.get_urls()Link to this definition# \n
\nModelAdmin上的get_urls方法以与 URLconf 相同的方式返回用于该 ModelAdmin 的 URL。 因此，你可以按照 URL调度器 中的文档来扩展它们：\nfrom django.contrib import admin\nfrom django.template.response import TemplateResponse\nfrom django.urls import path\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_urls(self):\n urls = super().get_urls()\n my_urls = [\n path('my_view/', self.my_view),\n ]\n return my_urls + urls\n\n def my_view(self, request):\n # ...\n context = dict(\n # Include common variables for rendering the admin template.\n self.admin_site.each_context(request),\n # Anything else you want in the context...\n key=value,\n )\n return TemplateResponse(request, "sometemplate.html", context)\n如果你想使用管理布局，从
\nadmin/base_site.html扩展：\n\n{% extends "admin/base_site.html" %}\n{% block content %}\n...\n{% endblock %}\n然而，上面注册的
\nself.my_view函数存在两个问题：- \n
它将 不 进行任何权限检查，所以它将对普通公众开放。
\n它将 不 提供任何头信息以防止缓存。这意味着如果页面从数据库中检索数据，而缓存中间件是活动的，页面可能会显示过时的信息。
\n
由于这通常不是你想要的，Django 提供了一个方便的包装器来检查权限并将视图标记为不可缓存。这个封装器是
\nAdminSite.admin_view()（即self.admin_site.admin_view在一个ModelAdmin实例中）；使用它就像这样：\nclass MyModelAdmin(admin.ModelAdmin):\n def get_urls(self):\n urls = super().get_urls()\n my_urls = [\n path('my_view/', self.admin_site.admin_view(self.my_view))\n ]\n return my_urls + urls\n请注意上面第五行的包装的视图：
\n\npath('my_view/', self.admin_site.admin_view(self.my_view))\n这个封装将保护
\nself.my_view不被未经授权的访问，并将应用django.views.decorators.cache.never_cache()装饰器来确保在缓存中间件处于活动状态时不被缓存。如果页面是可缓存的，但你仍然希望进行权限检查，你可以传递一个
\ncacheable=True参数到AdminSite.admin_view()：\npath('my_view/', self.admin_site.admin_view(self.my_view, cacheable=True))\n
\nModelAdmin视图有model_admin属性。其他AdminSite视图有admin_site属性。
- \n
- \nModelAdmin.get_form(request, obj=None, **kwargs)Link to this definition# \n
返回一个
\nModelForm类，用于管理员添加和更改视图，参见add_view()和change_view()。基本实现使用
\nmodelform_factory()来子类form，通过fields和exclude等属性进行修改。所以，例如，如果你想为超级用户提供额外的字段，你可以像这样换一个不同的基本表单：\nclass MyModelAdmin(admin.ModelAdmin):\n def get_form(self, request, obj=None, **kwargs):\n if request.user.is_superuser:\n kwargs['form'] = MySuperuserForm\n return super().get_form(request, obj, **kwargs)\n你也可以直接返回一个自定义的
\nModelForm类。
- \n
- \nModelAdmin.get_formsets_with_inlines(request, obj=None)Link to this definition# \n
产生 (
\nFormSet,InlineModelAdmin) 对，用于管理添加和更改视图。例如，如果你想只在变化视图中显示一个特定的内联，你可以覆盖
\nget_formsets_with_inlines如下：\nclass MyModelAdmin(admin.ModelAdmin):\n inlines = [MyInline, SomeOtherInline]\n\n def get_formsets_with_inlines(self, request, obj=None):\n for inline in self.get_inline_instances(request, obj):\n # hide MyInline in the add view\n if not isinstance(inline, MyInline) or obj is not None:\n yield inline.get_formset(request, obj), inline\n
- \n
- \nModelAdmin.formfield_for_foreignkey(db_field, request, **kwargs)Link to this definition# \n
\nModelAdmin上的formfield_for_foreignkey方法允许你覆盖外键字段的默认 formfield。例如，要根据用户返回这个外键字段的对象子集：\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_foreignkey(self, db_field, request, **kwargs):\n if db_field.name == "car":\n kwargs["queryset"] = Car.objects.filter(owner=request.user)\n return super().formfield_for_foreignkey(db_field, request, **kwargs)\n这使用
\nHttpRequest实例过滤Car外键字段，只显示User实例拥有的汽车。对于更复杂的过滤器，你可以使用
\nModelForm.__init__()方法来基于你的模型的instance进行过滤（参见 处理关系的字段）。例如：\nclass CountryAdminForm(forms.ModelForm):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.fields['capital'].queryset = self.instance.cities.all()\n\nclass CountryAdmin(admin.ModelAdmin):\n form = CountryAdminForm\n
- \n
- \nModelAdmin.formfield_for_manytomany(db_field, request, **kwargs)Link to this definition# \n
与
\nformfield_for_foreignkey方法一样，formfield_for_manytomany方法也可以被重写，以改变多对多字段的默认字段。例如，如果一个车主可以拥有多辆汽车，而汽车可以属于多个车主 —— 多对多关系 —— 你可以过滤Car外键字段，只显示User：\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_manytomany(self, db_field, request, **kwargs):\n if db_field.name == "cars":\n kwargs["queryset"] = Car.objects.filter(owner=request.user)\n return super().formfield_for_manytomany(db_field, request, **kwargs)\n
- \n
- \nModelAdmin.formfield_for_choice_field(db_field, request, **kwargs)Link to this definition# \n
与
\nformfield_for_foreignkey和formfield_for_manytomany方法一样，formfield_for_choice_field方法可以被重写，以改变已声明选择的字段的默认字段。例如，如果超级用户的选择与普通员工的选择不同，你可以按以下步骤进行：\n\nclass MyModelAdmin(admin.ModelAdmin):\n def formfield_for_choice_field(self, db_field, request, **kwargs):\n if db_field.name == "status":\n kwargs['choices'] = (\n ('accepted', 'Accepted'),\n ('denied', 'Denied'),\n )\n if request.user.is_superuser:\n kwargs['choices'] += (('ready', 'Ready for deployment'),)\n return super().formfield_for_choice_field(db_field, request, **kwargs)\n
- \n
- \nModelAdmin.get_changelist(request, **kwargs)Link to this definition# \n
返回用于列表的
\nChangelist类。默认情况下，使用的是django.contrib.admin.views.main.ChangeList。通过继承这个类，你可以改变列表的行为。
- \n
- \nModelAdmin.get_changelist_form(request, **kwargs)Link to this definition# \n
返回一个
\nModelForm类，供变更列表页面中的Formset使用。要使用一个自定义表单，例如：\n\nfrom django import forms\n\nclass MyForm(forms.ModelForm):\n pass\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_changelist_form(self, request, **kwargs):\n return MyForm\n
- \n
- \nModelAdmin.get_changelist_formset(request, **kwargs)Link to this definition# \n
如果使用了
\nlist_editable，则返回一个 ModelFormSet 类，供变更列表页面使用。要使用自定义表单集，例如：\nfrom django.forms import BaseModelFormSet\n\nclass MyAdminFormSet(BaseModelFormSet):\n pass\n\nclass MyModelAdmin(admin.ModelAdmin):\n def get_changelist_formset(self, request, **kwargs):\n kwargs['formset'] = MyAdminFormSet\n return super().get_changelist_formset(request, **kwargs)\n
- \n
- \nModelAdmin.lookup_allowed(lookup, value)Link to this definition# \n
变更列表页面中的对象可以通过 URL 的查询字符串进行过滤。例如
\nlist_filter就是这样工作的。这些查询类似于QuerySet.filter()（例如user__email=user@example.com）。由于用户可以对查询字符串中的查找进行操作，因此必须对它们进行处理，以防止未经授权的数据暴露。
\nlookup_allowed()方法从查询字符串（如'user__email'）和相应的值（如``'user@example.com'）中得到一个查找路径，并返回一个布尔值，表示是否允许使用参数过滤变更列表的 ``QuerySet。如果lookup_allowed()返回False，则会引发DisallowedModelAdminLookup（SuspiciousOperation的子类）。默认情况下，
\nlookup_allowed()允许访问模型的本地字段、在list_filter中使用的字段路径（但不包括get_list_filter()）中使用的字段路径，以及limit_choices_to在raw_id_fields中正确运行所需的查找。重写这个方法来定制你的
\nModelAdmin子类允许的查找。
- \n
- \nModelAdmin.has_view_permission(request, obj=None)Link to this definition# \n
如果允许查看
\nobj，应返回True，否则返回False。如果 obj 是None，应返回True或False表示是否允许查看该类型的对象（例如，False将被解释为当前用户不允许查看该类型的任何对象）。如果用户有 “更改” 或 “查看” 权限，默认的实现将返回
\nTrue。
- \n
- \nModelAdmin.has_add_permission(request)Link to this definition# \n
如果允许添加对象，应返回
\nTrue，否则返回False。
- \n
- \nModelAdmin.has_change_permission(request, obj=None)Link to this definition# \n
如果允许编辑
\nobj，应返回True，否则应返回False。如果obj是None，应返回True或False表示是否允许编辑该类型对象（例如，False将被解释为当前用户不允许编辑该类型的任何对象）。
- \n
- \nModelAdmin.has_delete_permission(request, obj=None)Link to this definition# \n
如果允许删除
\nobj，应返回True，否则返回False。如果obj是None，应返回True或False，以表明是否允许删除该类型的对象（例如，False将被解释为当前用户不允许删除该类型的任何对象）。
- \n
- \nModelAdmin.has_module_permission(request)Link to this definition# \n
如果允许在管理员索引页上显示模块和访问模块的索引页，应该返回
\nTrue，否则返回False。默认使用User.has_module_perms()。覆盖它并不限制对视图的访问，添加、更改或删除视图，has_view_permission()、has_add_permission()、has_change_permission()和has_delete_permission()应该用于此。
- \n
- \nModelAdmin.get_queryset(request)Link to this definition# \n
\nModelAdmin上的get_queryset方法返回一个QuerySet的所有模型实例，这些实例可以被管理网站编辑。覆盖该方法的一个用例是显示登录用户拥有的对象：\nclass MyModelAdmin(admin.ModelAdmin):\n def get_queryset(self, request):\n qs = super().get_queryset(request)\n if request.user.is_superuser:\n return qs\n return qs.filter(author=request.user)\n
- \n
- \nModelAdmin.message_user(request, message, level=messages.INFO, extra_tags='', fail_silently=False)Link to this definition# \n
使用
\ndjango.contrib.messages后台向用户发送消息。 参见 自定义 ModelAdmin 示例。关键字参数允许你改变消息的级别，添加额外的 CSS 标签，或者在没有安装
\ncontrib.messages框架的情况下无声地失败。这些关键字参数与django.contrib.messages.add_message()的参数一致，更多细节请参见该函数的文档。一个不同的地方是，除了整数／常量之外，级别还可以作为字符串标签传递。
- \n
- \nModelAdmin.get_paginator(request, queryset, per_page, orphans=0, allow_empty_first_page=True)Link to this definition# \n
返回要用于该视图的分页器实例。默认情况下，实例化一个
\npaginator的实例。
- \n
- \nModelAdmin.response_add(request, obj, post_url_continue=None)Link to this definition# \n
确定
\nadd_view()阶段的HttpResponse。
\nresponse_add在提交管理表单后，对象和所有相关实例被创建和保存后被调用。你可以覆盖它来改变对象创建后的默认行为。
- \n
- \nModelAdmin.response_change(request, obj)Link to this definition# \n
确定
\nchange_view()阶段的HttpResponse。
\nresponse_change在管理表单提交后，对象和所有相关实例被保存后被调用。你可以覆盖它来改变对象被改变后的默认行为。
- \n
- \nModelAdmin.response_delete(request, obj_display, obj_id)Link to this definition# \n
为
\ndelete_view()阶段确定HttpResponse。
\nresponse_delete在对象被删除后被调用。你可以覆盖它来改变对象被删除后的默认行为。
\nobj_display是删除对象名称的字符串。
\nobj_id是用于检索要删除的对象的序列化标识符。
- \n
- \nModelAdmin.get_changeform_initial_data(request)Link to this definition# \n
一个钩子，用于管理更改表格的初始数据。默认情况下，字段的初始值来自
\nGET参数。例如，?name=initial_value将把name字段的初始值设置为initial_value。这个方法应该返回一个形式为
\n{'fieldname': 'fieldval'}的字典：\ndef get_changeform_initial_data(self, request):\n return {'name': 'custom_initial_value'}\n
- \n
- \nModelAdmin.get_deleted_objects(objs, request)Link to this definition# \n
一个钩子，用于自定义
\ndelete_view()和 “删除已选” 动作 的删除过程。
\nobjs参数是要删除的对象（一个QuerySet或模型实例列表）的等价可迭代对象，request是HttpRequest。这个方法必须返回一个四元元组
\n(delete_objects, model_count, perms_needed, protected)。
\ndeleted_objects是一个代表所有将被删除对象的字符串列表。如果有任何相关的对象要删除，则列表是嵌套的，包括这些相关对象。该列表在模板中使用unordered_list过滤器进行格式化。
\nmodel_count是一个将每个模型的verbose_name_plural映射到将被删除的对象数量的字典。
\nperms_needed是一组verbose_name的用户没有权限删除的模型。
\nprotected是一个字符串列表，代表所有不能删除的受保护相关对象。该列表显示在模板中。
其他方法Link to this heading#
\n- \n
- \nModelAdmin.add_view(request, form_url='', extra_context=None)Link to this definition# \n
模型实例添加页面的 Django 视图。见下面的说明。
\n
- \n
- \nModelAdmin.change_view(request, object_id, form_url='', extra_context=None)Link to this definition# \n
模型实例编辑页面的 Django 视图。见下面的说明。
\n
- \n
- \nModelAdmin.changelist_view(request, extra_context=None)Link to this definition# \n
模型实例变更列表／动作页面的 Django 视图。见下面的说明。
\n
- \n
- \nModelAdmin.delete_view(request, object_id, extra_context=None)Link to this definition# \n
模型实例删除确认页面的 Django 视图。参见下面的说明。
\n
- \n
- \nModelAdmin.history_view(request, object_id, extra_context=None)Link to this definition# \n
Django 视图用于显示给定模型实例的修改历史的页面。
\n
与上一节中详细介绍的钩子类型的 ModelAdmin 方法不同，这五个方法实际上是被设计成作为 Django 视图从管理应用的 URL 调度处理程序中调用，以渲染处理模型实例 CRUD 操作的页面。因此，完全覆盖这些方法将显著改变管理员应用程序的行为。
覆盖这些方法的一个常见原因是为了增强提供给渲染视图的模板的上下文数据。在下面的例子中，更改视图被覆盖，以便为渲染模板提供一些额外的映射数据，否则这些数据将无法使用：
\nclass MyModelAdmin(admin.ModelAdmin):\n\n # A template for a very customized change view:\n change_form_template = 'admin/myapp/extras/openstreetmap_change_form.html'\n\n def get_osm_info(self):\n # ...\n pass\n\n def change_view(self, request, object_id, form_url='', extra_context=None):\n extra_context = extra_context or {}\n extra_context['osm_data'] = self.get_osm_info()\n return super().change_view(\n request, object_id, form_url, extra_context=extra_context,\n )\n这些视图返回 TemplateResponse 实例，允许你在渲染前轻松定制响应数据。更多细节，请看 TemplateResponse 文档。
ModelAdmin 静态资源定义Link to this heading#
\n有时你会想在添加／更改视图时添加一点 CSS 和／或 JavaScript。这可以通过在你的 ModelAdmin 上使用 Media 内类来实现：
class ArticleAdmin(admin.ModelAdmin):\n class Media:\n css = {\n "all": ("my_styles.css",)\n }\n js = ("my_code.js",)\nstaticfiles app 将 STATIC_URL （如果 STATIC_URL 是 None，则 MEDIA_URL）预先加入任何资产路径。同样的规则适用于:ref:表单上定义的静态资源 <form-asset-paths>。
jQueryLink to this heading#
\nDjango 管理 JavaScript 使用了 jQuery 库。
\n为了避免与用户提供的脚本或库发生冲突，Django 的 jQuery（3.5.1 版）被命名为 django.jQuery。如果你想在自己的管理 JavaScript 中使用 jQuery，而不需要包含第二个副本，你可以在变更列表和添加／删除视图中使用 django.jQuery 对象。另外，你自己的管理表单或部件依赖 django.jQuery 必须在 声明表单媒体资产 时指定 js=['admin/js/jquery.init.js', ...]。
ModelAdmin 类默认需要 jQuery，所以除非你有特殊需要，否则不需要将 jQuery 添加到你的 ModelAdmin 的媒体资源列表中。例如，如果你要求 jQuery 库在全局命名空间中（例如在使用第三方 jQuery 插件时），或者你需要一个较新版本的 jQuery，你将不得不包含自己的副本。
Django 提供了 jQuery 的非压缩和 “最小化” 版本，分别为 jquery.js 和 jquery.min.js。
ModelAdmin 和 InlineModelAdmin 有一个 media 属性，它返回一个 Media 对象的列表，其中存储了表单和／或表单集的 JavaScript 文件的路径。如果 DEBUG 是 True，它将返回各种 JavaScript 文件的未压缩版本，包括 jquery.js；如果不是，它将返回 “最小化” 版本。
在管理中添加自定义验证Link to this heading#
\n你也可以在管理中添加自定义的数据验证。自动管理界面重用 django.forms，ModelAdmin 类让你能够定义你自己的表单：
class ArticleAdmin(admin.ModelAdmin):\n form = MyArticleAdminForm\nMyArticleAdminForm 可以在任何地方定义，只要你在需要的地方导入。现在，在你的表单中，你可以为任何字段添加自己的自定义验证：
class MyArticleAdminForm(forms.ModelForm):\n def clean_name(self):\n # do something that validates your data\n return self.cleaned_data["name"]\n在这里使用 ModelForm 是很重要的，否则可能会出问题。更多信息请参见 表单 文档中的 自定义验证器 和 验证器返回的模型注解。