表单域

class Field(**kwargs)

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

Field.clean(value)

尽管使用 Field 类的主要方式是在 Form 类中，但您也可以实例化它们并直接使用它们以更好地了解它们的工作方式。每个 Field 实例都有一个 clean() 方法，该方法接受一个参数并引发 django.core.exceptions.ValidationError 异常或返回干净值：

>>> 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.']

核心字段参数

每个 Field 类构造函数至少接受这些参数。一些 Field 类采用额外的、特定于字段的参数，但以下内容应始终被接受：

required

Field.required

默认情况下，每个 Field 类都假定该值是必需的，因此如果您传递一个空值 – None 或空字符串 ("") – 那么 [ X156X] 将引发 ValidationError 异常：

>>> 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 构造函数：

>>> 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

Field.label

label 参数允许您为此字段指定“人性化”标签。当 Field 显示在 Form 中时使用。

如上面“将表单输出为 HTML”所述，Field 的默认标签是通过将所有下划线转换为空格并将第一个字母大写从字段名称生成的。如果默认行为没有产生足够的标签，请指定 label。

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

>>> 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

Field.label_suffix

label_suffix 参数允许您在每个字段的基础上覆盖表单的 label_suffix：

>>> 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>

initial

Field.initial

initial 参数允许您指定在未绑定的 Form 中渲染此 Field 时要使用的初始值。

要指定动态初始数据，请参阅 Form.initial 参数。

用例是当您想要显示一个“空”表单时，其中的字段被初始化为特定值。例如：

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial='Your name')
...     url = forms.URLField(initial='http://')
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

您可能会想，为什么不在显示表单时将初始值的字典作为数据传递？好吧，如果您这样做，您将触发验证，并且 HTML 输出将包含任何验证错误：

>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
>>> default_data = {'name': 'Your name', 'url': 'http://'}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>

这就是为什么 initial 值仅对未绑定表单显示的原因。对于绑定表单，HTML 输出将使用绑定数据。

另请注意，如果未给出特定字段的值，则 initial 值是而非用作验证中的“后备”数据。 initial 值是 only 用于初始表格显示：

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial='Your name')
...     url = forms.URLField(initial='http://')
...     comment = forms.CharField()
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}

除了常量，您还可以传递任何可调用对象：

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>

只有在显示未绑定的表单时才会评估可调用对象，而不是在定义它时。

help_text

Field.help_text

help_text 参数允许您为此 Field 指定描述性文本。如果您提供 help_text，当 Field 通过其中一种便利的 Form 方法（例如 as_ul()）。

与模型字段的 help_text 一样，该值在自动生成的表单中不是 HTML 转义的。

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

>>> 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

Field.error_messages

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

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

这是一条自定义错误消息：

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

在下面的内置字段类部分中，每个 Field 定义了它使用的错误消息键。

validators

Field.validators

validators 参数允许您为此字段提供验证函数列表。

有关更多信息，请参阅验证器文档。

localize

Field.localize

localize 参数启用表单数据输入以及渲染输出的本地化。

有关更多信息，请参阅格式本地化文档。

disabled

Field.disabled

disabled 布尔参数设置为 True 时，会禁用使用 disabled HTML 属性的表单字段，以便用户无法对其进行编辑。即使用户篡改了提交给服务器的字段值，它也会被忽略，取而代之的是表单初始数据中的值。

检查字段数据是否已更改

has_changed()

Field.has_changed()

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

有关更多信息，请参阅 Form.has_changed() 文档。

内置 Field 类

自然地，forms 库带有一组代表常见验证需求的 Field 类。本节记录每个内置字段。

对于每个字段，如果您未指定 widget，我们将描述使用的默认小部件。我们还指定了当您提供空值时返回的值（请参阅上面有关 required 的部分以了解其含义）。

BooleanField

class BooleanField(**kwargs)

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

笔记

由于所有 Field 子类默认都有 required=True，所以这里的验证条件很重要。如果您想在表单中包含一个布尔值，它可以是 True 或 False（例如一个勾选或未勾选的复选框），创建BooleanField时一定要记得传入required=False。

CharField

class CharField(**kwargs)

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

有四个可选的验证参数：

max_length

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

strip: 如果 True（默认），该值将被去除前导和尾随空格。

empty_value: 用于表示“空”的值。默认为空字符串。

ChoiceField

class ChoiceField(**kwargs)

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

invalid_choice 错误消息可能包含 %(value)s，它将被替换为选定的选项。

需要一个额外的参数：

choices: 用作此字段选项的 2 元组的 iterable、enumeration 选项或返回此类可迭代对象的可调用对象。此参数接受与模型字段的 choices 参数相同的格式。有关更多详细信息，请参阅有关选择的模型字段参考文档。如果参数是可调用的，除了在渲染期间，每次初始化字段的表单时都会对其进行评估。默认为空列表。

