The Django admin site

The Django admin site

One of the most powerful parts of Django is the automatic admin interface. Itreads metadata from your models to provide a quick, model-centric interfacewhere trusted users can manage content on your site. The admin's recommendeduse is limited to an organization's internal management tool. It's not intendedfor building your entire front end around.

The admin has many hooks for customization, but beware of trying to use thosehooks exclusively. If you need to provide a more process-centric interfacethat abstracts away the implementation details of database tables and fields,then it's probably time to write your own views.

In this document we discuss how to activate, use, and customize Django's admininterface.

Overview

The admin is enabled in the default project template used bystartproject.

If you're not using the default project template, here are the requirements:

Add 'django.contrib.admin' and its dependencies -django.contrib.auth, django.contrib.contenttypes,django.contrib.messages, and django.contrib.sessions - to yourINSTALLED_APPS setting.
Configure a DjangoTemplatesbackend in your TEMPLATES setting withdjango.contrib.auth.context_processors.auth anddjango.contrib.messages.context_processors.messages inthe 'context_processors' option of OPTIONS.
If you've customized the MIDDLEWARE setting,django.contrib.auth.middleware.AuthenticationMiddleware anddjango.contrib.messages.middleware.MessageMiddleware must beincluded.
Hook the admin's URLs into your URLconf.
After you've taken these steps, you'll be able to use the admin site byvisiting the URL you hooked it into (/admin/, by default).

If you need to create a user to login with, use the createsuperusercommand. By default, logging in to the admin requires that the user has theis_superuser or is_staff attribute set toTrue.

Finally, determine which of your application's models should be editable in theadmin interface. For each of those models, register them with the admin asdescribed in ModelAdmin.

ModelAdmin objects

class ModelAdmin[源代码]
The ModelAdmin class is the representation of a model in the admininterface. Usually, these are stored in a file named admin.py in yourapplication. Let's take a look at a very simple example ofthe ModelAdmin:

from django.contrib import admin
from myproject.myapp.models import Author
 
class AuthorAdmin(admin.ModelAdmin):
    pass
admin.site.register(Author, AuthorAdmin)

Do you need a ModelAdmin object at all?

In the preceding example, the ModelAdmin class doesn't define anycustom values (yet). As a result, the default admin interface will beprovided. If you are happy with the default admin interface, you don'tneed to define a ModelAdmin object at all — you can register themodel class without providing a ModelAdmin description. Thepreceding example could be simplified to:

from django.contrib import admin
from myproject.myapp.models import Author
 
admin.site.register(Author)

The register decorator

register(*models, site=django.admin.sites.site)[源代码]
There is also a decorator for registering your ModelAdmin classes:

from django.contrib import admin
from .models import Author
 
@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    pass

It's given one or more model classes to register with the ModelAdmin.If you're using a custom AdminSite, pass it using the site keywordargument:

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

You can't use this decorator if you have to reference your model adminclass in its init() method, e.g.super(PersonAdmin, self).init(args, **kwargs). You can usesuper().init(args, **kwargs).

Discovery of admin files

When you put 'django.contrib.admin' in your INSTALLED_APPSsetting, Django automatically looks for an admin module in eachapplication and imports it.

class apps.AdminConfig
This is the default AppConfig class for the admin.It calls autodiscover() when Django starts.
class apps.SimpleAdminConfig
This class works like AdminConfig,except it doesn't call autodiscover().
- default_site
- New in Django 2.1:

A dotted import path to the default admin site's class or to a callablethat returns a site instance. Defaults to'django.contrib.admin.sites.AdminSite'. SeeOverriding the default admin site for usage.

autodiscover()[源代码]
This function attempts to import an admin module in each installedapplication. Such modules are expected to register models with the admin.

Typically you won't need to call this function directly asAdminConfig calls it when Django starts.

If you are using a custom AdminSite, it is common to import all of theModelAdmin subclasses into your code and register them to the customAdminSite. In that case, in order to disable auto-discovery, you shouldput 'django.contrib.admin.apps.SimpleAdminConfig' instead of'django.contrib.admin' in your INSTALLED_APPS setting.

ModelAdmin options

The ModelAdmin is very flexible. It has several options for dealing withcustomizing the interface. All options are defined on the ModelAdminsubclass:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    date_hierarchy = 'pub_date'

ModelAdmin.actions
A list of actions to make available on the change list page. SeeAdmin actions for details.
ModelAdmin.actions_on_top
ModelAdmin.actions_on_bottom
Controls where on the page the actions bar appears. By default, the adminchangelist displays actions at the top of the page (actions_on_top = True; actions_on_bottom = False).
ModelAdmin.actions_selection_counter
Controls whether a selection counter is displayed next to the action dropdown.By default, the admin changelist will display it(actions_selection_counter = True).
ModelAdmin.date_hierarchy
Set date_hierarchy to the name of a DateField or DateTimeFieldin your model, and the change list page will include a date-based drilldownnavigation by that field.

Example:

date_hierarchy = 'pub_date'

You can also specify a field on a related model using the __ lookup,for example:

date_hierarchy = 'author__pub_date'

This will intelligently populate itself based on available data,e.g. if all the dates are in one month, it'll show the day-leveldrill-down only.

注解

date_hierarchy uses QuerySet.datetimes() internally. Please referto its documentation for some caveats when time zone support isenabled (USE_TZ = True).

ModelAdmin.empty_value_display
This attribute overrides the default display value for record's fields thatare empty (None, empty string, etc.). The default value is - (adash). For example:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    empty_value_display = '-empty-'

You can also override empty_value_display for all admin pages withAdminSite.empty_value_display, or for specific fields like this:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    fields = ('name', 'title', 'view_birth_date')
 
    def view_birth_date(self, obj):
        return obj.birth_date
 
    view_birth_date.empty_value_display = '???'

ModelAdmin.exclude
This attribute, if given, should be a list of field names to exclude fromthe form.

For example, let's consider the following model:

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)

If you want a form for the Author model that includes only the nameand title fields, you would specify fields or exclude likethis:

from django.contrib import admin
 
class AuthorAdmin(admin.ModelAdmin):
    fields = ('name', 'title')
 
class AuthorAdmin(admin.ModelAdmin):
    exclude = ('birth_date',)

Since the Author model only has three fields, name, title, andbirth_date, the forms resulting from the above declarations willcontain exactly the same fields.

ModelAdmin.fields
Use the fields option to make simple layout changes in the forms onthe "add" and "change" pages such as showing only a subset of availablefields, modifying their order, or grouping them into rows. For example, youcould define a simpler version of the admin form for thedjango.contrib.flatpages.models.FlatPage model as follows:

class FlatPageAdmin(admin.ModelAdmin):
    fields = ('url', 'title', 'content')

In the above example, only the fields url, title and contentwill be displayed, sequentially, in the form. fields can containvalues defined in ModelAdmin.readonly_fields to be displayed asread-only.

For more complex layout needs, see the fieldsets option.

The fields option accepts the same types of values aslist_display, except that callables aren't accepted.Names of model and model admin methods will only be used if they're listedin readonly_fields.

To display multiple fields on the same line, wrap those fields in their owntuple. In this example, the url and title fields will display on thesame line and the content field will be displayed below them on itsown line:

class FlatPageAdmin(admin.ModelAdmin):
    fields = (('url', 'title'), 'content')

Note

This fields option should not be confused with the fieldsdictionary key that is within the fieldsets option,as described in the next section.

If neither fields nor fieldsets options are present,Django will default to displaying each field that isn't an AutoField andhas editable=True, in a single fieldset, in the same order as the fieldsare defined in the model.

ModelAdmin.fieldsets
Set fieldsets to control the layout of admin "add" and "change" pages.

fieldsets is a list of two-tuples, in which each two-tuple represents a<fieldset> on the admin form page. (A <fieldset> is a "section" ofthe form.)

The two-tuples are in the format (name, field_options), where nameis a string representing the title of the fieldset and field_options isa dictionary of information about the fieldset, including a list of fieldsto be displayed in it.

A full example, taken from thedjango.contrib.flatpages.models.FlatPage model:

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'),
        }),
    )

This results in an admin page that looks like:

If neither fieldsets nor fields options are present,Django will default to displaying each field that isn't an AutoField andhas editable=True, in a single fieldset, in the same order as the fieldsare defined in the model.

The field_options dictionary can have the following keys:

- fields
- A tuple of field names to display in this fieldset. This key isrequired.

Example:

{
'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
}

As with the fields option, to display multiplefields on the same line, wrap those fields in their own tuple. In thisexample, the first_name and last_name fields will display onthe same line:

{
'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
}

fields can contain values defined inreadonly_fields to be displayed as read-only.

If you add the name of a callable to fields, the same rule appliesas with the fields option: the callable must belisted in readonly_fields.

- classes
- A list or tuple containing extra CSS classes to apply to the fieldset.

Example:

{
'classes': ('wide', 'extrapretty'),
}

Two useful classes defined by the default admin site stylesheet arecollapse and wide. Fieldsets with the collapse stylewill be initially collapsed in the admin and replaced with a small"click to expand" link. Fieldsets with the wide style will begiven extra horizontal space.

- description
- A string of optional extra text to be displayed at the top of eachfieldset, under the heading of the fieldset. This string is notrendered for TabularInline due to itslayout.

Note that this value is not HTML-escaped when it's displayed inthe admin interface. This lets you include HTML if you so desire.Alternatively you can use plain text anddjango.utils.html.escape() to escape any HTML specialcharacters.

