表单字段Link to this heading

class Field(**kwargs)Link to this definition

当你创建一个 Form 类时，最重要的部分是定义表单的字段。每个字段都有自定义的验证逻辑，以及其他一些钩子。

Field.clean(value)Link to this definition

虽然你主要会在 Form 类中使用 Field 类，但你也可以实例化它们并直接使用它们来更好地了解它们的工作原理。每个 Field 实例都有一个 clean() 方法，它接受一个参数，要么引发一个 django.core.exceptions.ValidationError 异常，要么返回清理后的值：

Python console

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("foo@example.com")
'foo@example.com'
>>> f.clean("invalid email address")
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

核心字段参数Link to this heading

每个 Field 类的构造函数至少需要这些参数。有些 Field 类需要额外的、特定的字段参数，但以下参数应始终接受：

`required`Link to this heading

Field.requiredLink to this definition

默认情况下，每个 Field 类都假定该值是必需的，因此如果传递一个空值 -- 无论是 None 还是空字符串（""）-- 那么 clean() 将引发一个 ValidationError 异常：

Python console

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(" ")
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

要指定字段为不必需的，请将 required=False 传递给 Field 构造函数：

Python console

>>> f = forms.CharField(required=False)
>>> f.clean("foo")
'foo'
>>> f.clean("")
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

如果一个 Field 有 required=False，而你给 clean() 传递一个空值，那么 clean() 将返回一个 规范化 的空值，而不是引发 ValidationError。对于 CharField，将返回 empty_value，默认为一个空字符串。对于其他 Field 类，它可能是 None。（这因字段而异。）

必填表单字段的部件有 required HTML 属性。将 Form.use_required_attribute 属性设置为 False 就可以禁用。由于在添加和删除表单集时，浏览器的验证可能不正确，所以表单集的表单中不包含 required 属性。

`label`Link to this heading

Field.labelLink to this definition

label 参数让你指定该字段的“人类友好”标签。当 Field 在 Form 中显示时，会用到这个标签。

如上文“将表格输出为 HTML”中所解释的，Field 的默认标签是由字段名通过将所有下划线转换为空格并将第一个字母大写而生成的。如果默认行为不能产生一个适当的标签，请指定 label。

以下是一个完整的示例 Form，它为其两个字段实现了 label。我们指定了 auto_id=False 以简化输出：

Python console

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label="Your name")
...     url = forms.URLField(label="Your website", required=False)
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

`label_suffix`Link to this heading

Field.label_suffixLink to this definition

label_suffix 参数允许你以每个字段为基础覆盖表单的 label_suffix：

Python console

