Form data is either bound or unbound data.

If it is binding, it is possible to verify the data and render the form and its data, then generates the HTML form. If it is not binding, it can not be verified, but it can still render a blank form in HTML form.

Prototype form class: class Form [source]

To create an unbound Form instance, simply instantiate the class:

f = ContactForm()

To bind to the form data, the data can be passed to a dictionary in the form of Form class constructor:

>>> data = {'subject': 'hello',
    ...         'message': 'Hi there',
    ...         'sender': '[email protected]',
    ...         'cc_myself': True}
    >>> f = ContactForm(data)

In this dictionary, the key name of the field, which correspond to the Form class field. Data value needs to be verified.

First, the form of binding properties

　　Form.is_bound：

　　　　If necessary to distinguish between the form and form binding unbound form can check the is_boundproperty values:

>>> f = ContactForm()
>>> f.is_bound
False
>>> f = ContactForm({'subject': 'hello'})
>>> f.is_bound
True

　　　　Note that passing an empty dictionary creates a bound form with empty data are:

>>> f = ContactForm({})
>>> f.is_bound
True

　　　　If there is a bound Form instance but want to change the next data, or want to form an unbound Form bind some data, you need to create another instance of a Form. Because the data is not self-Form instance of reading, Form instance once created, its data will not be changed.

Second, the use forms authentication data

　　1.Form.clean()

　　　　If you want custom validation function, you need to re-implement this clean method.

　　2.Form.is_valid()

　　　　Call is_valid()method to perform data binding verification form, and returns a Boolean value indicating whether the data legitimate.

>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True}
>>> f = ContactForm(data)
>>> f.is_valid()
True

　　　　Let's try illegal data. The following cases, subject is blank (default all fields are required) and the sender is not a valid email address:

>>> data = {'subject': '',
...         'message': 'Hi there',
...         'sender': 'invalid email address',
...         'cc_myself': True}
>>> f = ContactForm(data)
>>> f.is_valid()
False

　　3.Form.errors

　　　　Form errors property contains an error message dictionary:

>>> f.errors
{'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}

　　　　在这个字典中，键为字段的名称，值为错误信息的Unicode字符串组成的列表。错误信息保存在列表中是因为字段可能有多个错误信息。

　　4.Form.errors.as_data()

　　　　返回一个字典，它将字段映射到原始的ValidationError实例。

>>> f.errors.as_data()
{'sender': [ValidationError(['Enter a valid email address.'])],
'subject': [ValidationError(['This field is required.'])]}

　　5.Form.errors.as_json(escape_html=False)

　　　　返回JSON序列化后的错误信息字典。

>>> f.errors.as_json()
{"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],
"subject": [{"message": "This field is required.", "code": "required"}]}

　　6.Form.add_error(field,error)

　　　　向表单特定字段添加错误信息。

　　　　field参数为字段的名称。如果值为None，error将作为Form.non_field_errors()的一个非字段错误。

　　7.Form.has_error(field,code=None)

　　　　判断某个字段是否具有指定code的错误。当code为None时，如果字段有任何错误它都将返回True。

　　8.Form.non_field_errors()

　　　　返回Form.errors中不是与特定字段相关联的错误。

　　9.对于没有绑定数据的表单

　　　　验证没有绑定数据的表单是没有意义的，下面的例子展示了这种情况：

>>> f = ContactForm()
>>> f.is_valid()
False
>>> f.errors
{}

三、检查表单数据是否被修改

　　1.Form.has_changed()

　　　　当需要检查表单的数据是否从初始数据发生改变时，可以使用has_changed()方法。

>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True}
>>> f = ContactForm(data, initial=data)
>>> f.has_changed()
False

　　　　提交表单后，可以重新构建表单并提供初始值，进行比较：

>>> f = ContactForm(request.POST, initial=data)
>>> f.has_changed()

　　　　如果request.POST与initial中的数据有区别，则返回True，否则返回False。

　　2.Form.changed_data

　　　　返回有变化的字段的列表。

