管理动作

简而言之，Django 管理员的基本工作流程是“选择一个对象，然后更改它”。这适用于大多数用例。但是，如果您需要一次对许多对象进行相同的更改，则此工作流程可能会非常乏味。

在这些情况下，Django 的管理员允许您编写和注册“动作”——简单的函数，这些函数使用在更改列表页面上选择的对象列表来调用。

如果您查看管理中的任何更改列表，您将看到此功能正在运行； Django 附带了对所有模型都可用的“删除选定对象”操作。例如，这是来自 Django 内置 django.contrib.auth 应用程序的用户模块：

[[../File:../../../_images/admin-actions|../../../_images/admin-actions.png]]

警告

出于效率原因，“删除选定对象”操作使用 QuerySet.delete()，这有一个重要的警告：您的模型的 delete() 方法将不会被调用。

如果您希望覆盖此行为，您可以覆盖 ModelAdmin.delete_queryset() 或编写一个自定义操作，以您喜欢的方式进行删除 - 例如，通过为每个调用 Model.delete()选定的项目。

有关批量删除的更多背景信息，请参阅有关对象删除的文档。

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

编写动作

解释动作的最简单方法是举例，所以让我们深入研究。

管理操作的一个常见用例是模型的批量更新。想象一个带有 Article 模型的简单新闻应用程序：

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

我们可能使用这样的模型执行的一项常见任务是将文章的状态从“草稿”更新为“已发布”。我们可以轻松地在管理中一次完成一篇文章，但如果我们想批量发布一组文章，那就很乏味了。因此，让我们编写一个动作，让我们将文章的状态更改为“已发布”。

编写动作函数

首先，我们需要编写一个函数，当管理员触发操作时调用该函数。动作函数只是带有三个参数的常规函数：

当前的 ModelAdmin
一个 HttpRequest 代表当前请求，
QuerySet 包含用户选择的对象集。

我们的发布这些文章功能不需要 ModelAdmin 或请求对象，但我们将使用查询集：

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

笔记

为了获得最佳性能，我们使用查询集的更新方法。其他类型的操作可能需要单独处理每个对象；在这些情况下，我们只需遍历查询集：

for obj in queryset:
    do_something_with(obj)

这实际上就是编写动作的全部内容！但是，我们将采取另一个可选但有用的步骤，并在管理中为该操作提供一个“漂亮”的标题。默认情况下，此操作将在操作列表中显示为“发布” - 函数名称，下划线替换为空格。这很好，但我们可以通过给 make_published 函数一个 short_description 属性来提供一个更好、更人性化的名称：

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

笔记

这可能看起来很熟悉；管理员的 list_display 选项也使用相同的技术为在那里注册的回调函数提供人类可读的描述。

向 ModelAdmin 添加动作

接下来，我们需要将操作通知我们的 ModelAdmin。这就像任何其他配置选项一样工作。因此，带有操作及其注册的完整 admin.py 将如下所示：

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)

这段代码会给我们一个管理变更列表，看起来像这样：

[[../File:../../../_images/adding-actions-to-the-modeladmin|../../../_images/adding-actions-to-the-modeladmin.png]] 这就是它的全部内容！如果您渴望编写自己的操作，那么您现在已经足够了解可以开始使用了。本文档的其余部分仅涵盖更高级的技术。

处理动作中的错误

如果在运行您的操作时可能发生可预见的错误情况，您应该优雅地将问题告知用户。这意味着处理异常并使用 django.contrib.admin.ModelAdmin.message_user() 在响应中显示用户友好的问题描述。

进阶动作技巧

您可以利用一些额外的选项和可能性来获得更高级的选项。

作为 ModelAdmin 方法的操作

上面的示例显示了定义为简单函数的 make_published 操作。这很好，但从代码设计的角度来看并不完美：由于动作与 Article 对象紧密耦合，因此将动作挂钩到 ArticleAdmin 对象本身是有意义的。

这很容易做到：

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"

首先请注意，我们已将 make_published 移动到一个方法中并将 modeladmin 参数重命名为 self，其次我们现在已将字符串 'make_published'在 actions 中，而不是直接的函数引用。这告诉 ModelAdmin 将操作作为方法查找。

将动作定义为方法可以让动作更直接、更惯用地访问 ModelAdmin 本身，允许动作调用管理员提供的任何方法。

例如，我们可以使用 self 向用户闪现一条消息，通知她操作成功：