ModelAdmin.filter_horizontal
By default, a ManyToManyField is displayed inthe admin site with a <select multiple>. However, multiple-select boxescan be difficult to use when selecting many items. Adding aManyToManyField to this list will instead usea nifty unobtrusive JavaScript "filter" interface that allows searchingwithin the options. The unselected and selected options appear in two boxesside by side. See filter_vertical to use a verticalinterface.
ModelAdmin.filter_vertical
Same as filter_horizontal, but uses a vertical displayof the filter interface with the box of unselected options appearing abovethe box of selected options.
ModelAdmin.form
By default a ModelForm is dynamically created for your model. It isused to create the form presented on both the add/change pages. You caneasily provide your own ModelForm to override any default form behavioron the add/change pages. Alternatively, you can customize the defaultform rather than specifying an entirely new one by using theModelAdmin.get_form() method.

For an example see the section Adding custom validation to the admin.

Note

If you define the Meta.model attribute on aModelForm, you must also define theMeta.fields attribute (or the Meta.exclude attribute). However,since the admin has its own way of defining fields, the Meta.fieldsattribute will be ignored.

If the ModelForm is only going to be used for the admin, the easiestsolution is to omit the Meta.model attribute, since ModelAdminwill provide the correct model to use. Alternatively, you can setfields = [] in the Meta class to satisfy the validation on theModelForm.

Note

If your ModelForm and ModelAdmin both define an excludeoption then ModelAdmin takes precedence:

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

In the above example, the "age" field will be excluded but the "name"field will be included in the generated form.

ModelAdmin.formfield_overrides
This provides a quick-and-dirty way to override some of theField options for use in the admin.formfield_overrides is a dictionary mapping a field class to a dict ofarguments to pass to the field at construction time.

Since that's a bit abstract, let's look at a concrete example. The mostcommon use of formfield_overrides is to add a custom widget for acertain type of field. So, imagine we've written a RichTextEditorWidgetthat we'd like to use for large text fields instead of the default<textarea>. Here's how we'd do that:

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},
    }

Note that the key in the dictionary is the actual field class, not astring. The value is another dictionary; these arguments will be passed tothe form field's init() method. See The Forms API fordetails.

警告

If you want to use a custom widget with a relation field (i.e.ForeignKey orManyToManyField), make sure you haven'tincluded that field's name in raw_id_fields, radio_fields, orautocomplete_fields.

formfield_overrides won't let you change the widget on relationfields that have raw_id_fields, radio_fields, orautocomplete_fields set. That's because raw_id_fields,radio_fields, and autocomplete_fields imply custom widgets oftheir own.

ModelAdmin.inlines
See InlineModelAdmin objects below as well asModelAdmin.get_formsets_with_inlines().
ModelAdmin.list_display
Set list_display to control which fields are displayed on the changelist page of the admin.

Example:

list_display = ('first_name', 'last_name')

If you don't set listdisplay, the admin site will display a singlecolumn that displays the _str() representation of each object.

There are four types of values that can be used in list_display:

The name of a model field. For example:

class PersonAdmin(admin.ModelAdmin):
    list_display = ('first_name', 'last_name')

A callable that accepts one argument, the model instance. For example:

def upper_case_name(obj):
    return ("%s %s" % (obj.first_name, obj.last_name)).upper()
upper_case_name.short_description = 'Name'
 
class PersonAdmin(admin.ModelAdmin):
    list_display = (upper_case_name,)

A string representing a ModelAdmin method that accepts one argument,the model instance. For example:

class PersonAdmin(admin.ModelAdmin):
    list_display = ('upper_case_name',)
 
    def upper_case_name(self, obj):
        return ("%s %s" % (obj.first_name, obj.last_name)).upper()
    upper_case_name.short_description = 'Name'

A string representing a model attribute or method (without any requiredarguments). For example:

from django.contrib import admin
from django.db import models
 
class Person(models.Model):
    name = models.CharField(max_length=50)
    birthday = models.DateField()
 
    def decade_born_in(self):
        return self.birthday.strftime('%Y')[:3] + "0's"
    decade_born_in.short_description = 'Birth decade'
 
class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'decade_born_in')

A few special cases to note about list_display:

If the field is a ForeignKey, Django will display thestr() of the related object.
ManyToManyField fields aren't supported, because that wouldentail executing a separate SQL statement for each row in the table.If you want to do this nonetheless, give your model a custom method,and add that method's name to list_display. (See below for moreon custom methods in list_display.)
If the field is a BooleanField, Django will display a pretty "on" or"off" icon instead of True or False.
If the string given is a method of the model, ModelAdmin or acallable, Django will HTML-escape the output by default. To escapeuser input and allow your own unescaped tags, useformat_html().

Here's a full example model:

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)
 
    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')

As some examples have already demonstrated, when using a callable, amodel method, or a ModelAdmin method, you can customize the column'stitle by adding a short_description attribute to the callable.
If the value of a field is None, an empty string, or an iterablewithout elements, Django will display - (a dash). You can overridethis with AdminSite.empty_value_display:

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

You can also use ModelAdmin.empty_value_display:

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

Or on a field level:

class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'birth_date_view')
 
    def birth_date_view(self, obj):
         return obj.birth_date
 
    birth_date_view.empty_value_display = 'unknown'

If the string given is a method of the model, ModelAdmin or acallable that returns True or False Django will display a pretty"on" or "off" icon if you give the method a boolean attributewhose value is True.

Here's a full example model:

from django.contrib import admin
from django.db import models
 
class Person(models.Model):
    first_name = models.CharField(max_length=50)
    birthday = models.DateField()
 
    def born_in_fifties(self):
        return self.birthday.strftime('%Y')[:3] == '195'
    born_in_fifties.boolean = True
 
class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'born_in_fifties')

The str() method is just as valid in list_display as anyother model method, so it's perfectly OK to do this:

list_display = ('__str__', 'some_other_field')

Usually, elements of list_display that aren't actual databasefields can't be used in sorting (because Django does all the sortingat the database level).

However, if an element of list_display represents a certaindatabase field, you can indicate this fact by setting theadmin_order_field attribute of the item.

For example:

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)
 
    def colored_first_name(self):
        return format_html(
            '<span style="color: #{};">{}</span>',
            self.color_code,
            self.first_name,
        )
 
    colored_first_name.admin_order_field = 'first_name'
 
class PersonAdmin(admin.ModelAdmin):
    list_display = ('first_name', 'colored_first_name')

The above will tell Django to order by the first_name field whentrying to sort by colored_first_name in the admin.

To indicate descending order with admin_order_field you can use ahyphen prefix on the field name. Using the above example, this wouldlook like:

colored_first_name.admin_order_field = '-first_name'

admin_order_field supports query lookups to sort by values on relatedmodels. This example includes an "author first name" column in the listdisplay and allows sorting it by first name:

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')
 
    def author_first_name(self, obj):
        return obj.author.first_name
 
    author_first_name.admin_order_field = 'author__first_name'

Query expressions may be used inadmin_order_field. For example:

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)
 
    def full_name(self):
        return self.first_name + ' ' + self.last_name
    full_name.admin_order_field = Concat('first_name', Value(' '), 'last_name')

New in Django 2.1:
Support for expressions in admin_order_field was added.

Elements of list_display can also be properties. Please note however,that due to the way properties work in Python, settingshort_description on a property is only possible when using theproperty() function and not with the @property decorator.

For example:

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
 
    def my_property(self):
        return self.first_name + ' ' + self.last_name
    my_property.short_description = "Full name of the person"
 
    full_name = property(my_property)
 
class PersonAdmin(admin.ModelAdmin):
    list_display = ('full_name',)

The field names in list_display will also appear as CSS classes inthe HTML output, in the form of column-<field_name> on each <th>element. This can be used to set column widths in a CSS file for example.
Django will try to interpret every element of list_display in thisorder:
- A field of the model.
- A callable.
- A string representing a ModelAdmin attribute.
- A string representing a model attribute.
  For example if you have first_name as a model field andas a ModelAdmin attribute, the model field will be used.

ModelAdmin.list_display_links
Use list_display_links to control if and which fields inlist_display should be linked to the "change" page for an object.

By default, the change list page will link the first column — the firstfield specified in list_display — to the change page for each item.But list_display_links lets you change this:

Set it to None to get no links at all.
Set it to a list or tuple of fields (in the same format aslist_display) whose columns you want converted to links.

You can specify one or many fields. As long as the fields appear inlist_display, Django doesn't care how many (or how few) fields arelinked. The only requirement is that if you want to uselist_display_links in this fashion, you must define list_display.

In this example, the first_name and last_name fields will belinked on the change list page:

class PersonAdmin(admin.ModelAdmin):
    list_display = ('first_name', 'last_name', 'birthday')
    list_display_links = ('first_name', 'last_name')

In this example, the change list page grid will have no links:

class AuditEntryAdmin(admin.ModelAdmin):
    list_display = ('timestamp', 'message')
    list_display_links = None

ModelAdmin.list_editable
Set list_editable to a list of field names on the model which willallow editing on the change list page. That is, fields listed inlist_editable will be displayed as form widgets on the change listpage, allowing users to edit and save multiple rows at once.

注解

list_editable interacts with a couple of other options inparticular ways; you should note the following rules:

Any field in list_editable must also be in list_display.You can't edit a field that's not displayed!
The same field can't be listed in both list_editable andlist_display_links — a field can't be both a form anda link.
You'll get a validation error if either of these rules are broken.

ModelAdmin.list_filter
Set list_filter to activate filters in the right sidebar of the changelist page of the admin, as illustrated in the following screenshot:

list_filter should be a list or tuple of elements, where each elementshould be of one of the following types:
- a field name, where the specified field should be either aBooleanField, CharField, DateField, DateTimeField,IntegerField, ForeignKey or ManyToManyField, for example:

class PersonAdmin(admin.ModelAdmin):
    list_filter = ('is_staff', 'company')

Field names in listfilter can also span relationsusing the _ lookup, for example:

class PersonAdmin(admin.UserAdmin):
    list_filter = ('company__name',)

a class inheriting from django.contrib.admin.SimpleListFilter,which you need to provide the title and parameter_nameattributes to and override the lookups and queryset methods,e.g.:

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,)