>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")
...
>>> f = ContactForm(label_suffix="?")
>>> print(f.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required></p>

`help_text`Link to this heading

Field.help_textLink to this definition

help_text 参数让你为这个 Field 指定描述性文本。如果你提供了 help_text，当 Field 被一个方便的 Form 方法（例如 as_ul()）渲染时，它将显示在 Field` 旁边。

就像模型字段的 help_text 一样，这个值在自动生成的表单中并没有被 HTML 封装。

以下是一个完整的示例 Form，它为其两个字段实现了 help_text。我们指定了 auto_id=False 以简化输出：

Python console

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text="100 characters max.")
...     message = forms.CharField()
...     sender = forms.EmailField(help_text="A valid email address, please.")
...     cc_myself = forms.BooleanField(required=False)
...
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul())
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>

`error_messages`Link to this heading

Field.error_messagesLink to this definition

error_messages 参数允许你覆盖字段将引发的默认消息。传递一个字典，其中的键与你想要覆盖的错误消息匹配。例如，这是默认的错误消息：

Python console

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

以下是一个自定义错误消息的示例：

Python console

>>> name = forms.CharField(error_messages={"required": "Please enter your name"})
>>> name.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

在下面的内置字段类一节中，每个 Field 定义了它所使用的错误信息键。

`validators`Link to this heading

Field.validatorsLink to this definition

validators 参数让你为这个字段提供一个验证函数列表。

更多信息请参见验证器文档。

`localize`Link to this heading

Field.localizeLink to this definition

localize 参数可以实现表单数据输入和渲染输出的本地化。

更多信息请参见格式本地化文档。

`disabled`Link to this heading

Field.disabledLink to this definition

disabled 布尔参数设置为 True 时，使用 disabled HTML 属性禁用表单字段，使其不能被用户编辑。即使用户篡改了提交给服务器的字段值，也会被忽略，而采用表单初始数据的值。

检查字段数据是否有变化Link to this heading

`has_changed()`Link to this heading

Field.has_changed()Link to this definition

has_changed() 方法用于确定字段值是否与初始值发生了变化。返回 True 或 False。

更多信息请参见 Form.has_changed() 文档。

内置 `Field` 类Link to this heading

当然，forms 库附带了一组 Field 类，代表了常见的验证需求。本节将对每个内置字段进行说明。

对于每个字段，我们描述了在你没有指定 widget 时使用的默认部件。我们还指定了当你提供一个空值时返回的值（参见上文 required 一节以了解其含义）。

`BooleanField`Link to this heading

class BooleanField(**kwargs)Link to this definition

默认部件：CheckboxInput
空值：False
规范化为：Python 的 True 或 False 值。
如果字段有 required=True，则验证该值是否为 True （例如，复选框被选中）。
错误信息键：required

`CharField`Link to this heading

class CharField(**kwargs)Link to this definition

默认部件：TextInput
空值：不管你给 empty_value 的是什么。
规范化为：一个字符串。
如果提供了 max_length 和 min_length，则使用 MaxLengthValidator 和 MinLengthValidator。否则，所有输入都有效。
错误信息键：required、max_length、min_length

具有以下可选的验证参数：

max_lengthLink to this definition

min_lengthLink to this definition: 如果提供了这些参数，这些参数确保字符串的长度最多或至少是给定的长度。

stripLink to this definition: 如果 True （默认），该值将被去掉前导和尾部的空白。

empty_valueLink to this definition: 用来表示“空”的值。默认为空字符串。

`ChoiceField`Link to this heading

class ChoiceField(**kwargs)Link to this definition

默认部件：Select
空值：'' （空字符串）
规范化为：一个字符串。
验证给定值是否存在于选择列表中。
错误信息键：required、invalid_choice

invalid_choice 错误信息可能包含 %(value)s，该信息将被替换为选定的选择。

需要一个额外的参数：

choicesLink to this definition: 或者是一个 iterable 的二元元组作为这个字段的选择，或者是一个 enumeration 的选择，或者是一个返回这样一个迭代器的可调用对象。这个参数接受的格式与模型字段的 choices 参数相同。更多细节请参见模型字段引用文档中的选择。如果这个参数是可调用的，那么除了在渲染过程中，每次初始化字段的表单时，它都会被执行。默认为空列表。

`DateField`Link to this heading

class DateField(**kwargs)Link to this definition

默认部件：DateInput
空值：None
规范化为：Python 的 datetime.date 对象。
验证给定值是 datetime.date、datetime.datetime 或以特定日期格式化的字符串。
错误信息键：required、invalid

需要一个可选的参数：

input_formatsLink to this definition: 一个用于尝试将字符串转换为有效的 datetime.date 对象的格式迭代器。

如果没有提供 input_formats 参数，如果 USE_L10N 为 False，则默认输入格式来自 DATE_INPUT_FORMATS，如果启用了本地化，则默认输入格式来自激活的的本地格式 DATE_INPUT_FORMATS 键。也请参见格式本地化。

`DateTimeField`Link to this heading

class DateTimeField(**kwargs)Link to this definition

默认部件：DateTimeInput
空值：None
规范化为：Python 的 datetime.datetime 对象。
验证给定的值是 datetime.datetime、datetime.date 或以特定日期时间格式化的字符串。
错误信息键：required、invalid

需要一个可选的参数：

input_formatsLink to this definition: 一个用于尝试将字符串转换为有效的 datetime.datetime 对象的格式迭代器，除了 ISO 8601 格式。

该字段始终接受 ISO 8601 格式的日期或类似于 parse_datetime() 可识别的日期字符串。以下是一些示例：

'2006-10-25 14:30:59'
'2006-10-25T14:30:59'
'2006-10-25 14:30'
'2006-10-25T14:30'
'2006-10-25T14:30Z'
'2006-10-25T14:30+02:00'
'2006-10-25'

如果没有提供 input_formats 参数，默认的输入格式来自 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS，如果: setting:USE_L10N 为 False，如果启用了本地化，则从激活的本地格式 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 键中获取。也请参见格式本地化。

`DecimalField`Link to this heading

class DecimalField(**kwargs)Link to this definition

当 Field.localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。
空值：None
规范化为：Python 的 decimal。
验证给定的值是否为十进制数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。如果提供了 step_size，则使用 StepValueValidator。前导和尾随空格会被忽略。
错误消息键: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size。

max_value 和 min_value 错误信息可能包含 %(limit_value)s，将用适当的限制代替。同样，max_digits、max_decimal_places 和 max_whole_digits 错误信息可能包含 %(max)s。

接受五个可选参数：

max_valueLink to this definition

min_valueLink to this definition: 这些控制着字段中允许的数值范围，应以 decimal.Decimal 值的形式给出。

max_digitsLink to this definition: 值中允许的最大数字（小数点前的数字加上小数点后的数字，去掉前导零）。

decimal_placesLink to this definition: 允许的最大小数位数。

step_sizeLink to this definition: 将有效输入限制为 step_size 的整数倍。

`DurationField`Link to this heading

class DurationField(**kwargs)Link to this definition

默认部件：TextInput
空值：None
规范化为：Python 的 timedelta。
验证给定值是否是一个字符串，可以转换成 timedelta。该值必须在 datetime.timedelta.min 和 datetime.timedelta.max 之间。
错误信息键：required、invalid、overflow

接受 parse_duration() 理解的任何格式。

`EmailField`Link to this heading

class EmailField(**kwargs)Link to this definition

默认部件：EmailInput
空值：不管你给 empty_value 的是什么。
规范化为：一个字符串。
使用 EmailValidator 来验证给定的值是一个有效的电子邮件地址，使用一个适度复杂的正则表达式。
错误信息键：required、invalid

具有可选参数 max_length、min_length 和 empty_value，它们的工作方式与 CharField 相同。max_length 参数默认为 320（参见 RFC 3696 Section 3）。

`FileField`Link to this heading

class FileField(**kwargs)Link to this definition

默认部件：ClearableFileInput
空值：None
规范化为：一个 UploadedFile 对象，它将文件内容和文件名包装成一个单一对象。
可以验证非空文件数据已经绑定到表单中。
错误信息键：required、invalid、missing、empty、max_length

具有可选的验证参数：max_length 和 allow_empty_file。如果提供了这些参数，它们确保文件名最多为给定的长度，并且即使文件内容为空，验证也将成功。

要了解更多关于 UploadedFile 对象的信息，请看文件上传文档。

当你在表单中使用 FileField 时，你还必须记住将文件数据绑定到表单中。

max_length 错误指的是文件名的长度。在该键的错误信息中，%(max)d 将被替换为最大文件名长度，%(length)d 将被替换为当前文件名长度。

`FilePathField`Link to this heading

class FilePathField(**kwargs)Link to this definition

默认部件：Select
空值：'' （空字符串）
规范化为：一个字符串。
验证选择是否存在于选择列表中。
错误信息键：required、invalid_choice

该字段允许从某个目录内的文件中选择。它需要五个额外的参数；只有 path 是必须的。

pathLink to this definition: 你想要列出的内容的目录的绝对路径。该目录必须存在。

recursiveLink to this definition: 如果 False （默认），只提供 path 的直接内容作为选择。如果 True，目录将被递归递进，所有的子目录将被列为选择。

matchLink to this definition: 正则表达式模式；只允许将名称与此表达式相匹配的文件作为选择。

allow_filesLink to this definition: 可选。可选 True 或 False。默认值是 True。指定是否应该包含指定位置的文件。此项或 allow_folders 必须为 True。

allow_foldersLink to this definition: 可选。可选 True 或 False。默认为 False。指定是否应包括指定位置的文件夹。此项或 allow_files 必须为 True。

`FloatField`Link to this heading

class FloatField(**kwargs)Link to this definition

当 Field.localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。
空值：None
规范化为：Python 的浮点数。
验证给定的值是否为浮点数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。如果提供了 step_size，则使用 StepValueValidator。允许前导和尾随空格，就像 Python 的 float() 函数一样。
错误消息键: required, invalid, max_value, min_value, step_size。

接受三个可选参数：

max_valueLink to this definition

min_valueLink to this definition: 这些控制了该字段允许的数值范围。

step_sizeLink to this definition: New in Django 4.1

将有效输入限制为 step_size 的整数倍。

`GenericIPAddressField`Link to this heading

class GenericIPAddressField(**kwargs)Link to this definition

一个包含 IPv4 或 IPv6地址的字段。

默认部件：TextInput
空值：'' （空字符串）
规范化为：一个字符串。IPv6 地址的规范化如下所述。
验证给定的值是一个有效的 IP 地址。
Error message keys: required, invalid, max_length

IPv6 地址规范化遵循 RFC 4291 Section 2.2 第 2.2 节，包括使用该节第 3 段建议的 IPv4 格式，如 ::fffff:192.0.2.0。例如，2001:0::0:01 将被标准化为 2001::1，::fffff:0a0a:0a0a 将被标准化为 ::fffff:10.10.10.10。所有字符都转换为小写。

接受三个可选参数：

protocolLink to this definition: 将有效输入限制为指定协议。接受的值是 both （默认）、IPv4 或 IPv6。匹配是不区分大小写的。

unpack_ipv4Link to this definition: 解压 IPv4 映射地址，如 ::fffff:192.0.2.1。如果启用该选项，该地址将被解压为 192.0.2.1。默认为禁用。只有当 protocol 设置为 'both' 时才会启用。

max_lengthLink to this definition: Defaults to 39, and behaves the same way as it does for CharField.

`ImageField`Link to this heading

class ImageField(**kwargs)Link to this definition

默认部件：ClearableFileInput
空值：None
规范化为：一个 UploadedFile 对象，它将文件内容和文件名包装成一个单一对象。
验证文件数据是否已经绑定到表单中。同时使用 FileExtensionValidator 来验证 Pillow 是否支持文件扩展名。
错误信息键：required、invalid、missing、empty、invalid_image

使用 ImageField 需要安装的 Pillow 支持你使用的图片格式。如果你在上传图片时遇到 corrupt image 错误，通常意味着 Pillow 不理解图片格式。要解决这个问题，请安装相应的库并重新安装 Pillow。

当你在表单中使用 ImageField 时，你还必须记住将文件数据绑定到表单。

在字段被清理和验证后，UploadedFile 对象将具有一个额外的 image 属性，其中包含 Pillow 的 Image 实例，用于检查文件是否为有效的图像。Pillow 在验证图像后关闭底层文件描述符，因此虽然可以访问非图像数据属性，如 format、height 和 width，但不能在不重新打开文件的情况下使用访问底层图像数据的方法，比如 getdata() 或 getpixel()。例如：

Python console

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
...     img = forms.ImageField()
...
>>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data["img"]
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>

此外，UploadedFile.content_type 如果 Pillow 能够确定图片的内容类型，则会以图片的内容类型进行更新，否则会设置为 None。

`IntegerField`Link to this heading

class IntegerField(**kwargs)Link to this definition

当 Field.localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。
空值：None
规范化为：Python 的整数。
验证给定的值是否为整数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。如果提供了 step_size，则使用 StepValueValidator。允许前导和尾随空格，就像 Python 的 int() 函数一样。
错误消息键: required, invalid, max_value, min_value, step_size

max_value、min_value 和 step_size 的错误消息可能包含 %(limit_value)s，它将被适当的限制值替换。

接受三个可选的验证参数：

max_valueLink to this definition

min_valueLink to this definition: 这些控制了该字段允许的数值范围。

step_sizeLink to this definition: New in Django 4.1

将有效输入限制为 step_size 的整数倍。

`JSONField`Link to this heading

class JSONField(encoder=None, decoder=None, **kwargs)Link to this definition

一个接受 JSON 编码数据的字段 JSONField。

默认部件：Textarea
空值：None
规范化为：JSON 值的 Python 表示（通常为 dict、list 或 None），取决于 JSONField.decoder。
验证给定值是否为有效的 JSON。
错误信息键：required、invalid

需要两个可选的参数：

encoderLink to this definition

一个 json.JSONEncoder 子类，用于序列化标准 JSON 序列器不支持的数据类型（例如 datetime.datetime 或 UUID）。例如，你可以使用 DjangoJSONEncoder 类。

默认为 json.JSONEncoder。

decoderLink to this definition

一个 json.JSONDecoder 子类来反序列化输入。你的反序列化可能需要考虑到你无法确定输入类型的事实。例如，你有可能返回一个 datetime，但实际上是一个字符串，而这个字符串恰好与 datetime 的格式相同。

decoder 可用于验证输入。如果在反序列化过程中出现 json.JSONONDecodeError，则会出现 ValidationError。

默认为 json.JSONDecoder。

`MultipleChoiceField`Link to this heading

class MultipleChoiceField(**kwargs)Link to this definition

默认部件：SelectMultiple
空值：[] （空列表）
规范化为：一个字符串列表。
验证给定值列表中的每个值是否存在于选择列表中。
错误信息键：required、invalid_choice、invalid_list

invalid_choice 错误信息可能包含 %(value)s，该信息将被替换为选定的选择。

与 ChoiceField 一样，多了一个必要参数 choices。

`NullBooleanField`Link to this heading

class NullBooleanField(**kwargs)Link to this definition

默认部件：NullBooleanSelect
空值：None
规范化为：Python 的 True、False 或 None 值。
不验证任何东西（也就是说，它从不引起 ValidationError）。

NullBooleanField 可以通过提供部件 choices 来与诸如 Select 或 RadioSelect 等部件一起使用。

Code

NullBooleanField(
    widget=Select(
        choices=[
            ("", "Unknown"),
            (True, "Yes"),
            (False, "No"),
        ]
    )
)

`RegexField`Link to this heading

class RegexField(**kwargs)Link to this definition

默认部件：TextInput
空值：不管你给 empty_value 的是什么。
规范化为：一个字符串。
使用 RegexValidator 来验证给定的值是否匹配某个正则表达式。
错误信息键：required、invalid

需要一个额外的参数：

regexLink to this definition: 一个正则表达式，可以是字符串，也可以是编译后的正则表达式对象。

也接受 max_length、min_length、strip 和 empty_value，它们的工作原理和 CharField 一样。

stripLink to this definition: 默认值为 False。如果启用，将在验证正则表达式之前进行 strip。

`SlugField`Link to this heading

class SlugField(**kwargs)Link to this definition

默认部件：TextInput
空值：不管你给 empty_value 的是什么。
规范化为：一个字符串。
使用 validate_slug 或 validate_unicode_slug 来验证给定值是否只包含字母、数字、下划线和连字符。
错误信息键：required、invalid

这个字段用于在表单中表示一个模型 SlugField。

需要两个可选的参数：

allow_unicodeLink to this definition: 一个布尔值，指示该字段除了接受 ASCII 字母外，还接受 Unicode 字母。默认值为 False。

empty_valueLink to this definition: 用来表示“空”的值。默认为空字符串。

`TimeField`Link to this heading

class TimeField(**kwargs)Link to this definition

默认部件：TimeInput
空值：None
规范化为：Python 的 datetime.time 对象。
验证给定值是 datetime.time 或以特定时间格式化的字符串。
错误信息键：required、invalid

需要一个可选的参数：

input_formatsLink to this definition: 一个用于尝试将字符串转换为有效的 datetime.time 对象的格式迭代器。

如果没有提供 input_formats 参数，如果 USE_L10N 为 False，则默认输入格式来自 TIME_INPUT_FORMATS`，如果启用了本地化，则来自激活的本地格式 TIME_INPUT_FORMATS 键。也请参见格式本地化。

`TypedChoiceField`Link to this heading

class TypedChoiceField(**kwargs)Link to this definition

就像 ChoiceField 一样，除了 TypedChoiceField 需要两个额外的参数 coerce 和 empty_value。

默认部件：Select
空值：不管你给 empty_value 的是什么。
规范化为：coerce 参数提供的类型的值。
验证给定的值是否存在于选择列表中，并且可以被强制执行。
错误信息键：required、invalid_choice

需要额外的参数：

coerceLink to this definition: 接受一个参数并返回一个强制值的函数。例子包括内置的 int、float、bool 和其他类型。默认为身份函数。请注意，强制执行发生在输入验证之后，所以可以强制执行到一个不存在于``choices``中的值。

empty_valueLink to this definition: 用来表示“空”的值。默认为空字符串；None 是另一种常见的选择。请注意，这个值不会被 coerce 参数中给出的函数强制执行，所以要据此选择。

`TypedMultipleChoiceField`Link to this heading

class TypedMultipleChoiceField(**kwargs)Link to this definition

就像 MultipleChoiceField 一样，只是 TypedMultipleChoiceField 需要两个额外的参数：coerce 和 empty_value。

默认部件：SelectMultiple
空值：不管你给 empty_value 的是什么。
归法化为：coerce 参数提供的类型值列表。
验证给定的值是否存在于选择列表中，并且可以被强制执行。
错误信息键：required、invalid_choice

invalid_choice 错误信息可能包含 %(value)s，该信息将被替换为选定的选择。

需要两个额外的参数，coerce 和 empty_value，如 TypedChoiceField。

`URLField`Link to this heading

class URLField(**kwargs)Link to this definition

默认部件：URLInput
空值：不管你给 empty_value 的是什么。
规范化为：一个字符串。
使用 URLValidator 来验证给定值是一个有效的 URL。
错误信息键：required、invalid

具有可选参数 max_length、min_length 和 empty_value，它们的工作方式与 CharField 相同。

`UUIDField`Link to this heading

class UUIDField(**kwargs)Link to this definition

默认部件：TextInput
空值：None
规范化为：UUID 对象。
错误信息键：required、invalid

该字段将接受作为 UUID 构造函数的 hex 参数的任何字符串格式。

稍复杂的内置 `Field` 类Link to this heading

`ComboField`Link to this heading

class ComboField(**kwargs)Link to this definition

默认部件：TextInput
空值：'' （空字符串）
规范化为：一个字符串。
根据 ComboField 参数指定的每个字段验证给定值。
错误信息键：required、invalid

需要一个额外的必要参数。

fieldsLink to this definition

应该用来验证字段值的字段列表（按照提供的顺序）。

Code

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com')
'test@example.com'
>>> f.clean('longemailaddress@example.com')
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

`MultiValueField`Link to this heading

class MultiValueField(fields=(), **kwargs)Link to this definition

默认部件：TextInput
空值：'' （空字符串）
规范化为：子类的 compress 方法返回的类型。
根据作为 MultiValueField 参数指定的每个字段验证给定值。
错误信息键：required、invalid、incomplete

将多个字段的逻辑聚合在一起产生一个值。

这个字段是抽象的，必须被子类化。与单值字段相反， MultiValueField 的子类不能实现 clean()，而是——实现 compress()。

需要一个额外的必要参数。

fieldsLink to this definition: 字段组成的元组，其值经清理后合并为一个值。字段的每个值都由 fields 中的相应字段进行清理——第一个值由第一个字段清理，第二个值由第二个字段清理，等等。当所有字段清理完毕后，通过 compress() 将清理后的值列表合并为一个值。

还需要一些可选的参数：

require_all_fieldsLink to this definition

默认值为 True，在这种情况下，如果没有为任何字段提供值，就会出现 required 验证错误。

Field.required 属性设置为 False 时，可将单个字段设置为 False，使其成为可选字段。如果没有为必填字段提供任何值，就会出现 incomplete 的验证错误。

可以在 MultiValueField 子类上定义一个默认的 incomplete 错误信息，也可以在每个单独的字段上定义不同的信息。例如：

Code

from django.core.validators import RegexValidator


class PhoneField(MultiValueField):
    def __init__(self, **kwargs):
        # Define one message for all fields.
        error_messages = {
            "incomplete": "Enter a country calling code and a phone number.",
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={"incomplete": "Enter a country calling code."},
                validators=[
                    RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."),
                ],
            ),
            CharField(
                error_messages={"incomplete": "Enter a phone number."},
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")],
            ),
            CharField(
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")],
                required=False,
            ),
        )
        super().__init__(
            error_messages=error_messages,
            fields=fields,
            require_all_fields=False,
            **kwargs
        )

