管理动作

Django 的管理员的基本工作流程，简而言之，就是“选择一个对象，然后更改它”。这对于大多数用例来说都很好用。然而，如果你需要同时对许多对象进行相同的更改，这种工作流程可能会相当乏味。

在这种情况下，Django 的管理可以让你编写和注册“动作”——即使用在变更列表页面上选择的对象列表调用的函数。

如果你在管理中查看任何变化列表，你会看到这个功能的作用；Django 自带了一个“删除选定对象”的动作，所有模型都可以使用。例如，这里是 Django 内置的用户模块 django.contrib.auth 应用：

../../../_images/admin-actions.png

警告

“删除选定对象”动作使用 QuerySet.delete() 为了提高效率，它有一个重要的注意事项：你的模型的 delete() 方法将不会被调用。

如果你想覆盖这个行为，你可以覆盖 ModelAdmin.delete_queryset() 或者写一个自定义的动作，以你喜欢的方式进行删除 -- 例如，通过为每个选定的项目调用 Model.delete()。

关于批量删除的更多背景，请参见 对象删除 的文档。

请继续阅读，了解如何将自己的动作添加到此列表中。

编写动作

The easiest way to explain actions is by example, so let's dive in.

A common use case for admin actions is the bulk updating of a model. Imagine a news application with an Article model:

from django.db import models

STATUS_CHOICES = [
    ('d', 'Draft'),
    ('p', 'Published'),
    ('w', 'Withdrawn'),
]

class Article(models.Model):
    title = models.CharField(max_length=100)
    body = models.TextField()
    status = models.CharField(max_length=1, choices=STATUS_CHOICES)

    def __str__(self):
        return self.title

A common task we might perform with a model like this is to update an article's status from "draft" to "published". We could easily do this in the admin one article at a time, but if we wanted to bulk-publish a group of articles, it'd be tedious. So, let's write an action that lets us change an article's status to "published."

编写动作函数

First, we'll need to write a function that gets called when the action is triggered from the admin. Action functions are regular functions that take three arguments:

Our publish-these-articles function won't need the ModelAdmin or the request object, but we will use the queryset:

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')

注解

For the best performance, we're using the queryset's update method. Other types of actions might need to deal with each object individually; in these cases we'd iterate over the queryset:

for obj in queryset:
    do_something_with(obj)

That's actually all there is to writing an action! However, we'll take one more optional-but-useful step and give the action a "nice" title in the admin. By default, this action would appear in the action list as "Make published" -- the function name, with underscores replaced by spaces. That's fine, but we can provide a better, more human-friendly name by giving the make_published function a short_description attribute:

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.short_description = "Mark selected stories as published"

注解

This might look familiar; the admin's list_display option uses the same technique to provide human-readable descriptions for callback functions registered there, too.

在 ModelAdmin 中添加动作

Next, we'll need to inform our ModelAdmin of the action. This works just like any other configuration option. So, the complete admin.py with the action and its registration would look like:

from django.contrib import admin
from myapp.models import Article

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.short_description = "Mark selected stories as published"

class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title', 'status']
    ordering = ['title']
    actions = [make_published]

admin.site.register(Article, ArticleAdmin)

That code will give us an admin change list that looks something like this:

../../../_images/adding-actions-to-the-modeladmin.png

That's really all there is to it! If you're itching to write your own actions, you now know enough to get started. The rest of this document covers more advanced techniques.

处理动作中的错误

If there are foreseeable error conditions that may occur while running your action, you should gracefully inform the user of the problem. This means handling exceptions and using django.contrib.admin.ModelAdmin.message_user() to display a user friendly description of the problem in the response.

进阶动作技巧

There's a couple of extra options and possibilities you can exploit for more advanced options.

作为 ModelAdmin 方法的动作

The example above shows the make_published action defined as a function. That's perfectly fine, but it's not perfect from a code design point of view: since the action is tightly coupled to the Article object, it makes sense to hook the action to the ArticleAdmin object itself.

You can do it like this:

class ArticleAdmin(admin.ModelAdmin):
    ...

    actions = ['make_published']

    def make_published(self, request, queryset):
        queryset.update(status='p')
    make_published.short_description = "Mark selected stories as published"

Notice first that we've moved make_published into a method and renamed the modeladmin parameter to self, and second that we've now put the string 'make_published' in actions instead of a direct function reference. This tells the ModelAdmin to look up the action as a method.

Defining actions as methods gives the action more idiomatic access to the ModelAdmin itself, allowing the action to call any of the methods provided by the admin.

For example, we can use self to flash a message to the user informing them that the action was successful:

from django.contrib import messages
from django.utils.translation import ngettext

class ArticleAdmin(admin.ModelAdmin):
    ...

    def make_published(self, request, queryset):
        updated = queryset.update(status='p')
        self.message_user(request, ngettext(
            '%d story was successfully marked as published.',
            '%d stories were successfully marked as published.',
            updated,
        ) % updated, messages.SUCCESS)

This make the action match what the admin itself does after successfully performing an action:

../../../_images/actions-as-modeladmin-methods.png