注解

As a convenience, the HttpRequest object is passed to thelookups and queryset methods, for example:

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)

Also as a convenience, the ModelAdmin object is passed tothe lookups method, for example if you want to base thelookups on the available data:

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'))

a tuple, where the first element is a field name and the secondelement is a class inheriting fromdjango.contrib.admin.FieldListFilter, for example:

class PersonAdmin(admin.ModelAdmin):
    list_filter = (
        ('is_staff', admin.BooleanFieldListFilter),
    )

You can limit the choices of a related model to the objects involved inthat relation using RelatedOnlyFieldListFilter:

class BookAdmin(admin.ModelAdmin):
    list_filter = (
        ('author', admin.RelatedOnlyFieldListFilter),
    )

Assuming author is a ForeignKey to a User model, this willlimit the list_filter choices to the users who have written a bookinstead of listing all users.

注解

The FieldListFilter API is considered internal and might bechanged.

List filter's typically appear only if the filter has more than one choice.A filter's has_output() method controls whether or not it appears.

It is possible to specify a custom template for rendering a list filter:

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

See the default template provided by Django (admin/filter.html) fora concrete example.

ModelAdmin.list_max_show_all
Set list_max_show_all to control how many items can appear on a "Showall" admin change list page. The admin will display a "Show all" link on thechange list only if the total result count is less than or equal to thissetting. By default, this is set to 200.
ModelAdmin.list_per_page
Set list_per_page to control how many items appear on each paginatedadmin change list page. By default, this is set to 100.
ModelAdmin.list_select_related
Set list_select_related to tell Django to useselect_related() in retrievingthe list of objects on the admin change list page. This can save you abunch of database queries.

The value should be either a boolean, a list or a tuple. Default isFalse.

When value is True, select_related() will always be called. Whenvalue is set to False, Django will look at list_display and callselect_related() if any ForeignKey is present.

If you need more fine-grained control, use a tuple (or list) as value forlist_select_related. Empty tuple will prevent Django from callingselect_related at all. Any other tuple will be passed directly toselect_related as parameters. For example:

class ArticleAdmin(admin.ModelAdmin):
    list_select_related = ('author', 'category')

will call select_related('author', 'category').

If you need to specify a dynamic value based on the request, you canimplement a get_list_select_related() method.

ModelAdmin.ordering
Set ordering to specify how lists of objects should be ordered in theDjango admin views. This should be a list or tuple in the same format as amodel's ordering parameter.

If this isn't provided, the Django admin will use the model's defaultordering.

If you need to specify a dynamic order (for example depending on user orlanguage) you can implement a get_ordering() method.

Performance considerations with ordering and sorting

To ensure a deterministic ordering of results, the changelist addspk to the ordering if it can't find a single or unique together setof fields that provide total ordering.

For example, if the default ordering is by a non-unique name field,then the changelist is sorted by name and pk. This couldperform poorly if you have a lot of rows and don't have an index onname and pk.

ModelAdmin.paginator
The paginator class to be used for pagination. By default,django.core.paginator.Paginator is used. If the custom paginatorclass doesn't have the same constructor interface asdjango.core.paginator.Paginator, you will also need toprovide an implementation for ModelAdmin.get_paginator().
ModelAdmin.prepopulated_fields
Set prepopulated_fields to a dictionary mapping field names to thefields it should prepopulate from:

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

When set, the given fields will use a bit of JavaScript to populate fromthe fields assigned. The main use for this functionality is toautomatically generate the value for SlugField fields from one or moreother fields. The generated value is produced by concatenating the valuesof the source fields, and then by transforming that result into a validslug (e.g. substituting dashes for spaces; lowercasing ASCII letters; andremoving various English stop words such as 'a', 'an', 'as', and similar).