class ArticleAdmin(admin.ModelAdmin):
    ...

    def make_published(self, request, queryset):
        rows_updated = queryset.update(status='p')
        if rows_updated == 1:
            message_bit = "1 story was"
        else:
            message_bit = "%s stories were" % rows_updated
        self.message_user(request, "%s successfully marked as published." % message_bit)

这就使得在成功执行一个动作后，该动作与管理本身所做的动作相匹配。

[[../File:../../../_images/actions-as-modeladmin-methods|../../../_images/actions-as-modeladmin-methods.png]]

提供中间页的动作

默认情况下，执行操作后，用户会被简单地重定向回原始更改列表页面。但是，某些操作，尤其是更复杂的操作，将需要返回中间页面。例如，内置的删除操作会在删除所选对象之前要求确认。

要提供中间页面，只需从您的操作中返回 HttpResponse（或子类）。例如，您可以编写一个简单的导出函数，它使用 Django 的序列化函数将一些选定的对象转储为 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

一般来说，像上面这样的东西不被认为是一个好主意。大多数情况下，最佳实践是返回 HttpResponseRedirect 并将用户重定向到您编写的视图，在 GET 查询字符串中传递所选对象的列表。这允许您在中间页面上提供复杂的交互逻辑。例如，如果您想提供更完整的导出功能，您希望让用户选择一种格式，可能还有一个要包含在导出中的字段列表。最好的办法是编写一个小动作，简单地重定向到您的自定义导出视图：

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

如您所见，动作是简单的部分；所有复杂的逻辑都属于您的导出视图。这将需要处理任何类型的对象，因此涉及 ContentType 的业务。

如何编写这个视图，就留给读者去练习。

在整个站点提供动作

AdminSite.add_action(action, name=None)

如果某些操作可用于管理站点中的任何对象，则它们是最好的——上面定义的导出操作将是一个很好的候选者。您可以使用 AdminSite.add_action() 使操作全局可用。例如：

from django.contrib import admin

admin.site.add_action(export_selected_objects)

这使得 export_selected_objects 操作作为名为“export_selected_objects”的操作全局可用。您可以通过将第二个参数传递给 AdminSite.add_action() 来明确地为操作命名——如果您以后想以编程方式删除操作，那这很好：

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

禁用动作

有时您需要为特定对象禁用某些操作——尤其是那些注册站点范围。有几种方法可以禁用操作：

禁用全站点动作

AdminSite.disable_action(name)

如果您需要禁用站点范围的操作，您可以调用 AdminSite.disable_action()。

例如，您可以使用此方法删除内置的“删除选定对象”操作：

admin.site.disable_action('delete_selected')

完成上述操作后，该操作将不再适用于整个站点。

但是，如果您需要为某个特定模型重新启用全局禁用的操作，只需在 ModelAdmin.actions 列表中明确列出它：

# 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 的所有操作

如果您希望 no 批量操作可用于给定的 ModelAdmin，只需将 ModelAdmin.actions 设置为 None：

class MyModelAdmin(admin.ModelAdmin):
    actions = None

这告诉 ModelAdmin 不显示或不允许任何操作，包括任何站点范围的操作。

有条件地启用或禁用动作

ModelAdmin.get_actions(request)

最后，您可以通过覆盖 ModelAdmin.get_actions() 来有条件地启用或禁用针对每个请求（因此也基于每个用户）的操作。

这将返回一个允许操作的字典。键是动作名称，值是 (function, name, short_description) 元组。

例如，如果您只希望名称以“J”开头的用户能够批量删除对象：

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

设置动作的权限

2.1 版中的新功能。

通过在动作函数上设置 allowed_permissions 属性，动作可以限制具有特定权限的用户的可用性：

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

make_published() 操作仅对通过 ModelAdmin.has_change_permission() 检查的用户可用。

如果 allowed_permissions 拥有多个权限，则只要用户通过至少一项检查，该操作就可用。

allowed_permissions 的可用值和相应的方法检查是：

'add': ModelAdmin.has_add_permission()
'change': ModelAdmin.has_change_permission()
'delete'：ModelAdmin.has_delete_permission()
'view'：ModelAdmin.has_view_permission()

您可以指定任何其他值，只要您在 ModelAdmin 上实现相应的 has_<value>_permission(self, request) 方法即可。

例如：

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

管理员操作 — Django 文档

目录