widgetLink to this definition: 必须是 django.forms.MultiWidget 的子类。默认值是 TextInput，在这种情况下可能不是很有用。

compress(data_list)Link to this definition

取一个有效值的列表，并返回这些值的“压缩”版本——在一个单一值中。例如，SplitDateTimeField 是一个子类，它将一个时间字段和一个日期字段合并成一个 datetime 对象。

这个方法必须在子类中实现。

`SplitDateTimeField`Link to this heading

class SplitDateTimeField(**kwargs)Link to this definition

默认部件：SplitDateTimeWidget
空值：None
规范化为：Python 的 datetime.datetime 对象。
验证给定值是 datetime.datetime 或以特定日期时间格式化的字符串。
错误信息键：required、invalid、invalid_date、invalid_time

需要两个可选的参数：

input_date_formatsLink to this definition: 用于将字符串转换为有效的 datetime.date 对象的格式列表。

如果没有提供 input_date_formats 参数，则使用 DateField 的默认输入格式。

input_time_formatsLink to this definition: 用于将字符串转换为有效的 datetime.time 对象的格式列表。

如果没有提供 input_time_formats 参数，则使用 TimeField 的默认输入格式。

处理关系的字段Link to this heading

有两个字段可用于表示模型之间的关系： ModelChoiceField 和 ModelMultipleChoiceField。这两个字段都需要一个 queryset 参数，用于创建字段的选择。在表单验证后，这些字段将把一个模型对象（对于 ModelChoiceField）或多个模型对象（对于 ModelMultipleChoiceField）放入表单的 cleaned_data 字典中。

对于更复杂的用途，你可以在声明表单字段时指定 queryset=None，然后在表单的 __init__() 方法中填充 queryset：

Code

class FooMultipleChoiceForm(forms.Form):
    foo_select = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["foo_select"].queryset = ...

ModelChoiceField 和 ModelMultipleChoiceField 都有一个 iterator 属性，它指定了在生成选择时用于迭代查询集的类。详见迭代关系选择。

`ModelChoiceField`Link to this heading

class ModelChoiceField(**kwargs)Link to this definition

默认部件：Select
空值：None
规范化为：一个模型实例。
验证给定的 id 是否存在于查询集中。
错误信息键：required、invalid_choice

invalid_choice 错误信息可能包含 %(value)s，该信息将被替换为选定的选择。

允许选择一个单一的模型对象，适合代表一个外键。请注意，当条目数量增加时，ModelChoiceField 的默认部件变得不实用。你应该避免将其用于超过 100 个项目。

需要一个参数：

querysetLink to this definition: 由模型对象组成的 QuerySet，从中得出字段的选择，用于验证用户的选择。它在表单渲染时被执行。

ModelChoiceField 还接受几个可选参数：

empty_labelLink to this definition

默认情况下，ModelChoiceField 使用的 <select> 小组件将在列表顶部有一个空的选择。你可以用 empty_label 属性来改变这个标签的文本（默认是 "---------"），或者你可以通过将 empty_label 设置为 None 来完全禁用空标签。

Code

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

请注意，如果 ModelChoiceField 是必填的并且具有默认的初始值，或者 widget 设置为 RadioSelect 并且 ModelChoiceField.blank 参数为 False，则不会创建空选择项（无论 empty_label 的值如何）。

to_field_nameLink to this definition

这个可选参数用于指定字段，作为字段的小组件中选择的值。请确保它是模型的唯一字段，否则所选的值可能会匹配多个对象。默认情况下，它被设置为 None，在这种情况下，将使用每个对象的主键。例如：

Code

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

会产生：

Html

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

和：

Code

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

会产生：

Html

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

blankLink to this definition: 在使用 RadioSelect 小部件时，这个可选的布尔参数确定是否创建一个空选择项。默认情况下，blank 是 False，在这种情况下不会创建空选择项。

ModelChoiceField 也有属性：

iteratorLink to this definition: 用于从 queryset 中生成字段选择的迭代器类。默认情况下， ModelChoiceIterator。

模型的 __str__() 方法将被调用，以生成用于字段选择的对象的字符串表示。要提供自定义的表示，请将 ModelChoiceField 子类化，并覆盖 label_from_instance。该方法将接收一个模型对象，并应返回一个适合表示它的字符串。例如：

Code

from django.forms import ModelChoiceField


class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

`ModelMultipleChoiceField`Link to this heading

class ModelMultipleChoiceField(**kwargs)Link to this definition

默认部件：SelectMultiple
空值：一个空的 QuerySet （self.queryset.none()）。
规范化为：一个模型实例的 QuerySet。
验证给定值列表中的每个 id 是否存在于查询集中。
错误信息键：required、invalid_list、invalid_choice、invalid_pk_value

invalid_choice 信息可能包含 %(value)s，invalid_pk_value 信息可能包含 %(pk)s，将用适当的值代替。

允许选择一个或多个模型对象，适合表示多对多关系。与 ModelChoiceField 一样，你可以使用 label_from_instance 来自定义对象的表示。

需要一个参数：

querysetLink to this definition: 与 ModelChoiceField.queryset 相同。

需要一个可选的参数：

to_field_nameLink to this definition: 与 ModelChoiceField.to_field_name 相同。

ModelMultipleChoiceField 也有属性：

iteratorLink to this definition: 与 ModelChoiceField.iterator 相同。

迭代关系选择Link to this heading

默认情况下， ModelChoiceField 和 ModelMultipleChoiceField 使用 ModelChoiceIterator 来生成它们的字段 choices。

当迭代时，ModelChoiceIterator 产生一个二元元组选择，包含 ModelChoiceIteratorValue 实例作为每个选择的第一个 value 元素。ModelChoiceIteratorValue 封装了选择值，同时保持了对源模型实例的引用，可用于自定义部件的实现，例如，将 data-* attributes 添加到 <option>。