提供中间页的动作

By default, after an action is performed the user is redirected back to the original change list page. However, some actions, especially more complex ones, will need to return intermediate pages. For example, the built-in delete action asks for confirmation before deleting the selected objects.

To provide an intermediary page, return an HttpResponse (or subclass) from your action. For example, you might write an export function that uses Django's serialization functions to dump some selected objects as JSON:

from django.core import serializers
from django.http import HttpResponse

def export_as_json(modeladmin, request, queryset):
    response = HttpResponse(content_type="application/json")
    serializers.serialize("json", queryset, stream=response)
    return response

Generally, something like the above isn't considered a great idea. Most of the time, the best practice will be to return an HttpResponseRedirect and redirect the user to a view you've written, passing the list of selected objects in the GET query string. This allows you to provide complex interaction logic on the intermediary pages. For example, if you wanted to provide a more complete export function, you'd want to let the user choose a format, and possibly a list of fields to include in the export. The best thing to do would be to write a small action that redirects to your custom export view:

from django.contrib.contenttypes.models import ContentType
from django.http import HttpResponseRedirect

def export_selected_objects(modeladmin, request, queryset):
    selected = queryset.values_list('pk', flat=True)
    ct = ContentType.objects.get_for_model(queryset.model)
    return HttpResponseRedirect('/export/?ct=%s&ids=%s' % (
        ct.pk,
        ','.join(str(pk) for pk in selected),
    ))

As you can see, the action is rather short; all the complex logic would belong in your export view. This would need to deal with objects of any type, hence the business with the ContentType.

Writing this view is left as an exercise to the reader.

在整个网站上提供动作

AdminSite.add_action(action, name=None)

Some actions are best if they're made available to any object in the admin site -- the export action defined above would be a good candidate. You can make an action globally available using AdminSite.add_action(). For example:

from django.contrib import admin

admin.site.add_action(export_selected_objects)

This makes the export_selected_objects action globally available as an action named "export_selected_objects". You can explicitly give the action a name -- good if you later want to programmatically remove the action -- by passing a second argument to AdminSite.add_action():

admin.site.add_action(export_selected_objects, 'export_selected')

Disabling actions

Sometimes you need to disable certain actions -- especially those registered site-wide -- for particular objects. There's a few ways you can disable actions:

禁用全站点动作

AdminSite.disable_action(name)

If you need to disable a site-wide action you can call AdminSite.disable_action().

For example, you can use this method to remove the built-in "delete selected objects" action:

admin.site.disable_action('delete_selected')

Once you've done the above, that action will no longer be available site-wide.

If, however, you need to re-enable a globally-disabled action for one particular model, list it explicitly in your ModelAdmin.actions list:

# Globally disable delete selected
admin.site.disable_action('delete_selected')

# This ModelAdmin will not have delete_selected available
class SomeModelAdmin(admin.ModelAdmin):
    actions = ['some_other_action']
    ...

# This one will
class AnotherModelAdmin(admin.ModelAdmin):
    actions = ['delete_selected', 'a_third_action']
    ...

禁用特定 ModelAdmin 的所有动作

If you want no bulk actions available for a given ModelAdmin, set ModelAdmin.actions to None:

class MyModelAdmin(admin.ModelAdmin):
    actions = None

This tells the ModelAdmin to not display or allow any actions, including any site-wide actions.

有条件地启用或禁用动作

ModelAdmin.get_actions(request)

Finally, you can conditionally enable or disable actions on a per-request (and hence per-user basis) by overriding ModelAdmin.get_actions().

This returns a dictionary of actions allowed. The keys are action names, and the values are (function, name, short_description) tuples.

For example, if you only want users whose names begin with 'J' to be able to delete objects in bulk:

class MyModelAdmin(admin.ModelAdmin):
    ...

    def get_actions(self, request):
        actions = super().get_actions(request)
        if request.user.username[0].upper() != 'J':
            if 'delete_selected' in actions:
                del actions['delete_selected']
        return actions

设置动作的权限

Actions may limit their availability to users with specific permissions by setting an allowed_permissions attribute on the action function:

def make_published(modeladmin, request, queryset):
    queryset.update(status='p')
make_published.allowed_permissions = ('change',)

The make_published() action will only be available to users that pass the ModelAdmin.has_change_permission() check.

If allowed_permissions has more than one permission, the action will be available as long as the user passes at least one of the checks.

Available values for allowed_permissions and the corresponding method checks are:

You can specify any other value as long as you implement a corresponding has_<value>_permission(self, request) method on the ModelAdmin.

例子：

from django.contrib import admin
from django.contrib.auth import get_permission_codename

class ArticleAdmin(admin.ModelAdmin):
    actions = ['make_published']

    def make_published(self, request, queryset):
        queryset.update(status='p')
    make_published.allowed_permissions = ('publish',)

    def has_publish_permission(self, request):
        """Does the user have the publish permission?"""
        opts = self.opts
        codename = get_permission_codename('publish', opts)
        return request.user.has_perm('%s.%s' % (opts.app_label, codename))
« previous | up | next »