TypedChoiceField

class TypedChoiceField(**kwargs)

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

默认小部件：选择
空值：无论你给出的是 empty_value。
规范化为： coerce 参数提供的类型的值。
验证给定的值存在于选项列表中并且可以被强制。
错误信息键：required、invalid_choice

需要额外的参数：

coerce: 一个接受一个参数并返回一个强制值的函数。示例包括内置 int、float、bool 和其他类型。默认为身份函数。请注意，强制发生在输入验证之后，因此可以强制转换为 choices 中不存在的值。

empty_value: 用于表示“空”的值。默认为空字符串； None 是这里的另一个常见选择。请注意，此值不会被 coerce 参数中给出的函数强制转换，因此请相应地选择它。

DateField

class DateField(**kwargs)

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

采用一个可选参数：

input_formats: 用于尝试将字符串转换为有效 datetime.date 对象的格式列表。

如果未提供 input_formats 参数，则默认输入格式取自 :setting:`DATE_INPUT_FORMATS` 如果 :setting:`USE_L10N` 是 False ]，或者从活动区域设置格式 DATE_INPUT_FORMATS 键（如果启用了本地化）。另见格式本地化。

DateTimeField

class DateTimeField(**kwargs)

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

采用一个可选参数：

input_formats: 用于尝试将字符串转换为有效 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 参数，则默认输入格式取自 :setting:`DATETIME_INPUT_FORMATS` 和 :setting:`DATE_INPUT_FORMATS` 如果 :setting :`USE_L10N` 是 False，或者如果启用了本地化，则来自活动语言环境格式 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 键。另见格式本地化。

3.1 版更改：添加了对 ISO 8601 日期字符串解析（包括可选时区）的支持。

添加了默认 input_formats 中 DATE_INPUT_FORMATS 的后备。

DecimalField

class DecimalField(**kwargs)

默认小部件：NumberInput 当 Field.localize 为 False 时，否则为 TextInput。
空值：None
标准化为：Python decimal。
验证给定的值是小数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。忽略前导和尾随空格。
错误信息键：required、invalid、max_value、min_value、max_digits、max_decimal_places、[ X90X]

max_value 和 min_value 错误消息可能包含 %(limit_value)s，它们将被适当的限制替换。类似地，max_digits、max_decimal_places 和 max_whole_digits 错误消息可能包含 %(max)s。

采用四个可选参数：

max_value

min_value: 这些控制字段中允许的值范围，应以 decimal.Decimal 值的形式给出。

max_digits: 值中允许的最大位数（小数点前加小数点后，去掉前导零）。

decimal_places: 允许的最大小数位数。

DurationField

class DurationField(**kwargs)

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

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

EmailField

class EmailField(**kwargs)

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

具有三个可选参数 max_length、min_length 和 empty_value，它们的工作方式与 CharField 一样。

FileField

class FileField(**kwargs)

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

有两个可选的验证参数，max_length 和 allow_empty_file。如果提供，这些确保文件名最多为给定的长度，即使文件内容为空，验证也会成功。

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

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

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

FilePathField

class FilePathField(**kwargs)

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

该字段允许从某个目录中的文件中进行选择。它需要五个额外的参数；仅需要 path：

path: 要列出其内容的目录的绝对路径。该目录必须存在。

recursive: 如果False（默认）只有path的直接内容将被提供作为选择。如果是True，目录将被递归下降，所有后代将作为选择列出。

match: 正则表达式模式；仅允许名称与此表达式匹配的文件作为选择。

allow_files: 可选的。 True 或 False。默认值为 True。指定是否应包含指定位置的文件。此或 allow_folders 必须为 True。

allow_folders: 可选的。 True 或 False。默认值为 False。指定是否应包括指定位置的文件夹。此或 allow_files 必须为 True。

FloatField

class FloatField(**kwargs)

默认小部件：NumberInput 当 Field.localize 为 False 时，否则为 TextInput。
空值：None
规范化为：Python 浮点数。
验证给定的值是一个浮点数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。允许前导和尾随空格，如 Python 的 float() 函数。
错误信息键：required、invalid、max_value、min_value

采用两个可选参数进行验证，max_value 和 min_value。这些控制字段中允许的值范围。

ImageField

class ImageField(**kwargs)

默认小部件：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()。例如：

>>> 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', <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>

此外，如果 Pillow 可以确定 UploadedFile.content_type 将使用图像的内容类型更新，否则将设置为 None。

IntegerField

class IntegerField(**kwargs)