>>> f = ContactForm(request.POST, initial=data)
>>> if f.has_changed():
...     print("The following fields changed: %s" % ", ".join(f.changed_data))

四、访问表单中的字段

　　通过fileds属性访问表单的字段：

>>> for row in f.fields.values(): print(row)
...
<django.forms.fields.CharField object at 0x7ffaac632510>
<django.forms.fields.URLField object at 0x7ffaac632f90>
<django.forms.fields.CharField object at 0x7ffaac3aa050>
>>> f.fields['name']
<django.forms.fields.CharField object at 0x7ffaac6324d0>

　　可以修改Form实例的字段来改变字段在表单中的表示：

>>> f.as_table().split('\n')[0]
'<tr><th>Name:</th><td><input name="name" type="text" value="instance" required /></td></tr>'
>>> f.fields['name'].label = "Username"
>>> f.as_table().split('\n')[0]
'<tr><th>Username:</th><td><input name="name" type="text" value="instance" required /></td></tr>'

　　注意不要改变base_fields属性，因为一旦修改将影响同一个Python进程中接下来所有的ContactForm实例：

>>> f.base_fields['name'].label = "Username"
>>> another_f = CommentForm(auto_id=False)
>>> another_f.as_table().split('\n')[0]
'<tr><th>Username:</th><td><input name="name" type="text" value="class" required /></td></tr>'

五、访问cleaned_data

　　Form.cleaned_data

　　Form类中的每个字段不仅负责验证数据，还负责将它们转换为正确的格式。例如，DateField将输入转换为Python的datetime.date对象。无论传递的是普通字符串'1994-07-15'、DateField格式的字符串、datetime.date对象、还是其它格式的数字，Django将始终把它们转换成datetime.date对象。

　　一旦创建一个Form实例并通过验证后，就可以通过它的cleaned_data属性访问干净的数据：

>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True}
>>> f = ContactForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data
{'cc_myself': True, 'message': 'Hi there', 'sender': '[email protected]', 'subject': 'hello'}

　　如果数据没有通过验证，cleaned_data字典中只包含合法的字段：

>>> data = {'subject': '',
...         'message': 'Hi there',
...         'sender': 'invalid email address',
...         'cc_myself': True}
>>> f = ContactForm(data)
>>> f.is_valid()
False
>>> f.cleaned_data
{'cc_myself': True, 'message': 'Hi there'}

　　cleaned_data字典始终只包含Form中定义的字段，即使在构建Form时传递了额外的数据。在下面的例子中，传递了一组额外的字段给ContactForm构造函数，但是cleaned_data将只包含表单的字段：

>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True,
...         'extra_field_1': 'foo',
...         'extra_field_2': 'bar',
...         'extra_field_3': 'baz'}
>>> f = ContactForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data # Doesn't contain extra_field_1, etc.
{'cc_myself': True, 'message': 'Hi there', 'sender': '[email protected]', 'subject': 'hello'}

　　当Form通过验证后，cleaned_data将包含所有字段的键和值，即使传递的数据中没有提供某些字段的值。在下面的例子中，提供的实际数据中不包含nick_name字段，但是cleaned_data任然包含它，只是值为空：

>>> from django import forms
>>> class OptionalPersonForm(forms.Form):
...     first_name = forms.CharField()
...     last_name = forms.CharField()
...     nick_name = forms.CharField(required=False)
>>> data = {'first_name': 'John', 'last_name': 'Lennon'}
>>> f = OptionalPersonForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data
{'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}

六、表单的HTML生成方式

　　Form的第二个任务是将它渲染成HTML代码，默认情况下，根据form类中字段的编写顺序，在HTML中以同样的顺序罗列。可以通过print方法展示出来：

>>> f = ContactForm()
>>> print(f)
<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr>
<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr>
<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

　　如果表单是绑定的，输出的HTML将包含数据。

>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True}
>>> f = ContactForm(data)
>>> print(f)
<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" required /></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" required /></td></tr>
<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="[email protected]" required /></td></tr>
<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked /></td></tr>