Prepopulated fields aren't modified by JavaScript after a value has beensaved. It's usually undesired that slugs change (which would cause anobject's URL to change if the slug is used in it).

prepopulated_fields doesn't accept DateTimeField, ForeignKey,OneToOneField, and ManyToManyField fields.

ModelAdmin.preserve_filters
The admin now preserves filters on the list view after creating, editingor deleting an object. You can restore the previous behavior of clearingfilters by setting this attribute to False.
ModelAdmin.radio_fields

By default, Django's admin uses a select-box interface (

ModelAdmin.autocomplete_fields
autocomplete_fields is a list of ForeignKey and/orManyToManyField fields you would like to change to Select2 autocomplete inputs.

By default, the admin uses a select-box interface (<select>) forthose fields. Sometimes you don't want to incur the overhead of selectingall the related instances to display in the dropdown.

The Select2 input looks similar to the default input but comes with asearch feature that loads the options asynchronously. This is faster andmore user-friendly if the related model has many instances.

You must define search_fields on the related object'sModelAdmin because the autocomplete search uses it.

To avoid unauthorized data disclosure, users must have the view orchange permission to the related object in order to use autocomplete.

Ordering and pagination of the results are controlled by the relatedModelAdmin's get_ordering() andget_paginator() methods.

In the following example, ChoiceAdmin has an autocomplete field for theForeignKey to the Question. The results are filtered by thequestion_text field and ordered by the date_created field:

class QuestionAdmin(admin.ModelAdmin):
    ordering = ['date_created']
    search_fields = ['question_text']
 
class ChoiceAdmin(admin.ModelAdmin):
    autocomplete_fields = ['question']

Performance considerations for large datasets

Ordering using ModelAdmin.ordering may cause performanceproblems as sorting on a large queryset will be slow.

Also, if your search fields include fields that aren't indexed by thedatabase, you might encounter poor performance on extremely largetables.

For those cases, it's a good idea to write your ownModelAdmin.get_search_results() implementation using afull-text indexed search.

You may also want to change the Paginator on very large tablesas the default paginator always performs a count() query.For example, you could override the default implementation of thePaginator.count property.

ModelAdmin.raw_id_fields

By default, Django's admin uses a select-box interface (

ModelAdmin.readonly_fields
By default the admin shows all fields as editable. Any fields in thisoption (which should be a list or tuple) will display its dataas-is and non-editable; they are also excluded from theModelForm used for creating and editing. Note thatwhen specifying ModelAdmin.fields or ModelAdmin.fieldsetsthe read-only fields must be present to be shown (they are ignoredotherwise).

If readonly_fields is used without defining explicit ordering throughModelAdmin.fields or ModelAdmin.fieldsets they will beadded last after all editable fields.

A read-only field can not only display data from a model's field, it canalso display the output of a model's method or a method of theModelAdmin class itself. This is very similar to the wayModelAdmin.list_display behaves. This provides an easy way to usethe admin interface to provide feedback on the status of the objects beingedited, for example:

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',)
 
    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>")
 
    # short_description functions like a model field's verbose_name
    address_report.short_description = "Address"

ModelAdmin.save_as
Set save_as to enable a "save as new" feature on admin change forms.

Normally, objects have three save options: "Save", "Save and continueediting", and "Save and add another". If save_as is True, "Saveand add another" will be replaced by a "Save as new" button that creates anew object (with a new ID) rather than updating the existing object.

By default, save_as is set to False.

ModelAdmin.save_as_continue
When save_as=True, the default redirect after saving thenew object is to the change view for that object. If you setsave_as_continue=False, the redirect will be to the changelist view.

By default, save_as_continue is set to True.

ModelAdmin.save_on_top
Set save_on_top to add save buttons across the top of your admin changeforms.

Normally, the save buttons appear only at the bottom of the forms. If youset save_on_top, the buttons will appear both on the top and thebottom.

By default, save_on_top is set to False.

ModelAdmin.search_fields
Set search_fields to enable a search box on the admin change list page.This should be set to a list of field names that will be searched wheneversomebody submits a search query in that text box.

These fields should be some kind of text field, such as CharField orTextField. You can also perform a related lookup on a ForeignKey orManyToManyField with the lookup API "follow" notation:

search_fields = ['foreign_key__related_fieldname']

For example, if you have a blog entry with an author, the followingdefinition would enable searching blog entries by the email address of theauthor:

search_fields = ['user__email']

When somebody does a search in the admin search box, Django splits thesearch query into words and returns all objects that contain each of thewords, case-insensitive (using the icontains lookup), where eachword must be in at least one of search_fields. For example, ifsearch_fields is set to ['first_name', 'last_name'] and a usersearches for john lennon, Django will do the equivalent of this SQLWHERE clause:

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

If you don't want to use icontains as the lookup, you can use anylookup by appending it the field. For example, you could use exactby setting search_fields to ['first_name__exact'].

Beware that because query terms are split and ANDed as described earlier,searching with exact only works with a single search word sincetwo or more words can't all be an exact match unless all words are the same.

New in Django 2.1:
The ability to specify a field lookup was added.

Some (older) shortcuts for specifying a field lookup are also available.You can prefix a field in searchfields with the following charactersand it's equivalent to adding _<lookup> to the field:

PrefixLookup^startswith=iexact@searchNoneicontains

If you need to customize search you can useModelAdmin.get_search_results() to provide additional or alternatesearch behavior.

ModelAdmin.show_full_result_count
Set show_full_result_count to control whether the full count of objectsshould be displayed on a filtered admin page (e.g. 99 results (103 total)).If this option is set to False, a text like 99 results (Show all)is displayed instead.

The default of show_full_result_count=True generates a query to performa full count on the table which can be expensive if the table contains alarge number of rows.

ModelAdmin.sortable_by
New in Django 2.1:

By default, the change list page allows sorting by all model fields (andcallables that have the admin_order_field property) specified inlist_display.

If you want to disable sorting for some columns, set sortable_by toa collection (e.g. list, tuple, or set) of the subset oflist_display that you want to be sortable. An empty collectiondisables sorting for all columns.

If you need to specify this list dynamically, implement aget_sortable_by() method instead.

ModelAdmin.view_on_site
Set view_on_site to control whether or not to display the "View on site" link.This link should bring you to a URL where you can display the saved object.

This value can be either a boolean flag or a callable. If True (thedefault), the object's get_absolute_url()method will be used to generate the url.

If your model has a get_absolute_url() methodbut you don't want the "View on site" button to appear, you only need to setview_on_site to False:

from django.contrib import admin
 
class PersonAdmin(admin.ModelAdmin):
    view_on_site = False

In case it is a callable, it accepts the model instance as a parameter.For example:

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

Custom template options

The Overriding admin templates section describes how to override or extendthe default admin templates. Use the following options to override the defaulttemplates used by the ModelAdmin views:

ModelAdmin.add_form_template
Path to a custom template, used by add_view().
ModelAdmin.change_form_template
Path to a custom template, used by change_view().
ModelAdmin.change_list_template
Path to a custom template, used by changelist_view().
ModelAdmin.delete_confirmation_template
Path to a custom template, used by delete_view() for displaying aconfirmation page when deleting one or more objects.
ModelAdmin.delete_selected_confirmation_template
Path to a custom template, used by the delete_selected action methodfor displaying a confirmation page when deleting one or more objects. Seethe actions documentation.
ModelAdmin.object_history_template
Path to a custom template, used by history_view().
ModelAdmin.popup_response_template
Path to a custom template, used by response_add(),response_change(), and response_delete().

ModelAdmin methods

警告

When overriding ModelAdmin.save_model() andModelAdmin.delete_model(), your code must save/delete theobject. They aren't meant for veto purposes, rather they allow you toperform extra operations.

ModelAdmin.savemodel(_request, obj, form, change)[源代码]
The save_model method is given the HttpRequest, a model instance,a ModelForm instance, and a boolean value based on whether it is addingor changing the object. Overriding this method allows doing pre- orpost-save operations. Call super().save_model() to save the objectusing Model.save().

For example to attach request.user to the object prior to saving:

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.deletemodel(_request, obj)[源代码]
The delete_model method is given the HttpRequest and a modelinstance. Overriding this method allows doing pre- or post-deleteoperations. Call super().delete_model() to delete the object usingModel.delete().
ModelAdmin.deletequeryset(_request, queryset)[源代码]
New in Django 2.1:

The delete_queryset() method is given the HttpRequest and aQuerySet of objects to be deleted. Override this method to customizethe deletion process for the "delete selected objects" action.

ModelAdmin.saveformset(_request, form, formset, change)[源代码]
The save_formset method is given the HttpRequest, the parentModelForm instance and a boolean value based on whether it is adding orchanging the parent object.

For example, to attach request.user to each changed formsetmodel instance:

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()

See also Saving objects in the formset.

ModelAdmin.getordering(_request)
The get_ordering method takes a request as parameter andis expected to return a list or tuple for ordering similarto the ordering attribute. For example:

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

ModelAdmin.getsearch_results(_request, queryset, search_term)[源代码]
The get_search_results method modifies the list of objects displayedinto those that match the provided search term. It accepts the request, aqueryset that applies the current filters, and the user-provided search term.It returns a tuple containing a queryset modified to implement the search, anda boolean indicating if the results may contain duplicates.

The default implementation searches the fields named in ModelAdmin.search_fields.

This method may be overridden with your own custom search method. Forexample, you might wish to search by an integer field, or use an externaltool such as Solr or Haystack. You must establish if the queryset changesimplemented by your search method may introduce duplicates into the results,and return True in the second element of the return value.

For example, to search by name and age, you could use:

class PersonAdmin(admin.ModelAdmin):
    list_display = ('name', 'age')
    search_fields = ('name',)
 
    def get_search_results(self, request, queryset, search_term):
        queryset, use_distinct = 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, use_distinct

This implementation is more efficient than search_fields = ('name', '=age') which results in a string comparison for the numericfield, for example … OR UPPER("polls_choice"."votes"::text) = UPPER('4')on PostgreSQL.

ModelAdmin.saverelated(_request, form, formsets, change)[源代码]
The save_related method is given the HttpRequest, the parentModelForm instance, the list of inline formsets and a boolean valuebased on whether the parent is being added or changed. Here you can do anypre- or post-save operations for objects related to the parent. Notethat at this point the parent object and its form have already been saved.
ModelAdmin.getautocomplete_fields(_request)
The get_autocomplete_fields() method is given the HttpRequest and isexpected to return a list or tuple of field names that will bedisplayed with an autocomplete widget as described above in theModelAdmin.autocomplete_fields section.
ModelAdmin.getreadonly_fields(_request, obj=None)
The get_readonly_fields method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna list or tuple of field names that will be displayed as read-only,as described above in the ModelAdmin.readonly_fields section.
ModelAdmin.getprepopulated_fields(_request, obj=None)
The get_prepopulated_fields method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna dictionary, as described above in the ModelAdmin.prepopulated_fieldssection.
ModelAdmin.getlist_display(_request)[源代码]
The get_list_display method is given the HttpRequest and isexpected to return a list or tuple of field names that will bedisplayed on the changelist view as described above in theModelAdmin.list_display section.
ModelAdmin.getlist_display_links(_request, list_display)[源代码]
The get_list_display_links method is given the HttpRequest andthe list or tuple returned by ModelAdmin.get_list_display().It is expected to return either None or a list or tuple of fieldnames on the changelist that will be linked to the change view, as describedin the ModelAdmin.list_display_links section.
ModelAdmin.getexclude(_request, obj=None)
The get_exclude method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof fields, as described in ModelAdmin.exclude.
ModelAdmin.getfields(_request, obj=None)
The get_fields method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof fields, as described above in the ModelAdmin.fields section.
ModelAdmin.getfieldsets(_request, obj=None)
The get_fieldsets method is given the HttpRequest and the objbeing edited (or None on an add form) and is expected to return a listof two-tuples, in which each two-tuple represents a <fieldset> on theadmin form page, as described above in the ModelAdmin.fieldsets section.
ModelAdmin.getlist_filter(_request)[源代码]
The get_list_filter method is given the HttpRequest and is expectedto return the same kind of sequence type as for thelist_filter attribute.
ModelAdmin.getlist_select_related(_request)[源代码]
The get_list_select_related method is given the HttpRequest andshould return a boolean or list as ModelAdmin.list_select_relateddoes.
ModelAdmin.getsearch_fields(_request)[源代码]
The get_search_fields method is given the HttpRequest and is expectedto return the same kind of sequence type as for thesearch_fields attribute.
ModelAdmin.getsortable_by(_request)
New in Django 2.1:

The get_sortable_by() method is passed the HttpRequest and isexpected to return a collection (e.g. list, tuple, or set) offield names that will be sortable in the change list page.

Its default implementation returns sortable_by if it's set,otherwise it defers to get_list_display().

For example, to prevent one or more columns from being sortable:

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

ModelAdmin.getinline_instances(_request, obj=None)[源代码]
The get_inline_instances method is given the HttpRequest and theobj being edited (or None on an add form) and is expected to returna list or tuple of InlineModelAdminobjects, as described below in the InlineModelAdminsection. For example, the following would return inlines without the defaultfiltering based on add, change, delete, and view permissions:

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]

If you override this method, make sure that the returned inlines areinstances of the classes defined in inlines or you might encountera "Bad Request" error when adding related objects.

ModelAdmin.get_urls()[源代码]
The get_urls method on a ModelAdmin returns the URLs to be used forthat ModelAdmin in the same way as a URLconf. Therefore you can extendthem as documented in URL调度器:

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.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)

If you want to use the admin layout, extend from admin/base_site.html:

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

注解

Notice that the custom patterns are included before the regular adminURLs: the admin URL patterns are very permissive and will match nearlyanything, so you'll usually want to prepend your custom URLs to thebuilt-in ones.

In this example, my_view will be accessed at/admin/myapp/mymodel/my_view/ (assuming the admin URLs are includedat /admin/.)

However, the self.my_view function registered above suffers from twoproblems:

It will not perform any permission checks, so it will be accessibleto the general public.
It will not provide any header details to prevent caching. This meansif the page retrieves data from the database, and caching middleware isactive, the page could show outdated information.
Since this is usually not what you want, Django provides a conveniencewrapper to check permissions and mark the view as non-cacheable. Thiswrapper is AdminSite.admin_view() (i.e. self.admin_site.admin_viewinside a ModelAdmin instance); use it like so:

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

Notice the wrapped view in the fifth line above:

path('my_view/', self.admin_site.admin_view(self.my_view))

This wrapping will protect self.my_view from unauthorized access andwill apply the django.views.decorators.cache.never_cache() decorator tomake sure it is not cached if the cache middleware is active.

If the page is cacheable, but you still want the permission check to beperformed, you can pass a cacheable=True argument toAdminSite.admin_view():

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

ModelAdmin views have model_admin attributes. OtherAdminSite views have admin_site attributes.

ModelAdmin.getform(_request, obj=None, **kwargs)[源代码]
Returns a ModelForm class for use in the admin addand change views, see add_view() and change_view().

The base implementation uses modelform_factory()to subclass form, modified by attributes such as fieldsand exclude. So, for example, if you wanted to offer additionalfields to superusers, you could swap in a different base form like so:

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)

You may also simply return a custom ModelForm classdirectly.

ModelAdmin.getformsets_with_inlines(_request, obj=None)[源代码]
Yields (FormSet, InlineModelAdmin) pairs for use in admin addand change views.

For example if you wanted to display a particular inline only in the changeview, you could override get_formsets_with_inlines as follows:

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.formfieldfor_foreignkey(_db_field, request, **kwargs)
The formfield_for_foreignkey method on a ModelAdmin allows you tooverride the default formfield for a foreign keys field. For example, toreturn a subset of objects for this foreign key field based on the user:

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)