默认小部件：NumberInput 当 Field.localize 为 False 时，否则为 TextInput。
空值：None
规范化为：一个 Python 整数。
验证给定的值是一个整数。如果提供了 max_value 和 min_value，则使用 MaxValueValidator 和 MinValueValidator。允许前导和尾随空格，如 Python 的 int() 函数。
错误信息键：required、invalid、max_value、min_value

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

采用两个可选参数进行验证：

max_value

min_value: 这些控制字段中允许的值范围。

JSONField

class JSONField(encoder=None, decoder=None, **kwargs)

3.1 版中的新功能。

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

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

采用两个可选参数：

encoder

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

默认为 json.JSONEncoder。

decoder

用于反序列化输入的 json.JSONDecoder 子类。您的反序列化可能需要考虑到您无法确定输入类型的事实。例如，您冒着返回 datetime 的风险，该字符串实际上是一个恰好与为 datetime 选择的格式相同的字符串。

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

默认为 json.JSONDecoder。

笔记

如果您使用 ModelForm，则将使用 JSONField 中的 encoder 和 decoder。

用户友好的表格

JSONField 在大多数情况下不是特别用户友好。但是，这是一种从客户端小部件格式化数据以提交到服务器的有用方法。

GenericIPAddressField

class GenericIPAddressField(**kwargs)

包含 IPv4 或 IPv6 地址的字段。

默认小部件：TextInput
空值：（空字符串）
规范化为：一个字符串。 IPv6 地址按如下所述进行规范化。
验证给定的值是有效的 IP 地址。
错误信息键：required、invalid

IPv6 地址规范化遵循 RFC 4291#section-2.2 第 2.2 节，包括使用该节第 3 段中建议的 IPv4 格式，如 ::ffff:192.0.2.0。例如，2001:0::0:01 将归一化为 2001::1，而 ::ffff:0a0a:0a0a 将归一化为 ::ffff:10.10.10.10。所有字符都转换为小写。

采用两个可选参数：

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

unpack_ipv4: 解压缩 IPv4 映射地址，如 ::ffff:192.0.2.1。如果启用此选项，该地址将被解压缩到 192.0.2.1。默认为禁用。仅当 protocol 设置为 'both' 时才能使用。

MultipleChoiceField

class MultipleChoiceField(**kwargs)

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

invalid_choice 错误消息可能包含 %(value)s，它将被替换为选定的选项。

需要一个额外的必需参数，choices，就像 ChoiceField。

TypedMultipleChoiceField

class TypedMultipleChoiceField(**kwargs)

就像 MultipleChoiceField，除了 TypedMultipleChoiceField 需要两个额外的参数，coerce 和 empty_value。

默认小部件：SelectMultiple
空值：无论你给出的是 empty_value
规范化为：coerce 参数提供的类型的值列表。
验证给定的值存在于选项列表中并且可以被强制。
错误信息键：required、invalid_choice

invalid_choice 错误消息可能包含 %(value)s，它将被替换为选定的选项。

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

NullBooleanField

class NullBooleanField(**kwargs)

默认小部件：NullBooleanSelect
空值：None
标准化为：Python True、False 或 None 值。
不验证任何内容（即，它从不引发 ValidationError）。

NullBooleanField 可以通过提供小部件 choices 与小部件一起使用，例如 Select 或 RadioSelect：

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

RegexField

class RegexField(**kwargs)

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

接受一个必需的参数：

regex: 指定为字符串或编译的正则表达式对象的正则表达式。

还采用 max_length、min_length、strip 和 empty_value，它们的作用与 CharField 一样。

strip: 默认为 False。如果启用，将在正则表达式验证之前应用剥离。

SlugField

class SlugField(**kwargs)

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

此字段旨在用于在表单中表示模型 SlugField。

采用两个可选参数：

allow_unicode: 指示字段除 ASCII 字母外还接受 Unicode 字母的布尔值。默认为 False。

empty_value: 用于表示“空”的值。默认为空字符串。

TimeField

class TimeField(**kwargs)

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

采用一个可选参数：

input_formats: 用于尝试将字符串转换为有效 datetime.time 对象的格式列表。

如果未提供 input_formats 参数，则默认输入格式取自 :setting:`TIME_INPUT_FORMATS` 如果 :setting:`USE_L10N` 是 False ]，或从活动区域设置格式 TIME_INPUT_FORMATS 键（如果启用了本地化）。另见格式本地化。

URLField

class URLField(**kwargs)

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

具有三个可选参数 max_length、min_length 和 empty_value，它们的工作方式与 CharField 一样。

UUIDField

class UUIDField(**kwargs)

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

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

稍微复杂的内置 Field 类

ComboField

class ComboField(**kwargs)

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

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

fields

用于验证字段值的字段列表（按提供顺序）。

>>> 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

