Django 1.8.2  文档

消息框架

在网页应用中,你经常需要在处理完表单或其它类型的用户输入后,显示一个通知消息(也叫做“flash message”)给用户。

对于这个功能,Django 提供基于Cookie 和会话的消息,无论是匿名用户还是认证的用户。其消息框架允许你临时将消息存储在请求中,并在接下来的请求(通常就是下一个请求)中提取它们并显示。每个消息都带有一个特定level 标签,表示其优先级(例如infowarningerror)。

启用消息框架

消息框架的实现通过一个中间件 类和对应的context processor

django-admin startproject 创建的默认settings.py  已经包含启用消息框架功能需要的所有的设置:

  • INSTALLED_APPS 中的'django.contrib.messages'

  • MIDDLEWARE_CLASSES 中的'django.contrib.sessions.middleware.SessionMiddleware''django.contrib.messages.middleware.MessageMiddleware'

    默认的后端存储 依赖sessions所以MIDDLEWARE_CLASSES 中必须启用SessionMiddleware 并出现在MessageMiddleware 之前。

  • TEMPLATES 设置中定义的DjangoTemplates'context_processors' 选项包含 'django.contrib.messages.context_processors.messages'

如果你不想使用消息框架,你可以删除INSTALLED_APPS 中的 'django.contrib.messages'MIDDLEWARE_CLASSES 中的MessageMiddlewareTEMPLATES 中的messages context processor。

配置消息框架引擎

后台存储

消息框架可以使用不同的后台存储临时消息。

Django 在django.contrib.messages 中提供三个内建的存储类:

class storage.session.SessionStorage

这个类存储所有的消息于请求的会话中。因此,它要求启用Django 的contrib.sessions 应用。

class storage.cookie.CookieStorage

这个类存储消息数据于与Cookie 中(已经用一个安全的哈希进行签名以防止篡改)以在请求之间传递消息。如果Cookie 数据的大小将超过2048 字节,将丢弃旧的消息。

class storage.fallback.FallbackStorage

这个类首先使用CookieStorage,如果消息塞不进一个Cookie 中则使用SessionStorage它同样要求启用Django 的contrib.sessions 应用。

这个行为避免每次都写会话。在通常情况下,它提供的性能应该是最好的。

FallbackStorage 是默认的存储类。如果它不适合你的需要,你可以通过设置 MESSAGE_STORAGE 为它的完整导入路径选择另外一个存储类,例如:

MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'
class storage.base.BaseStorage

如果想编写你自己的存储类,子类化django.contrib.messages.storage.base 中的BaseStorage 类并实现_get_store 方法。

消息级别

消息框架的级别是可配置的,与Python logging 模块类似。消息的级别可以让你根据类型进行分组,这样它们能够在不同的视图和模板中过滤或显示出来。

可以直接从django.contrib.messages 导入的内建级别有:

Constant Purpose
DEBUG Development-related messages that will be ignored (or removed) in a production deployment
INFO Informational messages for the user
SUCCESS An action was successful, e.g. “Your profile was updated successfully”
WARNING A failure did not occur but may be imminent
ERROR An action was not successful or some other failure occurred

MESSAGE_LEVEL 设置可以用来改变记录的最小级别(它还可以在每个请求中修改)。小于这个级别的消息将被忽略。

消息的标签

消息的标签是一个字符串,表示消息的级别以及在视图中添加的其它标签(参见下文添加额外的消息标签)。标签存储在字符串中并通过空格分隔。通常情况下,消息的标签用于作为CSS 类来根据消息的类型定制消息的风格。默认情况下,每个级别具有一个标签,为其级别的字符串常量的小写:

Level Constant Tag
DEBUG debug
INFO info
SUCCESS success
WARNING warning
ERROR error

若要修改消息级别的默认标签,设置MESSAGE_TAGS为包含你想要修改的级别的字典。As this extends the default tags, you only need to provide tags for the levels you wish to override:

from django.contrib.messages import constants as messages
MESSAGE_TAGS = {
    messages.INFO: '',
    50: 'critical',
}

在视图和模板中使用消息

add_message(request, level, message, extra_tags='', fail_silently=False)

新增一条消息

新增一条消息,调用:

from django.contrib import messages
messages.add_message(request, messages.INFO, 'Hello world.')

有几个快捷方法提供标准的方式来新增消息并带有常见的标签(这些标签通常表示消息的HTML 类型):

messages.debug(request, '%s SQL statements were executed.' % count)
messages.info(request, 'Three credits remain in your account.')
messages.success(request, 'Profile details updated.')
messages.warning(request, 'Your account expires in three days.')
messages.error(request, 'Document deleted.')

显示消息

get_messages(request)

在你的模板中,像下面这样使用:

{% if messages %}
<ul class="messages">
    {% for message in messages %}
    <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>{{ message }}</li>
    {% endfor %}
</ul>
{% endif %}

如果你正在使用context processor,你的模板应该通过 RequestContext 渲染。否则,需要确保messages 在模板的Context 中可以访问。

即使你知道只有一条消息,你也应该仍然迭代messages 序列,否则下个请求中的消息不会被清除。

New in Django 1.7.

Context processor 还提供一个DEFAULT_MESSAGE_LEVELS 变量,它映射消息级别的名称到它们的数值:

{% if messages %}
<ul class="messages">
    {% for message in messages %}
    <li{% if message.tags %} class="{{ message.tags }}"{% endif %}>
        {% if message.level == DEFAULT_MESSAGE_LEVELS.ERROR %}Important: {% endif %}
        {{ message }}
    </li>
    {% endfor %}
</ul>
{% endif %}

在模板的外面,你可以使用get_messages()