例如，考虑以下模型：

Code

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(decimal_places=2, max_digits=6)

    def __str__(self):
        return self.name


class Pizza(models.Model):
    topping = models.ForeignKey(Topping, on_delete=models.CASCADE)

你可以使用 Select 部件子类将 Topping.price 的值作为 HTML 属性 data-price，包含在每个 <option> 元素中：

Code

from django import forms


class ToppingSelect(forms.Select):
    def create_option(
        self, name, value, label, selected, index, subindex=None, attrs=None
    ):
        option = super().create_option(
            name, value, label, selected, index, subindex, attrs
        )
        if value:
            option["attrs"]["data-price"] = value.instance.price
        return option


class PizzaForm(forms.ModelForm):
    class Meta:
        model = Pizza
        fields = ["topping"]
        widgets = {"topping": ToppingSelect}

这将使 Pizza.topping 选择为：

Html

<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>

对于更高级的用法，你可以将 ModelChoiceIterator 子类化，以自定义产生的二元元组选择。

`ModelChoiceIterator`Link to this heading

class ModelChoiceIterator(field)Link to this definition

指定给 ModelChoiceField`和:class:`ModelMultipleChoiceField 的 iterator 属性的默认类。迭代器，从查询集中产生二元元组选择。

需要一个参数：

fieldLink to this definition: ModelChoiceField 或 ModelMultipleChoiceField 的实例来迭代和产生选择。

ModelChoiceIter 有以下方法：

__iter__()Link to this definition: 产生二元元组选择，格式为 ChoiceField.chips 使用的 (value, label)。第一个 value 元素是一个 ModelChoiceIteratorValue 实例。

