html表单 api,表单 API

本文例子基于以下 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': ''}