from django.contrib.messages import get_messages

storage = get_messages(request)
for message in storage:
    do_something_with_the_message(message)

例如,你可以获取所有的消息并在JSONResponseMixin 而不是TemplateResponseMixin 中返回它们。

get_messages() 将返回配置的存储后台的一个实例。

TheMessage

class storage.base.Message

当浏览某个模板的消息列表时,你得到的其实是Message 类的实例。它只是一个非常简单、只带很少属性的对象:

  • message: 消息的实际内容文本。
  • level: 一个整数,它描述了消息的类型 (请参阅上面 message levels一节).
  • tags: 一个字符串,它由该消息的所有标签 (extra_tagslevel_tag)组合而成,组合时用空格分割开这些标签。
  • extra_tags: 一个字符串,它由该消息的定制标签组合而成,并用空格分割。缺省为空。
New in Django 1.7.
  • level_tag: 代表该消息级别的字符串。该属性缺省由小写的关联常数名组成, 但当设置MESSAGE_TAGS参数时,可改变该规则。

Creating custom message levels

Messages levels are nothing more than integers, so you can define your own level constants and use them to create more customized user feedback, e.g.:

CRITICAL = 50

def my_view(request):
    messages.add_message(request, CRITICAL, 'A serious error occurred.')

When creating custom message levels you should be careful to avoid overloading existing levels. The values for the built-in levels are:

Level Constant Value
DEBUG 10
INFO 20
SUCCESS 25
WARNING 30
ERROR 40

If you need to identify the custom levels in your HTML or CSS, you need to provide a mapping via the MESSAGE_TAGS setting.

Note

If you are creating a reusable application, it is recommended to use only the built-in message levels and not rely on any custom levels.

在每个请求中修改最小的记录级别

每个请求都可以通过 set_level方法设置最小记录级别:

from django.contrib import messages

# Change the messages level to ensure the debug message is added.
messages.set_level(request, messages.DEBUG)
messages.debug(request, 'Test message...')

# In another request, record only messages with a level of WARNING and higher
messages.set_level(request, messages.WARNING)
messages.success(request, 'Your profile was updated.') # ignored
messages.warning(request, 'Your account is about to expire.') # recorded

# Set the messages level back to default.
messages.set_level(request, None)

与此相似,当前有效的记录级别可以用get_level方法获取:

from django.contrib import messages
current_level = messages.get_level(request)

有关最小记录级别相关的函数信息,请参阅上面 Message levels 一节.

Adding extra message tags

For more direct control over message tags, you can optionally provide a string containing extra tags to any of the add methods:

messages.add_message(request, messages.INFO, 'Over 9000!',
                     extra_tags='dragonball')
messages.error(request, 'Email box full', extra_tags='email')

Extra tags are added before the default tag for that level and are space separated.

当消息框架被禁止时,失败静悄悄

如果您撰写的是可重复使用的应用程式(或其他碎片代码),但想要包含讯息功能,但又不想要您的使用者启用(如果他们不想使用),您可以传送额外的关键字参数 fail_silently = True指向任何add_message方法系列。举个例子

messages.add_message(request, messages.SUCCESS, 'Profile details updated.',
                     fail_silently=True)
messages.info(request, 'Hello world.', fail_silently=True)

Note

Setting fail_silently=True only hides the MessageFailure that would otherwise occur when the messages framework disabled and one attempts to use one of the add_message family of methods. It does not hide failures that may occur for other reasons.

在基于类的视图中添加消息

class views.SuccessMessageMixin

向基于FormView 的类添加一条成功的消息

get_success_message(cleaned_data)

cleaned_data 是表单中的清洁数据,用于字符串格式化

示例 views.py

from django.contrib.messages.views import SuccessMessageMixin
from django.views.generic.edit import CreateView
from myapp.models import Author

class AuthorCreate(SuccessMessageMixin, CreateView):
    model = Author
    success_url = '/success/'
    success_message = "%(name)s was created successfully"

字符串插值可以使用%(field_name)s 语法访问form 中的清洁数据。对于ModelForms,如果你需要访问保存的object 中的字段,可以覆盖get_success_message() 方法。

ModelForms 的示例views.py

from django.contrib.messages.views import SuccessMessageMixin
from django.views.generic.edit import CreateView
from myapp.models import ComplicatedModel

class ComplicatedCreate(SuccessMessageMixin, CreateView):
    model = ComplicatedModel
    success_url = '/success/'
    success_message = "%(calculated_field)s was created successfully"

    def get_success_message(self, cleaned_data):
        return self.success_message % dict(cleaned_data,
                                           calculated_field=self.object.calculated_field)

Expiration of messages

The messages are marked to be cleared when the storage instance is iterated (and cleared when the response is processed).

To avoid the messages being cleared, you can set the messages storage to False after iterating:

storage = messages.get_messages(request)
for message in storage:
    do_something_with(message)
storage.used = False

Behavior of parallel requests

Due to the way cookies (and hence sessions) work, the behavior of any backends that make use of cookies or sessions is undefined when the same client makes multiple requests that set or get messages in parallel. For example, if a client initiates a request that creates a message in one window (or tab) and then another that fetches any uniterated messages in another window, before the first window redirects, the message may appear in the second window instead of the first window where it may be expected.

In short, when multiple simultaneous requests from the same client are involved, messages are not guaranteed to be delivered to the same window that created them nor, in some cases, at all. Note that this is typically not a problem in most applications and will become a non-issue in HTML5, where each window/tab will have its own browsing context.

设置

A few settings give you control over message behavior:

New in Django 1.7.

For backends that use cookies, the settings for the cookie are taken from the session cookie settings: