GET 和 POST

处理表单时候只会用到GET 和 POST 方法。

Django 的登录表单使用POST 方法，在这个方法中浏览器组合表单数据、对它们进行编码以用于传输、将它们发送到服务器然后接收它的响应。

相反，GET 组合提交的数据为一个字符串，然后使用它来生成一个URL。这个URL 将包含数据发送的地址以及数据的键和值。如果你在Django 文档中做一次搜索，你会立即看到这点，此时将生成一个https://docs.djangoproject.com/search/?q=forms&release=1 形式的URL。

GET 和POST 用于不同的目的。

用于改变系统状态的请求 —— 例如，给数据库带来变化的请求 —— 应该使用POST。GET 只应该用于不会影响系统状态的请求。

GET 还不适合密码表单，因为密码将出现在URL 中，以及浏览器的历史和服务器的日志中，而且都是以普通的文本格式。它还不适合数据量大的表单和二进制数据，例如一张图片。使用GET 请求作为管理站点的表单具有安全隐患：攻击者很容易模拟表单请求来取得系统的敏感数据。POST，如果与其它的保护措施结合将对访问提供更多的控制，例如Django 的CSRF 保护。

另一个方面，GET 适合网页搜索这样的表单，因为这种表示一个GET 请求的URL 可以很容易地作为书签、分享和重新提交。

Django 的Form 类

表单系统的核心部分是Django 的Form 类。Django 的模型描述一个对象的逻辑结构、行为以及展现给我们的方式，与此类似，Form 类描述一个表单并决定它如何工作和展现。

就像模型类的属性映射到数据库的字段一样，表单类的字段会映射到HTML 的<input>表单的元素。（ModelForm 通过一个Form 映射模型类的字段到HTML 表单的<input> 元素；Django 的Admin 站点就是基于这个）。

表单的字段本身也是类；它们管理表单的数据并在表单提交时进行验证。DateField 和FileField 处理的数据类型差别很大，必须完成不同的事情。

表单字段在浏览器中呈现给用户的是一个HTML 的“widget”  —— 用户界面的一个片段。每个字段类型都有一个合适的默认Widget 类，需要时可以覆盖。

实例化、处理和渲染表单

在Django 中渲染一个对象时，我们通常：

1. 在视图中获得它（例如，从数据库中获取）
2. 将它传递给模板上下文
3. 使用模板变量将它扩展为HTML 标记

在模板中渲染表单和渲染其它类型的对象几乎一样，除了几个关键的差别。

在模型实例不包含数据的情况下，在模板中对它做处理很少有什么用处。但是渲染一个未填充的表单却非常有意义 —— 我们希望用户去填充它。

所以当我们在视图中处理模型实例时，我们一般从数据库中获取它。当我们处理表单时，我们一般在视图中实例化它。

当我们实例化表单时，我们可以选择让它为空还是预先填充它，例如使用：

• 来自一个保存后的模型实例的数据（例如用于编辑的管理表单）
• 我们从其它地方获得的数据
• 从前面一个HTML 表单提交过来的数据

最后一种情况最令人关注，因为它使得用户可以不只是阅读一个网站，而且可以给网站返回信息。

需要完成的工作

假设你想在你的网站上创建一个简单的表单，以获得用户的名字。你需要类似这样的模板：

<form action="/your-name/" method="post">

    <label for="your_name">Your name: </label>

    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">

    <input type="submit" value="OK">

</form>

这告诉浏览器发送表单的数据到URL /your-name/，并使用POST 方法。它将显示一个标签为"Your name:"的文本字段，和一个"OK"按钮。如果模板上下文包含一个current_name 变量，它将用于预填充your_name 字段。

你将需要一个视图来渲染这个包含HTML 表单的模板，并提供合适的current_name 字段。

当表单提交时，发往服务器的POST 请求将包含表单数据。

现在你还需要一个对应/your-name/ URL 的视图，它在请求中找到正确的键/值对，然后处理它们。

这是一个非常简单的表单。实际应用中，一个表单可能包含几十上百个字段，其中大部分需要预填充，而且我们预料到用户将来回编辑-提交几次才能完成操作。

我们可能需要在表单提交之前，在浏览器端作一些验证。我们可能想使用非常复杂的字段，以允许用户做类似从日历中挑选日期这样的事情，等等。

这个时候，让Django 来为我们完成大部分工作是很容易的。

在Django 中构建一个表单

from django import forms

class NameForm(forms.Form):

    your_name = forms.CharField(label='Your name', max_length=100)

<label for="your_name">Your name: </label>

<input id="your_name" type="text" name="your_name" maxlength="100">

from django.shortcuts import render

from django.http import HttpResponseRedirect

from .forms import NameForm

def get_name(request):

    # if this is a POST request we need to process the form data

    if request.method == 'POST':

        # create a form instance and populate it with data from the request:

        form = NameForm(request.POST)

        # check whether it's valid:

        if form.is_valid():

            # process the data in form.cleaned_data as required

            # ...

            # redirect to a new URL:

            return HttpResponseRedirect('/thanks/')

    # if a GET (or any other method) we'll create a blank form

    else:

        form = NameForm()

    return render(request, 'name.html', {'form': form})

<form action="/your-name/" method="post">

    {% csrf_token %}

    {{ form }}

    <input type="submit" value="Submit" />

</form>

模型和表单

实际上，如果你的表单打算直接用来添加和编辑Django 的模型，ModelForm 可以节省你的许多时间、精力和代码，因为它将根据Model 类构建一个表单以及适当的字段和属性。

绑定的和未绑定的表单实例

绑定的和未绑定的表单 之间的区别非常重要：

• 未绑定的表单没有关联的数据。当渲染给用户时，它将为空或包含默认的值。
• 绑定的表单具有提交的数据，因此可以用来检验数据是否合法。如果渲染一个不合法的绑定的表单，它将包含内联的错误信息，告诉用户如何纠正数据。

表单的is_bound 属性将告诉你一个表单是否具有绑定的数据。

字段详解

考虑一个比上面的迷你示例更有用的一个表单，我们可以用它来在一个个人网站上实现“contact me”功能：

from django import forms

class ContactForm(forms.Form):

    subject = forms.CharField(max_length=100)

    message = forms.CharField(widget=forms.Textarea)

    sender = forms.EmailField()

    cc_myself = forms.BooleanField(required=False)

我们前面的表单只使用一个字段your_name，它是一个CharField。在这个例子中，我们的表单具有四个字段：subject、message、sender 和cc_myself。共用到三种字段类型：CharField、EmailField 和 BooleanField；完整的字段类型列表可以在表单字段中找到。

from django.core.mail import send_mail

if form.is_valid():

    subject = form.cleaned_data['subject']

    message = form.cleaned_data['message']

    sender = form.cleaned_data['sender']

    cc_myself = form.cleaned_data['cc_myself']

    recipients = ['info@example.com']

    if cc_myself:

        recipients.append(sender)

    send_mail(subject, message, sender, recipients)

    return HttpResponseRedirect('/thanks/')

表单渲染的选项

对于<label>/<input> 对，还有几个输出选项：

• {{ form.as_table }} 以表格的形式将它们渲染在<tr> 标签中
• {{ form.as_p }}  将它们渲染在<p> 标签中
• {{ form.as_ul }} 将它们渲染在<li> 标签中

注意，你必须自己提供<table> 或<ul> 元素。

下面是我们的ContactForm 实例的输出{{ form.as_p }}：

<p><label for="id_subject">Subject:</label>

    <input id="id_subject" type="text" name="subject" maxlength="100" /></p>

<p><label for="id_message">Message:</label>

    <input type="text" name="message" id="id_message" /></p>

<p><label for="id_sender">Sender:</label>

    <input type="email" name="sender" id="id_sender" /></p>

<p><label for="id_cc_myself">Cc myself:</label>

    <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>

注意，每个表单字段具有一个ID 属性并设置为id_<field-name>，它被一起的label 标签引用。它对于确保屏幕阅读软件这类的辅助计算非常重要。你还可以自定义label 和 id 生成的方式。

更多信息参见 输出表单为HTML。

手工渲染字段

我们没有必要非要让Django 来分拆表单的字段；如果我们喜欢，我们可以手工来做（例如，这样允许重新对字段排序）。每个字段都是表单的一个属性，可以使用{{ form.name_of_field }} 访问，并将在Django 模板中正确地渲染。例如：

{{ form.non_field_errors }}

<div class="fieldWrapper">

    {{ form.subject.errors }}

    <label for="{{ form.subject.id_for_label }}">Email subject:</label>

    {{ form.subject }}

</div>

