本文例子基于以下 form:
class TestForm(forms.Form):
name = forms.CharField(max_length=6)
age = forms.IntegerField()
绑定的表单和未绑定的表单
表单分为绑定的,和未绑定的两种状态。
如果是绑定的,那么它能够验证数据,并渲染表单及其数据成 HTML。
如果是未绑定的,那么它不能够完成验证(因为没有可验证的数据!),但是仍然能渲染空白的表单成 HTML。
若要创建一个未绑定的表单实例,只需简单地实例化该类:
f = TestForm()
若要绑定数据到表单,可以将数据以字典的形式传递给表单类的构造函数的第一个参数:
data = {'name':'diego', 'age': 20}
f = TestForm(data)
在这个字典中,键为字段的名称,它们对应于表单类中的属性。值为需要验证的数据。它们通常为字符串,但是没有强制要求必须是字符串;传递的数据类型取决于字段,我们稍后会看到。
Form.is_bound
使用 Form.is_bound
来验证表单是否绑定。
# 未绑定表单
f = TestForm()
f.is_bound
>>> False
# 已绑定表单
f = TestForm({'name':'diego', 'age': 20})
f.is_bound
>>> True
注意,传递一个空字典将创建一个带有空数据的绑定的表单:
f = TestForm({})
f.is_bound
>>> True
如果你有一个绑定的表单实例但是想改下数据,或者你想绑定一个未绑定的表单表单到某些数据,你需要创建另外一个表单实例。Form 实例的数据没有办法修改。表单实例一旦创建,你应该将它的数据视为不可变的,无论它有没有数据。
使用表单来验证数据
Form.clean()
当你需要为相互依赖的字段添加自定义的验证时(也就是验证涉及多个字段时),你可以实现表单的 clean()
方法。示例用法参见后面的章节。
Form.is_valid()
对于绑定的表单实例,可以调用 is_valid()
方法来执行验证并返回一个表示数据是否合法的布尔值。
data = {'name':'abcd', 'age': 20}
f = TestForm(data)
f.is_valid()
>>> True
# 因为 name 超过6个字符,所以这个表单是通不过验证的
data = {'name':'abcdefg', 'age': 20}
f = TestForm(data)
f.is_valid()
>>> False
Form.errors
访问 errors
属性可以获得包含错误信息的字典:
f.errors
>>> {'name': ['Ensure this value has at most 6 characters (it has 7).']}
在这个字典中,键为字段的名称,值为表示错误信息的 Unicode 字符串组成的列表。错误信息保存在列表中是因为字段可能有多个错误信息。
关于自定义错误信息的方法,参加下面章节。
Form.errors.as_data()
返回一个字典,它映射字段到原始的 ValidationError
实例。
f.errors.as_data()
>>> {'name': [ValidationError(['Ensure this value has at most 6 characters (it has 7).'])]}
Form.errors.as_json(escape_html=False)
返回 JSON 序列化后的错误。
f.errors.as_json()
>>> '{"name": [{"code": "max_length", "message": "Ensure this value has at most 6 characters (it has 7)."}]}'
Form.add_error(field, error)
这个方法允许在 Form.clean()
方法内部或从表单的外部一起给字段添加错误信息;例如从一个视图中。
field
参数为字段的名称。如果值为 None,error 将作为 Form.non_field_errors()
返回的一个非字段错误。
error
参数可以是一个简单的字符串,或者最好是一个 ValidationError
实例。
注意,Form.add_error()
会自动删除 cleaned_data
中的相关字段。(具体用法参照后面章节)
Form.has_error(field, code=None)
这个方法返回一个布尔值,指示一个字段是否具有指定错误 code 的错误。当 code 为 None 时,如果字段有任何错误它都将返回 True。
# name 字段有错误
f.has_error('name', code=None)
>>> True
# name 字段有 max_length 错误
f.has_error('name', code='max_length')
>> True
# # name 字段没 min_length 错误
f.has_error('name', code='min_length')
>>> False
# age 字段没错误
f.has_error('age', code=None)
>>> False
若要检查非字段错误,使用 NON_FIELD_ERRORS
作为 field
参数。
Form.non_field_errors()
这个方法返回 Form.errors
中不是与特定字段相关联的错误。它包含在 Form.clean()
中引发的 ValidationError
和使用 Form.add_error(None, "...")
添加的错误。
未绑定表单的行为
验证没有绑定数据的表单是没有意义的,下面的例子展示了这种情况:
>>> f = TestForm()
>>> f.is_valid()
False
>>> f.errors
{}
Form.initial
使用 ** initial ** 可以设定表单的初始值。
data = {'name':'abcd', 'age': 20}
f = TestForm(initial = data)
这些值只显示在没有绑定的表单中,即使没有提供特定值它们也不会作为后备的值。
Form.has_changed()
当你需要检查表单的数据是否从初始数据发生改变时,可以使用表单的 has_changed()
方法。
data = {'name':'abcd', 'age': 20}
f = TestForm(data, initial = data)
f.has_changed()
>>> False
data = {'name':'abcd', 'age': 20}
f = TestForm(data)
f.has_changed()
>>> True
data = {'name':'abcd', 'age': 20}
data_1 = {'name':'abcd', 'age': 30}
f = TestForm(data, initial=data)
f.has_changed()
>>> False
f = TestForm(data_1, initial=data)
f.has_changed()
>>> True
当提交表单时,我们可以与初始值比较,检验其是否更新了数据,这样可以实现比较:
f = TestForm(request.POST, initial=data)
f.has_changed()
如果 request.POST
中的数据与 initial
中的不同,has_changed()
将为 True
,否则为 False
。 计算的结果是通过调用表单每个字段的 Field.has_changed()
得到的。
Form.cleaned_data
表单类中的每个字段不仅负责验证数据,还负责“清洁”它们 —— 将它们转换为正确的格式。这是个非常好用的功能,因为它允许字段以多种方式输入数据,并总能得到一致的输出。
一旦你创建一个表单实例并通过验证后,你就可以通过它的 cleaned_data
属性访问清洁的数据:
data = {'name':'abcd', 'age': '20'}
f = TestForm(data)
f.is_valid()
>>> True
# cleaned_data 方法让 age 的数据从字符串变为表单所定义的整形
f.cleaned_data
>>> {'name': 'abcd', 'age': 20}
cleaned_data
始终只包含表单中定义的字段,即使你在构建表单时传递了额外的数据。
data = {'name':'abcd', 'age': '20', 'sex': 'male'}
f = TestForm(data)
f.is_valid()
>>> True
# sex 并没有在表单中定义,所以 cleaned_data 中不会存在
f.cleaned_data
>>> {'name': 'abcd', 'age': 20}
当表单合法时,cleaned_data
将包含所有字段的键和值,即使传递的数据不包含某些可选字段的值。
例如有这样一个表单:
class TestForm(forms.Form):
name = forms.CharField(max_length=6)
age = forms.IntegerField()
sex = forms.CharField(required=False) # 非必需字段
测试 cleaned_data
的结果:
data = {'name':'abcd', 'age': '20',}
f = TestForm(data)
f.is_valid()
>>> True
# cleaned_data 中依然包含 sex 字段,是个空字符串
f.cleaned_data
>>> {'age': 20, 'name': 'abcd', 'sex': ''}