This uses the HttpRequest instance to filter the Car foreign keyfield to only display the cars owned by the User instance.

ModelAdmin.formfieldfor_manytomany(_db_field, request, **kwargs)
Like the formfield_for_foreignkey method, theformfield_for_manytomany method can be overridden to change thedefault formfield for a many to many field. For example, if an owner canown multiple cars and cars can belong to multiple owners — a many tomany relationship — you could filter the Car foreign key field toonly display the cars owned by the 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.formfieldfor_choice_field(_db_field, request, **kwargs)
Like the formfield_for_foreignkey and formfield_for_manytomanymethods, the formfield_for_choice_field method can be overridden tochange the default formfield for a field that has declared choices. Forexample, if the choices available to a superuser should be different thanthose available to regular staff, you could proceed as follows:

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'] += (('ready', 'Ready for deployment'),)
        return super().formfield_for_choice_field(db_field, request, **kwargs)

Note

Any choices attribute set on the formfield will be limited to theform field only. If the corresponding field on the model has choicesset, the choices provided to the form must be a valid subset of thosechoices, otherwise the form submission will fail witha ValidationError when the model itselfis validated before saving.

ModelAdmin.getchangelist(_request, **kwargs)[源代码]
Returns the Changelist class to be used for listing. By default,django.contrib.admin.views.main.ChangeList is used. By inheriting thisclass you can change the behavior of the listing.
ModelAdmin.getchangelist_form(_request, **kwargs)[源代码]
Returns a ModelForm class for use in the Formseton the changelist page. To use a custom form, for example:

from django import forms
 
class MyForm(forms.ModelForm):
    pass
 
class MyModelAdmin(admin.ModelAdmin):
    def get_changelist_form(self, request, **kwargs):
        return MyForm

Note

If you define the Meta.model attribute on aModelForm, you must also define theMeta.fields attribute (or the Meta.exclude attribute). However,ModelAdmin ignores this value, overriding it with theModelAdmin.list_editable attribute. The easiest solution is toomit the Meta.model attribute, since ModelAdmin will provide thecorrect model to use.

ModelAdmin.getchangelist_formset(_request, **kwargs)[源代码]
Returns a ModelFormSet class for use on thechangelist page if list_editable is used. To use acustom formset, for example:

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.lookupallowed(_lookup, value)
The objects in the changelist page can be filtered with lookups from theURL's query string. This is how list_filter works, for example. Thelookups are similar to what's used in QuerySet.filter() (e.g.user__email=user@example.com). Since the lookups in the query stringcan be manipulated by the user, they must be sanitized to preventunauthorized data exposure.

The lookup_allowed() method is given a lookup path from the query string(e.g. 'user__email') and the corresponding value(e.g. 'user@example.com'), and returns a boolean indicating whetherfiltering the changelist's QuerySet using the parameters is permitted.If lookup_allowed() returns False, DisallowedModelAdminLookup(subclass of SuspiciousOperation) is raised.

By default, lookup_allowed() allows access to a model's local fields,field paths used in list_filter (but not paths fromget_list_filter()), and lookups required forlimit_choices_to to functioncorrectly in raw_id_fields.

Override this method to customize the lookups permitted for yourModelAdmin subclass.

ModelAdmin.hasview_permission(_request, obj=None)
New in Django 2.1:

Should return True if viewing obj is permitted, False otherwise.If obj is None, should return True or False to indicate whetherviewing of objects of this type is permitted in general (e.g., Falsewill be interpreted as meaning that the current user is not permitted toview any object of this type).

The default implementation returns True if the user has either the"change" or "view" permission.

ModelAdmin.hasadd_permission(_request)
Should return True if adding an object is permitted, Falseotherwise.
ModelAdmin.haschange_permission(_request, obj=None)
Should return True if editing obj is permitted, Falseotherwise. If obj is None, should return True or False toindicate whether editing of objects of this type is permitted in general(e.g., False will be interpreted as meaning that the current user isnot permitted to edit any object of this type).
ModelAdmin.hasdelete_permission(_request, obj=None)
Should return True if deleting obj is permitted, Falseotherwise. If obj is None, should return True or False toindicate whether deleting objects of this type is permitted in general(e.g., False will be interpreted as meaning that the current user isnot permitted to delete any object of this type).
ModelAdmin.hasmodule_permission(_request)
Should return True if displaying the module on the admin index page andaccessing the module's index page is permitted, False otherwise.Uses User.has_module_perms() by default. Overridingit does not restrict access to the view, add, change, or delete views,has_view_permission(),has_add_permission(),has_change_permission(), andhas_delete_permission() should be used for that.
ModelAdmin.getqueryset(_request)
The get_queryset method on a ModelAdmin returns aQuerySet of all model instances thatcan be edited by the admin site. One use case for overriding this methodis to show objects owned by the logged-in user:

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.messageuser(_request, message, level=messages.INFO, extra_tags='', fail_silently=False)[源代码]
Sends a message to the user using the django.contrib.messagesbackend. See the custom ModelAdmin example.

Keyword arguments allow you to change the message level, add extra CSStags, or fail silently if the contrib.messages framework is notinstalled. These keyword arguments match those fordjango.contrib.messages.add_message(), see that function'sdocumentation for more details. One difference is that the level may bepassed as a string label in addition to integer/constant.

ModelAdmin.getpaginator(_request, queryset, per_page, orphans=0, allow_empty_first_page=True)[源代码]
Returns an instance of the paginator to use for this view. By default,instantiates an instance of paginator.
ModelAdmin.responseadd(_request, obj, post_url_continue=None)[源代码]
Determines the HttpResponse for theadd_view() stage.

response_add is called after the admin form is submitted andjust after the object and all the related instances havebeen created and saved. You can override it to change the default behaviorafter the object has been created.

ModelAdmin.responsechange(_request, obj)[源代码]
Determines the HttpResponse for thechange_view() stage.

response_change is called after the admin form is submitted andjust after the object and all the related instances havebeen saved. You can override it to change the defaultbehavior after the object has been changed.

ModelAdmin.responsedelete(_request, obj_display, obj_id)[源代码]
Determines the HttpResponse for thedelete_view() stage.

response_delete is called after the object has beendeleted. You can override it to change the defaultbehavior after the object has been deleted.

obj_display is a string with the name of the deletedobject.

obj_id is the serialized identifier used to retrieve the object to bedeleted.

ModelAdmin.getchangeform_initial_data(_request)[源代码]
A hook for the initial data on admin change forms. By default, fields aregiven initial values from GET parameters. For instance,?name=initial_value will set the name field's initial value to beinitial_value.

This method should return a dictionary in the form{'fieldname': 'fieldval'}:

def get_changeform_initial_data(self, request):
    return {'name': 'custom_initial_value'}

ModelAdmin.getdeleted_objects(_objs, request)[源代码]
New in Django 2.1:

A hook for customizing the deletion process of the delete_view() andthe "delete selected" action.

The objs argument is a homogeneous iterable of objects (a QuerySetor a list of model instances) to be deleted, and request is theHttpRequest.

This method must return a 4-tuple of(deleted_objects, model_count, perms_needed, protected).

deleted_objects is a list of strings representing all the objects thatwill be deleted. If there are any related objects to be deleted, the listis nested and includes those related objects. The list is formatted in thetemplate using the unordered_list filter.

model_count is a dictionary mapping each model'sverbose_name_plural to the number ofobjects that will be deleted.

perms_needed is a set of verbose_namesof the models that the user doesn't have permission to delete.

protected is a list of strings representing of all the protectedrelated objects that can't be deleted. The list is displayed in thetemplate.

Other methods

ModelAdmin.addview(_request, form_url='', extra_context=None)[源代码]
Django view for the model instance addition page. See note below.
ModelAdmin.changeview(_request, object_id, form_url='', extra_context=None)[源代码]
Django view for the model instance editing page. See note below.
ModelAdmin.changelistview(_request, extra_context=None)[源代码]
Django view for the model instances change list/actions page. See notebelow.
ModelAdmin.deleteview(_request, object_id, extra_context=None)[源代码]
Django view for the model instance(s) deletion confirmation page. See notebelow.
ModelAdmin.historyview(_request, object_id, extra_context=None)[源代码]
Django view for the page that shows the modification history for a givenmodel instance.

Unlike the hook-type ModelAdmin methods detailed in the previous section,these five methods are in reality designed to be invoked as Django views fromthe admin application URL dispatching handler to render the pages that dealwith model instances CRUD operations. As a result, completely overriding thesemethods will significantly change the behavior of the admin application.

One common reason for overriding these methods is to augment the context datathat is provided to the template that renders the view. In the followingexample, the change view is overridden so that the rendered template isprovided some extra mapping data that would not otherwise be available:

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,
        )

These views return TemplateResponseinstances which allow you to easily customize the response data beforerendering. For more details, see the TemplateResponse documentation.

ModelAdmin asset definitions

There are times where you would like add a bit of CSS and/or JavaScript tothe add/change views. This can be accomplished by using a Media inner classon your ModelAdmin:

class ArticleAdmin(admin.ModelAdmin):
    class Media:
        css = {
            "all": ("my_styles.css",)
        }
        js = ("my_code.js",)

The staticfiles app prependsSTATIC_URL (or MEDIA_URL if STATIC_URL isNone) to any asset paths. The same rules apply as regular assetdefinitions on forms.

jQuery

Django admin JavaScript makes use of the jQuery library.

To avoid conflicts with user-supplied scripts or libraries, Django's jQuery(version 3.3.1) is namespaced as django.jQuery. If you want to use jQueryin your own admin JavaScript without including a second copy, you can use thedjango.jQuery object on changelist and add/edit views.

Changed in Django 2.1:
jQuery was upgraded from 2.2.3 to 3.3.1.

The ModelAdmin class requires jQuery by default, so there is no needto add jQuery to your ModelAdmin’s list of media resources unless you havea specific need. For example, if you require the jQuery library to be in theglobal namespace (for example when using third-party jQuery plugins) or if youneed a newer version of jQuery, you will have to include your own copy.

Django provides both uncompressed and 'minified' versions of jQuery, asjquery.js and jquery.min.js respectively.

ModelAdmin and InlineModelAdmin have a media propertythat returns a list of Media objects which store paths to the JavaScriptfiles for the forms and/or formsets. If DEBUG is True it willreturn the uncompressed versions of the various JavaScript files, includingjquery.js; if not, it will return the 'minified' versions.

Adding custom validation to the admin

Adding custom validation of data in the admin is quite easy. The automaticadmin interface reuses django.forms, and the ModelAdmin class givesyou the ability define your own form:

class ArticleAdmin(admin.ModelAdmin):
    form = MyArticleAdminForm

MyArticleAdminForm can be defined anywhere as long as you import whereneeded. Now within your form you can add your own custom validation forany field:

class MyArticleAdminForm(forms.ModelForm):
    def clean_name(self):
        # do something that validates your data
        return self.cleaned_data["name"]

It is important you use a ModelForm here otherwise things can break. Seethe forms documentation on custom validation and, more specifically, themodel form validation notes for moreinformation.

InlineModelAdmin objects

class InlineModelAdmin
class TabularInline[源代码]
class StackedInline[源代码]
The admin interface has the ability to edit models on the same page as aparent model. These are called inlines. Suppose you have these two models:

from django.db import models
 
class Author(models.Model):
   name = models.CharField(max_length=100)
 
class Book(models.Model):
   author = models.ForeignKey(Author, on_delete=models.CASCADE)
   title = models.CharField(max_length=100)

You can edit the books authored by an author on the author page. You addinlines to a model by specifying them in a ModelAdmin.inlines:

from django.contrib import admin
 
class BookInline(admin.TabularInline):
    model = Book
 
class AuthorAdmin(admin.ModelAdmin):
    inlines = [
        BookInline,
    ]

Django provides two subclasses of InlineModelAdmin and they are:

TabularInline
StackedInline
The difference between these two is merely the template used to renderthem.

InlineModelAdmin options

InlineModelAdmin shares many of the same features as ModelAdmin, andadds some of its own (the shared features are actually defined in theBaseModelAdmin superclass). The shared features are:

form
fieldsets
fields
formfield_overrides
exclude
filter_horizontal
filter_vertical
ordering
prepopulated_fields
get_queryset()
radio_fields
readonly_fields
raw_id_fields
formfield_for_choice_field()
formfield_for_foreignkey()
formfield_for_manytomany()
has_module_permission()
The InlineModelAdmin class adds or customizes:
InlineModelAdmin.model
The model which the inline is using. This is required.
InlineModelAdmin.fk_name
The name of the foreign key on the model. In most cases this will be dealtwith automatically, but fk_name must be specified explicitly if thereare more than one foreign key to the same parent model.
InlineModelAdmin.formset
This defaults to BaseInlineFormSet. Usingyour own formset can give you many possibilities of customization. Inlinesare built around model formsets.
InlineModelAdmin.form
The value for form defaults to ModelForm. This is what is passedthrough to inlineformset_factory() whencreating the formset for this inline.

警告

When writing custom validation for InlineModelAdmin forms, be cautiousof writing validation that relies on features of the parent model. If theparent model fails to validate, it may be left in an inconsistent state asdescribed in the warning in 验证 ModelForm.

InlineModelAdmin.classes
A list or tuple containing extra CSS classes to apply to the fieldset thatis rendered for the inlines. Defaults to None. As with classesconfigured in fieldsets, inlines with a collapseclass will be initially collapsed and their header will have a small "show"link.
InlineModelAdmin.extra
This controls the number of extra forms the formset will display inaddition to the initial forms. See theformsets documentation for moreinformation.

For users with JavaScript-enabled browsers, an "Add another" link isprovided to enable any number of additional inlines to be added in additionto those provided as a result of the extra argument.

The dynamic link will not appear if the number of currently displayed formsexceeds max_num, or if the user does not have JavaScript enabled.

InlineModelAdmin.get_extra() also allows you to customize the numberof extra forms.

InlineModelAdmin.max_num
This controls the maximum number of forms to show in the inline. Thisdoesn't directly correlate to the number of objects, but can if the valueis small enough. See Limiting the number of editable objects for more information.

InlineModelAdmin.get_max_num() also allows you to customize themaximum number of extra forms.

InlineModelAdmin.min_num
This controls the minimum number of forms to show in the inline.See modelformset_factory() for more information.

InlineModelAdmin.get_min_num() also allows you to customize theminimum number of displayed forms.

InlineModelAdmin.raw_id_fields

By default, Django's admin uses a select-box interface (

InlineModelAdmin.template
The template used to render the inline on the page.
InlineModelAdmin.verbose_name
An override to the verbose_name found in the model's inner Metaclass.
InlineModelAdmin.verbose_name_plural
An override to the verbose_name_plural found in the model's innerMeta class.
InlineModelAdmin.can_delete
Specifies whether or not inline objects can be deleted in the inline.Defaults to True.
InlineModelAdmin.show_change_link
Specifies whether or not inline objects that can be changed in theadmin have a link to the change form. Defaults to False.
InlineModelAdmin.getformset(_request, obj=None, **kwargs)
Returns a BaseInlineFormSet class for use inadmin add/change views. See the example forModelAdmin.get_formsets_with_inlines.
InlineModelAdmin.getextra(_request, obj=None, **kwargs)
Returns the number of extra inline forms to use. By default, returns theInlineModelAdmin.extra attribute.

Override this method to programmatically determine the number of extrainline forms. For example, this may be based on the model instance(passed as the keyword argument obj):

class BinaryTreeAdmin(admin.TabularInline):
    model = BinaryTree
 
    def get_extra(self, request, obj=None, **kwargs):
        extra = 2
        if obj:
            return extra - obj.binarytree_set.count()
        return extra

InlineModelAdmin.getmax_num(_request, obj=None, **kwargs)
Returns the maximum number of extra inline forms to use. By default,returns the InlineModelAdmin.max_num attribute.

Override this method to programmatically determine the maximum number ofinline forms. For example, this may be based on the model instance(passed as the keyword argument obj):

class BinaryTreeAdmin(admin.TabularInline):
    model = BinaryTree
 
    def get_max_num(self, request, obj=None, **kwargs):
        max_num = 10
        if obj and obj.parent:
            return max_num - 5
        return max_num

InlineModelAdmin.getmin_num(_request, obj=None, **kwargs)
Returns the minimum number of inline forms to use. By default,returns the InlineModelAdmin.min_num attribute.

Override this method to programmatically determine the minimum number ofinline forms. For example, this may be based on the model instance(passed as the keyword argument obj).

InlineModelAdmin.hasadd_permission(_request, obj)
Should return True if adding an inline object is permitted, Falseotherwise. obj is the parent object being edited or None whenadding a new parent.

Changed in Django 2.1:
The obj argument was added. During the deprecation period, it mayalso be None if third-party calls to has_add_permission() don'tprovide it.

InlineModelAdmin.haschange_permission(_request, obj=None)
Should return True if editing an inline object is permitted, Falseotherwise. obj is the parent object being edited.
InlineModelAdmin.hasdelete_permission(_request, obj=None)
Should return True if deleting an inline object is permitted, Falseotherwise. obj is the parent object being edited.

Working with a model with two or more foreign keys to the same parent model

It is sometimes possible to have more than one foreign key to the same model.Take this model for instance:

from django.db import models
 
class Friendship(models.Model):
    to_person = models.ForeignKey(Person, on_delete=models.CASCADE, related_name="friends")
    from_person = models.ForeignKey(Person, on_delete=models.CASCADE, related_name="from_friends")

If you wanted to display an inline on the Person admin add/change pagesyou need to explicitly define the foreign key since it is unable to do soautomatically:

from django.contrib import admin
from myapp.models import Friendship
 
class FriendshipInline(admin.TabularInline):
    model = Friendship
    fk_name = "to_person"
 
class PersonAdmin(admin.ModelAdmin):
    inlines = [
        FriendshipInline,
    ]

Working with many-to-many models

By default, admin widgets for many-to-many relations will be displayedon whichever model contains the actual reference to theManyToManyField. Depending on your ModelAdmindefinition, each many-to-many field in your model will be represented by astandard HTML <select multiple>, a horizontal or vertical filter, or araw_id_admin widget. However, it is also possible to replace thesewidgets with inlines.

Suppose we have the following models:

from django.db import models
 
class Person(models.Model):
    name = models.CharField(max_length=128)
 
class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, related_name='groups')

If you want to display many-to-many relations using an inline, you can doso by defining an InlineModelAdmin object for the relationship:

from django.contrib import admin
 
class MembershipInline(admin.TabularInline):
    model = Group.members.through
 
class PersonAdmin(admin.ModelAdmin):
    inlines = [
        MembershipInline,
    ]
 
class GroupAdmin(admin.ModelAdmin):
    inlines = [
        MembershipInline,
    ]
    exclude = ('members',)

There are two features worth noting in this example.

Firstly - the MembershipInline class references Group.members.through.The through attribute is a reference to the model that manages themany-to-many relation. This model is automatically created by Django when youdefine a many-to-many field.

Secondly, the GroupAdmin must manually exclude the members field.Django displays an admin widget for a many-to-many field on the model thatdefines the relation (in this case, Group). If you want to use an inlinemodel to represent the many-to-many relationship, you must tell Django's adminto not display this widget - otherwise you will end up with two widgets onyour admin page for managing the relation.

Note that when using this technique them2m_changed signals aren't triggered. Thisis because as far as the admin is concerned, through is just a model withtwo foreign key fields rather than a many-to-many relation.