`ModelChoiceIteratorValue`Link to this heading

class ModelChoiceIteratorValue(value, instance)Link to this definition

需要两个参数：

valueLink to this definition: 选择的值。该值用于呈现 HTML <option> 元素的 value 属性。

instanceLink to this definition: 来自查询集的模型实例。该实例可以在自定义的 ChoiceWidget.create_option() 实现中被访问，以调整渲染的 HTML。

ModelChoiceIteratorValue 有以下方法：

__str__()Link to this definition: 返回 value 作为一个字符串在 HTML 中显示。

创建自定义字段Link to this heading

如果内置的 Field 类不能满足你的需求，你可以创建自定义的 Field 类。为此，创建一个 django.forms.Field 的子类。它唯一的要求是实现一个 clean() 方法，并且它的 __init__() 方法接受上面提到的核心参数 (required, label, initial, widget, help_text)。

你也可以通过覆盖 get_bound_field() 来自定义字段的访问方式。

表单字段Link to this heading#

核心字段参数Link to this heading#

requiredLink to this heading#

labelLink to this heading#

label_suffixLink to this heading#

initialLink to this heading#

widgetLink to this heading#

help_textLink to this heading#

error_messagesLink to this heading#

validatorsLink to this heading#

localizeLink to this heading#

disabledLink to this heading#

检查字段数据是否有变化Link to this heading#

has_changed()Link to this heading#

内置 Field 类Link to this heading#

BooleanFieldLink to this heading#

CharFieldLink to this heading#

ChoiceFieldLink to this heading#

DateFieldLink to this heading#

DateTimeFieldLink to this heading#

DecimalFieldLink to this heading#

DurationFieldLink to this heading#

EmailFieldLink to this heading#

FileFieldLink to this heading#

FilePathFieldLink to this heading#

FloatFieldLink to this heading#

GenericIPAddressFieldLink to this heading#

ImageFieldLink to this heading#

IntegerFieldLink to this heading#

JSONFieldLink to this heading#

MultipleChoiceFieldLink to this heading#

NullBooleanFieldLink to this heading#

RegexFieldLink to this heading#

SlugFieldLink to this heading#

TimeFieldLink to this heading#

TypedChoiceFieldLink to this heading#

TypedMultipleChoiceFieldLink to this heading#

URLFieldLink to this heading#

UUIDFieldLink to this heading#

稍复杂的内置 Field 类Link to this heading#

ComboFieldLink to this heading#

MultiValueFieldLink to this heading#

SplitDateTimeFieldLink to this heading#

处理关系的字段Link to this heading#

ModelChoiceFieldLink to this heading#

ModelMultipleChoiceFieldLink to this heading#

迭代关系选择Link to this heading#

ModelChoiceIteratorLink to this heading#

ModelChoiceIteratorValueLink to this heading#

创建自定义字段Link to this heading#

表单字段Link to this heading

核心字段参数Link to this heading

`required`Link to this heading

`label`Link to this heading

`label_suffix`Link to this heading

`initial`Link to this heading

`widget`Link to this heading

`help_text`Link to this heading

`error_messages`Link to this heading

`validators`Link to this heading

`localize`Link to this heading

`disabled`Link to this heading

检查字段数据是否有变化Link to this heading

`has_changed()`Link to this heading

内置 `Field` 类Link to this heading

`BooleanField`Link to this heading

`CharField`Link to this heading

`ChoiceField`Link to this heading

`DateField`Link to this heading

`DateTimeField`Link to this heading

`DecimalField`Link to this heading

`DurationField`Link to this heading

`EmailField`Link to this heading

`FileField`Link to this heading

`FilePathField`Link to this heading

`FloatField`Link to this heading

`GenericIPAddressField`Link to this heading

`ImageField`Link to this heading

`IntegerField`Link to this heading

`JSONField`Link to this heading

`MultipleChoiceField`Link to this heading

`NullBooleanField`Link to this heading

`RegexField`Link to this heading

`SlugField`Link to this heading

`TimeField`Link to this heading

`TypedChoiceField`Link to this heading

`TypedMultipleChoiceField`Link to this heading

`URLField`Link to this heading

`UUIDField`Link to this heading

稍复杂的内置 `Field` 类Link to this heading

`ComboField`Link to this heading

`MultiValueField`Link to this heading

`SplitDateTimeField`Link to this heading

处理关系的字段Link to this heading

`ModelChoiceField`Link to this heading

`ModelMultipleChoiceField`Link to this heading

迭代关系选择Link to this heading

`ModelChoiceIterator`Link to this heading

`ModelChoiceIteratorValue`Link to this heading

创建自定义字段Link to this heading