<div class="fieldWrapper">

    {{ form.message.errors }}

    <label for="{{ form.message.id_for_label }}">Your message:</label>

    {{ form.message }}

</div>

<div class="fieldWrapper">

    {{ form.sender.errors }}

    <label for="{{ form.sender.id_for_label }}">Your email address:</label>

    {{ form.sender }}

</div>

<div class="fieldWrapper">

    {{ form.cc_myself.errors }}

    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>

    {{ form.cc_myself }}

</div>

完整的<label> 元素还可以使用label_tag() 生成。例如：

<div class="fieldWrapper">

    {{ form.subject.errors }}

    {{ form.subject.label_tag }}

    {{ form.subject }}

</div>

<ul class="errorlist">

    <li>Sender is required.</li>

</ul>

{% if form.subject.errors %}

    <ol>

    {% for error in form.subject.errors %}

        <li><strong>{{ error|escape }}</strong></li>

    {% endfor %}

    </ol>

{% endif %}

<ul class="errorlist nonfield">

    <li>Generic validation error</li>

</ul>

迭代表单的字段

如果你为你的表单使用相同的HTML，你可以使用{% for %} 循环迭代每个字段来减少重复的代码：

{% for field in form %}

    <div class="fieldWrapper">

        {{ field.errors }}

        {{ field.label_tag }} {{ field }}

    </div>

{% endfor %}

{{ field }} 中有用的属性包括：

{{ field.label }}

字段的label，例如Email address。

{{ field.label_tag }}

包含在HTML <label> 标签中的字段Label。它包含表单的label_suffix。例如，默认的label_suffix 是一个冒号：

<label for="id_email">Email address:</label>

{{ field.id_for_label }}

用于这个字段的ID（在上面的例子中是id_email）。如果你正在手工构造label，你可能想使用它代替label_tag。如果你有一些内嵌的JavaScript 并且想避免硬编码字段的ID，这也是有用的。

{{ field.value }}

字段的值，例如someone@example.com。

{{ field.html_name }}

输入元素的name 属性中将使用的名称。它将考虑到表单的前缀。

{{ field.help_text }}

与该字段关联的帮助文档。

{{ field.errors }}

输出一个<ul class="errorlist">，包含这个字段的验证错误信息。你可以使用{% for error in field.errors %}自定义错误的显示。 这种情况下，循环中的每个对象只是一个包含错误信息的简单字符串。

{{ field.is_hidden }}

如果字段是隐藏字段，则为True，否则为False。作为模板变量，它不是很有用处，但是可以用于条件测试，例如：

{% if field.is_hidden %}

{% endif %}

{{ field.field }}

表单类中的Field 实例，通过BoundField 封装。你可以使用它来访问Field 属性，例如{% char_field.field.max_length %}。

{% for hidden in form.hidden_fields %}

{{ hidden }}

{% endfor %}

{% for field in form.visible_fields %}

    <div class="fieldWrapper">

        {{ field.errors }}

        {{ field.label_tag }} {{ field }}

    </div>

{% endfor %}

可重用的表单模板

如果你的网站在多个地方对表单使用相同的渲染逻辑，你可以保存表单的循环到一个单独的模板中来减少重复，然后在其它模板中使用include 标签来重用它：

# In your form template:

{% include "form_snippet.html" %}

# In form_snippet.html:

{% for field in form %}

    <div class="fieldWrapper">

        {{ field.errors }}

        {{ field.label_tag }} {{ field }}

    </div>

{% endfor %}

如果传递到模板上下文中的表单对象具有一个不同的名称，你可以使用include 标签的with 参数来对它起个别名：

{% include "form_snippet.html" with form=comment_form %}

如果你发现自己经常这样做，你可能需要考虑一下创建一个自定义的 inclusion 标签。

• 表单集
  • 在表单集中使用初始化数据
  • 限制表单的最大数目
  • 表单集的验证
  • 验证表单集中表单的数目
  • 处理表单的排序和删除
  • 添加额外的字段到表单中
  • 在视图和模板中使用表单集
• 从模型中创建表单
  • ModelForm
  • 模型表单集
  • 内联formets
• 表单集（Media 类）
  • 资产作为静态定义
  • Media作为动态属性
  • 资产定义中的路径
  • Media 对象
  • 表单中的Media

另见

表单参考

覆盖完整的API 参考，包括表单字段、表单Widget 以及表单和字段的验证。