In all other respects, the InlineModelAdmin is exactly the same as anyother. You can customize the appearance using any of the normalModelAdmin properties.

Working with many-to-many intermediary models

When you specify an intermediary model using the through argument to aManyToManyField, the admin will not display awidget by default. This is because each instance of that intermediary modelrequires more information than could be displayed in a single widget, and thelayout required for multiple widgets will vary depending on the intermediatemodel.

However, we still want to be able to edit that information inline. Fortunately,this is easy to do with inline admin models. Suppose we have the followingmodels:

from django.db import models
 
class Person(models.Model):
    name = models.CharField(max_length=128)
 
class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, through='Membership')
 
class Membership(models.Model):
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    date_joined = models.DateField()
    invite_reason = models.CharField(max_length=64)

The first step in displaying this intermediate model in the admin is todefine an inline class for the Membership model:

class MembershipInline(admin.TabularInline):
    model = Membership
    extra = 1

This simple example uses the default InlineModelAdmin values for theMembership model, and limits the extra add forms to one. This could becustomized using any of the options available to InlineModelAdmin classes.

Now create admin views for the Person and Group models:

class PersonAdmin(admin.ModelAdmin):
    inlines = (MembershipInline,)
 
class GroupAdmin(admin.ModelAdmin):
    inlines = (MembershipInline,)

Finally, register your Person and Group models with the admin site:

admin.site.register(Person, PersonAdmin)
admin.site.register(Group, GroupAdmin)

Now your admin site is set up to edit Membership objects inline fromeither the Person or the Group detail pages.

Using generic relations as an inline

It is possible to use an inline with generically related objects. Let's sayyou have the following models:

from django.contrib.contenttypes.fields import GenericForeignKey
from django.db import models
 
class Image(models.Model):
    image = models.ImageField(upload_to="images")
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
    object_id = models.PositiveIntegerField()
    content_object = GenericForeignKey("content_type", "object_id")
 
class Product(models.Model):
    name = models.CharField(max_length=100)

If you want to allow editing and creating an Image instance on theProduct, add/change views you can useGenericTabularInlineor GenericStackedInline (bothsubclasses of GenericInlineModelAdmin)provided by admin. They implement tabularand stacked visual layouts for the forms representing the inline objects,respectively, just like their non-generic counterparts. They behave just likeany other inline. In your admin.py for this example app:

from django.contrib import admin
from django.contrib.contenttypes.admin import GenericTabularInline
 
from myproject.myapp.models import Image, Product
 
class ImageInline(GenericTabularInline):
    model = Image
 
class ProductAdmin(admin.ModelAdmin):
    inlines = [
        ImageInline,
    ]
 
admin.site.register(Product, ProductAdmin)

See the contenttypes documentation for morespecific information.

Overriding admin templates

It is relatively easy to override many of the templates which the admin moduleuses to generate the various pages of an admin site. You can even override afew of these templates for a specific app, or a specific model.

Set up your projects admin template directories

The admin template files are located in the contrib/admin/templates/admindirectory.

In order to override one or more of them, first create an admin directoryin your project's templates directory. This can be any of the directoriesyou specified in the DIRS option of theDjangoTemplates backend in the TEMPLATES setting. If you havecustomized the 'loaders' option, be sure'django.template.loaders.filesystem.Loader' appears before'django.template.loaders.app_directories.Loader' so that your customtemplates will be found by the template loading system before those that areincluded with django.contrib.admin.

Within this admin directory, create sub-directories named after your app.Within these app subdirectories create sub-directories named after your models.Note, that the admin app will lowercase the model name when looking for thedirectory, so make sure you name the directory in all lowercase if you aregoing to run your app on a case-sensitive filesystem.

To override an admin template for a specific app, copy and edit the templatefrom the django/contrib/admin/templates/admin directory, and save it to oneof the directories you just created.

For example, if we wanted to add a tool to the change list view for all themodels in an app named my_app, we would copycontrib/admin/templates/admin/change_list.html to thetemplates/admin/my_app/ directory of our project, and make any necessarychanges.

If we wanted to add a tool to the change list view for only a specific modelnamed 'Page', we would copy that same file to thetemplates/admin/my_app/page directory of our project.

Overriding vs. replacing an admin template

Because of the modular design of the admin templates, it is usually neithernecessary nor advisable to replace an entire template. It is almost alwaysbetter to override only the section of the template which you need to change.

To continue the example above, we want to add a new link next to theHistory tool for the Page model. After looking at change_form.htmlwe determine that we only need to override the object-tools-items block.Therefore here is our new change_form.html :

{% extends "admin/change_form.html" %}
{% load i18n admin_urls %}
{% block object-tools-items %}
    <li>
        <a href="{% url opts|admin_urlname:'history' original.pk|admin_urlquote %}" class="historylink">{% trans "History" %}</a>
    </li>
    <li>
        <a href="mylink/" class="historylink">My Link</a>
    </li>
    {% if has_absolute_url %}
        <li>
            <a href="{% url 'admin:view_on_site' content_type_id original.pk %}" class="viewsitelink">{% trans "View on site" %}</a>
        </li>
    {% endif %}
{% endblock %}

And that's it! If we placed this file in the templates/admin/my_appdirectory, our link would appear on the change form for all models withinmy_app.

Templates which may be overridden per app or model

Not every template in contrib/admin/templates/admin may be overridden perapp or per model. The following can:

actions.html
app_index.html
change_form.html
change_form_object_tools.html
change_list.html
change_list_object_tools.html
change_list_results.html
date_hierarchy.html
delete_confirmation.html
object_history.html
pagination.html
popup_response.html
prepopulated_fields_js.html
search_form.html
submit_line.html
Changed in Django 2.1:
The ability to override the actions.html, change_form_object_tools.html,change_list_object_tools.html, change_list_results.html,date_hierarchy.html, pagination.html, prepopulated_fields_js.html,search_form.html, and submit_line.html templates was added.

For those templates that cannot be overridden in this way, you may stilloverride them for your entire project. Just place the new version in yourtemplates/admin directory. This is particularly useful to create custom 404and 500 pages.

注解

Some of the admin templates, such as change_list_results.html are usedto render custom inclusion tags. These may be overridden, but in such casesyou are probably better off creating your own version of the tag inquestion and giving it a different name. That way you can use itselectively.

If you wish to change the index, login or logout templates, you are better offcreating your own AdminSite instance (see below), and changing theAdminSite.index_template , AdminSite.login_template orAdminSite.logout_template properties.

AdminSite objects

class AdminSite(name='admin')[源代码]
A Django administrative site is represented by an instance ofdjango.contrib.admin.sites.AdminSite; by default, an instance ofthis class is created as django.contrib.admin.site and you canregister your models and ModelAdmin instances with it.

If you want to customize the default admin site, you can override it.

When constructing an instance of an AdminSite, you can providea unique instance name using the name argument to the constructor. Thisinstance name is used to identify the instance, especially whenreversing admin URLs. If no instance name isprovided, a default instance name of admin will be used.See Customizing the AdminSite class for an example of customizing theAdminSite class.

AdminSite attributes

Templates can override or extend base admin templates as described inOverriding admin templates.

AdminSite.site_header
The text to put at the top of each admin page, as an <h1> (a string).By default, this is "Django administration".
AdminSite.site_title
The text to put at the end of each admin page's <title> (a string). Bydefault, this is "Django site admin".
AdminSite.site_url
The URL for the "View site" link at the top of each admin page. By default,site_url is /. Set it to None to remove the link.

For sites running on a subpath, the each_context() method checks ifthe current request has request.META['SCRIPT_NAME'] set and uses thatvalue if site_url isn't set to something other than /.

AdminSite.index_title
The text to put at the top of the admin index page (a string). By default,this is "Site administration".
AdminSite.index_template
Path to a custom template that will be used by the admin site main indexview.
AdminSite.app_index_template
Path to a custom template that will be used by the admin site app index view.
AdminSite.empty_value_display
The string to use for displaying empty values in the admin site's changelist. Defaults to a dash. The value can also be overridden on a perModelAdmin basis and on a custom field within a ModelAdmin bysetting an empty_value_display attribute on the field. SeeModelAdmin.empty_value_display for examples.
AdminSite.login_template
Path to a custom template that will be used by the admin site login view.
AdminSite.login_form
Subclass of AuthenticationForm thatwill be used by the admin site login view.
AdminSite.logout_template
Path to a custom template that will be used by the admin site logout view.
AdminSite.password_change_template
Path to a custom template that will be used by the admin site passwordchange view.
AdminSite.password_change_done_template
Path to a custom template that will be used by the admin site passwordchange done view.

AdminSite methods

AdminSite.eachcontext(_request)[源代码]
Returns a dictionary of variables to put in the template context forevery page in the admin site.

Includes the following variables and values by default:

site_header: AdminSite.site_header
site_title: AdminSite.site_title
site_url: AdminSite.site_url
has_permission: AdminSite.has_permission()
available_apps: a list of applications from the application registry available for the current user. Each entry in thelist is a dict representing an application with the following keys:
- app_label: the application label
- app_url: the URL of the application index in the admin
- has_module_perms: a boolean indicating if displaying and accessing ofthe module's index page is permitted for the current user
- models: a list of the models available in the application
  Each model is a dict with the following keys:
- object_name: class name of the model
- name: plural name of the model
- perms: a dict tracking add, change, delete, andview permissions
- admin_url: admin changelist URL for the model
- add_url: admin URL to add a new model instance
- AdminSite.haspermission(_request)[源代码]
- Returns True if the user for the given HttpRequest has permissionto view at least one page in the admin site. Defaults to requiring bothUser.is_active andUser.is_staff to beTrue.

AdminSite.register(model_or_iterable, admin_class=None, **options)[源代码]
Registers the given model class (or iterable of classes) with the givenadmin_class. admin_class defaults toModelAdmin (the default admin options). Ifkeyword arguments are given — e.g. list_display — they'll be appliedas options to the admin class.