class MultiValueField(fields=(), **kwargs)

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

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

该字段是抽象的，必须是子类。与单值字段相比，MultiValueField 的子类不能实现 clean()，而是 - 实现 compress()。

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

fields: 字段的元组，其值被清理并随后组合成单个值。该字段的每个值都由 fields 中的相应字段清理 - 第一个值由第一个字段清理，第二个值由第二个字段清理，依此类推。清理完所有字段后，清理值列表将通过 compress() 合并为一个值。

还需要一些可选参数：

require_all_fields

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

当设置为 False 时，可以将 Field.required 属性设置为 False 以针对单个字段使它们成为可选。如果没有为必填字段提供值，则会引发 incomplete 验证错误。

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

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
        )

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

compress(data_list)

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

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

SplitDateTimeField

class SplitDateTimeField(**kwargs)

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

采用两个可选参数：

input_date_formats: 用于尝试将字符串转换为有效 datetime.date 对象的格式列表。

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

input_time_formats: 用于尝试将字符串转换为有效 datetime.time 对象的格式列表。

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

处理关系的字段

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

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

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

class ModelChoiceField(**kwargs)

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

允许选择单个模型对象，适用于表示外键。请注意，当条目数量增加时，ModelChoiceField 的默认小部件变得不切实际。您应该避免将它用于 100 多个项目。

需要一个参数：

queryset: 模型对象的 QuerySet，从中派生字段选择并用于验证用户的选择。在呈现表单时对其进行评估。

ModelChoiceField 也有两个可选参数：

empty_label

默认情况下，ModelChoiceField 使用的 <select> 小部件将在列表顶部有一个空选项。您可以使用 empty_label 属性更改此标签的文本（默认为 "---------"），也可以通过将 empty_label 设置为 None：

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

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

请注意，如果需要 ModelChoiceField 且具有默认初始值，则不会创建空选项（无论 empty_label 的值如何）。

to_field_name

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

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

会产生：

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

和：

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

会产生：

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

ModelChoiceField 也有属性：

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

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

from django.forms import ModelChoiceField

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

ModelMultipleChoiceField

class ModelMultipleChoiceField(**kwargs)

默认小部件：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 自定义对象表示。

需要一个参数：

queryset: 与 ModelChoiceField.queryset 相同。

采用一个可选参数：

to_field_name: 与 ModelChoiceField.to_field_name 相同。

ModelMultipleChoiceField 也有属性：

iterator: 与 ModelChoiceField.iterator 相同。

自 3.1 版起已弃用：不推荐使用 list 消息，请改用 invalid_list。

迭代关系选择

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

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

例如，考虑以下模型：

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 的值包含为每个 <option> 元素的 HTML 属性 data-price：

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 选择为：

<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 以自定义生成的 2 元组选项。

ModelChoiceIterator

class ModelChoiceIterator(field)

分配给 ModelChoiceField 和 ModelMultipleChoiceField 的 iterator 属性的默认类。从查询集中产生 2 元组选择的可迭代对象。

需要一个参数：

field: ModelChoiceField 或 ModelMultipleChoiceField 的实例，用于迭代和产生选择。

ModelChoiceIterator有如下方法：

__iter__(): 产生 2 元组选择，采用 ChoiceField.choices 使用的 (value, label) 格式。第一个 value 元素是一个 ModelChoiceIteratorValue 实例。

3.1 版更改：在旧版本中，选择元组中的第一个 value 元素是 field 值本身，而不是 ModelChoiceIteratorValue 实例。在大多数情况下，此代理是透明的，但是，如果您需要 field 值本身，请改用 ModelChoiceIteratorValue.value 属性。

ModelChoiceIteratorValue

class ModelChoiceIteratorValue(value, instance)

3.1 版中的新功能。

需要两个参数：

value: 选择的价值。此值用于呈现 HTML <option> 元素的 value 属性。

instance: 查询集中的模型实例。可以在自定义 ChoiceWidget.create_option() 实现中访问该实例以调整呈现的 HTML。

ModelChoiceIteratorValue有如下方法：

__str__(): 将 value 作为要在 HTML 中呈现的字符串返回。

创建自定义字段

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

您还可以通过覆盖 get_bound_field() 来自定义如何访问字段。

表单域 — Django 文档

表单域

核心字段参数

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

检查字段数据是否已更改

has_changed()

内置 Field 类

BooleanField

CharField

ChoiceField

TypedChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

ImageField

IntegerField

JSONField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

稍微复杂的内置 Field 类

ComboField

MultiValueField

SplitDateTimeField

处理关系的字段

ModelChoiceField

ModelMultipleChoiceField

迭代关系选择

ModelChoiceIterator

ModelChoiceIteratorValue

创建自定义字段