　　注意事项：

为了灵活性，输出不包含<table>和</table>、<form>和</form>以及<input type="submit">标签。需要程序员手动添加它们。
每个字段类型都由一个默认的HTML标签展示。注意，这些只是默认的，可以使用Widget 特别指定。
每个HTML标签的name属性名直接从ContactForm类中获取。
form使用HTML5语法，顶部需添加<!DOCTYPE html>说明。

　　1.渲染成文字段落as_p()

　　　　Form.as_p()

　　　　该方法将form渲染成一系列<p>标签，每个<p>标签包含一个字段；

>>> f = ContactForm()
>>> f.as_p()
'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'
>>> print(f.as_p())
<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p>
<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p>
<p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></p>
<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>

　　2.渲染成无序列表as_ul()

　　　　Form.as_ul()

　　　　该方法将form渲染成一系列<li>标签，每个<li>标签包含一个字段。但不会自动生成</ul>和<ul>，所以可以自己指定<ul>的任何HTML属性：

>>> f = ContactForm()
>>> f.as_ul()
'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'
>>> print(f.as_ul())
<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li>
<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li>
<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li>
<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>

　　3.渲染成表格as_table()

　　　　Form.as_table()

　　　　渲染成HTML表格。它与print完全相同，事实上，当print一个表单对象时，在后台调用的就是as_table()方法：

>>> f = ContactForm()
>>> f.as_table()
'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'
>>> print(f)
<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr>
<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr>
<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

七、为错误信息添加CSS样式

　　Form.error_css_class

　　Form.required_css_class

　　为一些特别强调的或者需要额外显示的内容设置醒目的CSS样式是一种常用做法，也是非常有必要的。比如给必填字段加粗显示，设置错误文字为红色等等。

　　Form.error_css_class和Form.required_css_class属性就是做这个用的：

from django import forms

class ContactForm(forms.Form):
    error_css_class = 'error'
    required_css_class = 'required'

    # ... and the rest of your fields here

　　属性名是固定的，不可变（废话），通过赋值不同的字符串，表示给这两类属性添加不同的CSS的class属性。以后Django在渲染form成HTML时将自动为error和required行添加对应的CSS样式。

　　上面的例子，其HTML看上去将类似：

>>> f = ContactForm(data)
>>> print(f.as_table())
<tr class="required"><th><label class="required" for="id_subject">Subject:</label>    ...
<tr class="required"><th><label class="required" for="id_message">Message:</label>    ...
<tr class="required error"><th><label class="required" for="id_sender">Sender:</label>      ...
<tr><th><label for="id_cc_myself">Cc myself:<label> ...
>>> f['subject'].label_tag()
<label class="required" for="id_subject">Subject:</label>
>>> f['subject'].label_tag(attrs={'class': 'foo'})
<label for="id_subject" class="foo required">Subject:</label>

八、将上传的文件绑定到表单

　　处理带有FileField和ImageField字段的表单比普通的表单要稍微复杂一点。

　　首先，为了上传文件，需要确保<form>元素定义enctype为"multipart/form-data"：

<form enctype="multipart/form-data" method="post" action="/foo/">

　　其次，当使用表单时，需要绑定文件数据。文件数据的处理与普通的表单数据是分开的，所以如果表单包含FileField和ImageField，绑定表单时需要指定第二个参数，参考下面的例子。

# 为表单绑定image字段
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> data = {'subject': 'hello',
...         'message': 'Hi there',
...         'sender': '[email protected]',
...         'cc_myself': True}
>>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
>>> f = ContactFormWithMugshot(data, file_data)

　　实际上，一般使用request.FILES作为文件数据的源：

# Bound form with an image field, data from the request
>>> f = ContactFormWithMugshot(request.POST, request.FILES)

　　构造一个未绑定的表单和往常一样，将表单数据和文件数据同时省略：

# Unbound form with an image field
>>> f = ContactFormWithMugshot()

Detailed Django Forms API