Raises ImproperlyConfigured if a model isabstract. and django.contrib.admin.sites.AlreadyRegistered if a modelis already registered.

Hooking AdminSite instances into your URLconf

The last step in setting up the Django admin is to hook your AdminSiteinstance into your URLconf. Do this by pointing a given URL at theAdminSite.urls method. It is not necessary to useinclude().

In this example, we register the default AdminSite instancedjango.contrib.admin.site at the URL /admin/

# urls.py
from django.contrib import admin
from django.urls import path
 
urlpatterns = [
    path('admin/', admin.site.urls),
]

Customizing the AdminSite class

If you'd like to set up your own admin site with custom behavior, you're freeto subclass AdminSite and override or add anything you like. Then, simplycreate an instance of your AdminSite subclass (the same way you'dinstantiate any other Python class) and register your models andModelAdmin subclasses with it instead of with the default site. Finally,update myproject/urls.py to reference your AdminSite subclass.

myapp/admin.py

from django.contrib.admin import AdminSite
 
from .models import MyModel
 
class MyAdminSite(AdminSite):
    site_header = 'Monty Python administration'
 
admin_site = MyAdminSite(name='myadmin')
admin_site.register(MyModel)

myproject/urls.py

from django.urls import path
 
from myapp.admin import admin_site
 
urlpatterns = [
    path('myadmin/', admin_site.urls),
]

Note that you may not want autodiscovery of admin modules when using yourown AdminSite instance since you will likely be importing all the per-appadmin modules in your myproject.admin module. This means you need toput 'django.contrib.admin.apps.SimpleAdminConfig' instead of'django.contrib.admin' in your INSTALLED_APPS setting.

Overriding the default admin site

New in Django 2.1:

You can override the default django.contrib.admin.site by setting thedefault_site attribute of a custom AppConfigto the dotted import path of either a AdminSite subclass or a callable thatreturns a site instance.

myproject/admin.py

from django.contrib import admin
 
class MyAdminSite(admin.AdminSite):
    ...

myproject/apps.py

from django.contrib.admin.apps import AdminConfig
 
class MyAdminConfig(AdminConfig):
    default_site = 'myproject.admin.MyAdminSite'

myproject/settings.py

INSTALLED_APPS = [
    ...
    'myproject.apps.MyAdminConfig',  # replaces 'django.contrib.admin'
    ...
]

Multiple admin sites in the same URLconf

It's easy to create multiple instances of the admin site on the sameDjango-powered website. Just create multiple instances of AdminSite androot each one at a different URL.

In this example, the URLs /basic-admin/ and /advanced-admin/ featureseparate versions of the admin site — using the AdminSite instancesmyproject.admin.basic_site and myproject.admin.advanced_site,respectively:

# urls.py
from django.urls import path
from myproject.admin import advanced_site, basic_site
 
urlpatterns = [
    path('basic-admin/', basic_site.urls),
    path('advanced-admin/', advanced_site.urls),
]

AdminSite instances take a single argument to their constructor, theirname, which can be anything you like. This argument becomes the prefix to theURL names for the purposes of reversing them. Thisis only necessary if you are using more than one AdminSite.

Adding views to admin sites

Just like ModelAdmin, AdminSite provides aget_urls() methodthat can be overridden to define additional views for the site. To adda new view to your admin site, extend the baseget_urls() method to includea pattern for your new view.

注解

Any view you render that uses the admin templates, or extends the baseadmin template, should set request.current_app before rendering thetemplate. It should be set to either self.name if your view is on anAdminSite or self.admin_site.name if your view is on aModelAdmin.

Adding a password reset feature

You can add a password reset feature to the admin site by adding a few lines toyour URLconf. Specifically, add these four patterns:

from django.contrib.auth import views as auth_views
 
path(
    'admin/password_reset/',
    auth_views.PasswordResetView.as_view(),
    name='admin_password_reset',
),
path(
    'admin/password_reset/done/',
    auth_views.PasswordResetDoneView.as_view(),
    name='password_reset_done',
),
path(
    'reset/<uidb64>/<token>/',
    auth_views.PasswordResetConfirmView.as_view(),
    name='password_reset_confirm',
),
path(
    'reset/done/',
    auth_views.PasswordResetCompleteView.as_view(),
    name='password_reset_complete',
),

(This assumes you've added the admin at admin/ and requires that you putthe URLs starting with ^admin/ before the line that includes the admin appitself).

The presence of the admin_password_reset named URL will cause a "forgottenyour password?" link to appear on the default admin log-in page under thepassword box.

LogEntry objects

class models.LogEntry
The LogEntry class tracks additions, changes, and deletions of objectsdone through the admin interface.

LogEntry attributes

LogEntry.action_time
The date and time of the action.
LogEntry.user
The user (an AUTH_USER_MODEL instance) who performed theaction.
LogEntry.content_type
The ContentType of themodified object.
LogEntry.object_id
The textual representation of the modified object's primary key.
LogEntry.object_repr
The object`s repr() after the modification.
LogEntry.action_flag
The type of action logged: ADDITION, CHANGE, DELETION.

For example, to get a list of all additions done through the admin:

from django.contrib.admin.models import ADDITION, LogEntry
 
LogEntry.objects.filter(action_flag=ADDITION)

LogEntry.change_message
The detailed description of the modification. In the case of an edit, forexample, the message contains a list of the edited fields. The Django adminsite formats this content as a JSON structure, so thatget_change_message() can recompose a message translated in the currentuser language. Custom code might set this as a plain string though. You areadvised to use the get_change_message() method to retrieve this valueinstead of accessing it directly.

LogEntry methods

LogEntry.get_edited_object()
A shortcut that returns the referenced object.
LogEntry.get_change_message()
Formats and translates change_message into the current userlanguage. Messages created before Django 1.10 will always be displayed inthe language in which they were logged.

Reversing admin URLs

When an AdminSite is deployed, the views provided by that site areaccessible using Django's URL reversing system.

The AdminSite provides the following named URL patterns:

Page	URL name	Parameters
Index	`index`
Login	`login`
Logout	`logout`
Password change	`password_change`
Password change done	`password_change_done`
i18n JavaScript	`jsi18n`
Application index page	`app_list`	`app_label`
Redirect to object's page	`view_on_site`	`content_type_id`, `object_id`

Each ModelAdmin instance provides an additional set of named URLs:

Page	URL name	Parameters
Changelist	`{{ applabel }}{{ modelname }}_changelist`
Add	`{{ app_label }}{{ modelname }}_add`
History	`{{ app_label }}{{ modelname }}_history`	`object_id`
Delete	`{{ app_label }}{{ modelname }}_delete`	`object_id`
Change	`{{ app_label }}{{ model_name }}_change`	`object_id`

The UserAdmin provides a named URL:

Page	URL name	Parameters
Password change	`auth_user_password_change`	`user_id`

These named URLs are registered with the application namespace admin, andwith an instance namespace corresponding to the name of the Site instance.

So - if you wanted to get a reference to the Change view for a particularChoice object (from the polls application) in the default admin, you wouldcall:

>>> from django.urls import reverse
>>> c = Choice.objects.get(...)
>>> change_url = reverse('admin:polls_choice_change', args=(c.id,))

This will find the first registered instance of the admin application(whatever the instance name), and resolve to the view for changingpoll.Choice instances in that instance.

If you want to find a URL in a specific admin instance, provide the name ofthat instance as a current_app hint to the reverse call. For example,if you specifically wanted the admin view from the admin instance namedcustom, you would need to call:

>>> change_url = reverse('admin:polls_choice_change', args=(c.id,), current_app='custom')

For more details, see the documentation on reversing namespaced URLs.

To allow easier reversing of the admin urls in templates, Django provides anadmin_urlname filter which takes an action as argument:

{% load admin_urls %}
<a href="{% url opts|admin_urlname:'add' %}">Add user</a>
<a href="{% url opts|admin_urlname:'delete' user.pk %}">Delete this user</a>

The action in the examples above match the last part of the URL names forModelAdmin instances described above. The opts variable can be anyobject which has an app_label and model_name attributes and is usuallysupplied by the admin views for the current model.

The staff_member_required decorator

staffmember_required(_redirect_field_name='next', login_url='admin:login')[源代码]
This decorator is used on the admin views that require authorization. Aview decorated with this function will having the following behavior:
- If the user is logged in, is a staff member (User.is_staff=True), andis active (User.is_active=True), execute the view normally.
- Otherwise, the request will be redirected to the URL specified by thelogin_url parameter, with the originally requested path in a querystring variable specified by redirect_field_name. For example:/admin/login/?next=/admin/polls/question/3/.
  Example usage:

from django.contrib.admin.views.decorators import staff_member_required
 
@staff_member_required
def my_view(request):
    ...

The Django admin site

The Django admin site

Overview

Other topics

ModelAdmin objects

The register decorator

Discovery of admin files

ModelAdmin options

Custom template options

ModelAdmin methods

Other methods

ModelAdmin asset definitions

jQuery

Adding custom validation to the admin

InlineModelAdmin objects

InlineModelAdmin options

Working with a model with two or more foreign keys to the same parent model

Working with many-to-many models

Working with many-to-many intermediary models

Using generic relations as an inline

Overriding admin templates

Set up your projects admin template directories

Overriding vs. replacing an admin template

Templates which may be overridden per app or model

Root and login templates

AdminSite objects

AdminSite attributes

AdminSite methods

Hooking AdminSite instances into your URLconf

Customizing the AdminSite class

Overriding the default admin site

Multiple admin sites in the same URLconf

Adding views to admin sites

Adding a password reset feature

LogEntry objects

LogEntry attributes

LogEntry methods

Reversing admin URLs

The staff_member_required decorator