表单字段¶

class Field[source]¶

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

Field.clean(value)[source]¶

虽然你主要会在 Form 类中使用 Field 类，但你也可以实例化它们并直接使用它们来更好地了解它们的工作原理。每个 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 还是空字符串（""）-- 那么 clean() 将引发一个 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(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)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>

`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)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>

`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="https://")
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>

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

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

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

还要注意，如果没有提供特定字段的值，initial 值不会用作验证的 "回退" 数据。initial 值仅用于初始表单显示：

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback 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())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>

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

`help_text`¶

Field.help_text¶

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

就像模型字段的 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)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
<div>Cc myself:<input type="checkbox" name="cc_myself"></div>

当字段有帮助文本时，它使用 aria-describedby HTML 属性与其输入关联。如果小部件在 <fieldset> 中渲染，则 aria-describedby 会添加到此元素，否则会添加到小部件的 <input>：

>>> from django import forms
>>> class UserForm(forms.Form):
...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>

当添加自定义的 aria-describedby 属性时，请确保以所需的顺序还包括 help_text 元素的 id （如果使用）。对于屏幕阅读器用户，描述将按照它们在 aria-describedby 中出现的顺序进行阅读：

>>> class UserForm(forms.Form):
...     username = forms.CharField(
...         max_length=255,
...         help_text="e.g., user@example.com",
...         widget=forms.TextInput(
...             attrs={"aria-describedby": "custom-description id_username_helptext"},
...         ),
...     )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>

Changed in Django 5.0:

已添加 aria-describedby 以将 help_text 与其输入关联起来。

Changed in Django 5.1:

为 <fieldset> 添加了 aria-describedby 支持。

`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 属性禁用表单字段，使其不能被用户编辑。即使用户篡改了提交给服务器的字段值，也会被忽略，而采用表单初始数据的值。

`template_name`¶

Field.template_name¶

New in Django 5.0.

template_name 参数允许在使用 as_field_group() 渲染字段时使用自定义模板。默认情况下，该值设置为 "django/forms/field.html"。可以通过覆盖此属性来为每个字段更改它，或者更一般地，可以通过覆盖默认模板来更改它，另请参阅覆盖内置字段模板。

检查字段数据是否有变化¶

`has_changed()`¶

Field.has_changed()[source]¶

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

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

内置 `Field` 类¶

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

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

`BooleanField`¶

class BooleanField(**kwargs)[source]¶

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

Note

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

`CharField`¶

class CharField(**kwargs)[source]¶

默认部件：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)[source]¶

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

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

需要一个额外的参数：

choices[source]¶: 可以是一个包含 2 元组的可迭代对象，用作此字段的选项，也可以是返回这种可迭代对象的可调用对象。此参数接受与模型字段的 choices 参数相同的格式。有关更多详细信息，请参阅模型字段参考文档中的 choices。如果该参数是可调用的，它将在每次初始化字段的表单时进行评估，以及在渲染时进行评估。默认为一个空列表。

选择类型

这个字段将选择项标准化为字符串，所以如果选择项需要其他数据类型，比如整数或布尔值，请考虑使用 TypedChoiceField 代替。

Changed in Django 5.0:

已添加对映射和直接在 choices 中使用枚举类型的支持。

`DateField`¶

class DateField(**kwargs)[source]¶

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

需要一个可选的参数：

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

如果未提供 input_formats 参数，则默认的输入格式将从活动区域设置的 DATE_INPUT_FORMATS 键中获取，或者如果禁用了本地化，则从 DATE_INPUT_FORMATS 获取。另请参阅格式本地化。

`DateTimeField`¶

class DateTimeField(**kwargs)[source]¶

默认部件：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 参数，则默认的输入格式将从活动区域设置的 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 键中获取，或者如果禁用了本地化，则从 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 获取。另请参阅格式本地化。

`DecimalField`¶

class DecimalField(**kwargs)[source]¶

当 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_value¶

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

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

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

step_size¶: 限制有效输入为 step_size 的整数倍。如果还提供了 min_value，则将其添加为偏移量以确定步长是否匹配。

`DurationField`¶

class DurationField(**kwargs)[source]¶

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

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

`EmailField`¶

class EmailField(**kwargs)[source]¶

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

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

`FileField`¶

class FileField(**kwargs)[source]¶

默认部件：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)[source]¶

默认部件：Select
空值：'' （空字符串）
规范化为：一个字符串。
验证选择是否存在于选择列表中。
错误信息键：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)[source]¶

当 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_value¶

min_value¶: 这些控制了该字段允许的数值范围。

step_size¶: 限制有效输入为 step_size 的整数倍。如果还提供了 min_value，则将其添加为偏移量以确定步长是否匹配。

`GenericIPAddressField`¶

class GenericIPAddressField(**kwargs)[source]¶

一个包含 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。所有字符都转换为小写。

接受三个可选参数：

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

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

max_length¶: Defaults to 39, and behaves the same way as it does for CharField.

Changed in Django 4.2.18:

The default value for max_length was set to 39 characters.

`ImageField`¶

class ImageField(**kwargs)[source]¶

默认部件：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", 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`¶

class IntegerField(**kwargs)[source]¶

当 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_value¶

min_value¶: 这些控制了该字段允许的数值范围。

step_size¶: 限制有效输入为 step_size 的整数倍。如果还提供了 min_value，则将其添加为偏移量以确定步长是否匹配。

`JSONField`¶

class JSONField(encoder=None, decoder=None, **kwargs)[source]¶

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

默认部件：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.JSONONDecodeError，则会出现 ValidationError。

默认为 json.JSONDecoder。

Note

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

用户友好的表单

JSONField 在大多数情况下不是特别方便用户使用。但是，它是一种有用的方式，可以将客户端部件的数据格式化，以便提交给服务器。

`MultipleChoiceField`¶

class MultipleChoiceField(**kwargs)[source]¶

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

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

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

`NullBooleanField`¶

class NullBooleanField(**kwargs)[source]¶

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

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

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

`RegexField`¶

class RegexField(**kwargs)[source]¶

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

需要一个额外的参数：

regex¶: 一个正则表达式，可以是字符串，也可以是编译后的正则表达式对象。

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

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

`SlugField`¶

class SlugField(**kwargs)[source]¶

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

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

需要两个可选的参数：

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

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

`TimeField`¶

class TimeField(**kwargs)[source]¶

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

需要一个可选的参数：

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

如果未提供 input_formats 参数，则默认的输入格式将从活动区域设置的 TIME_INPUT_FORMATS 键中获取，或者如果禁用了本地化，则从 TIME_INPUT_FORMATS 获取。另请参阅格式本地化。

`TypedChoiceField`¶

class TypedChoiceField(**kwargs)[source]¶

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

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

需要额外的参数：

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

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

`TypedMultipleChoiceField`¶

class TypedMultipleChoiceField(**kwargs)[source]¶

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

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

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

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

`URLField`¶

class URLField(**kwargs)[source]¶

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

具有可选参数 max_length、min_length、empty_value，它们的工作方式与 CharField 中的一样，并且还有一个额外的参数：

assume_scheme¶: New in Django 5.0.

对于没有指定的 URL，假定的方案是 "http"。例如，如果 assume_scheme 是 "https"，提供的值是 "example.com"，则规范化后的值将是 "https://example.com"。

Deprecato dalla versione 5.0: 在 Django 6.0 中，assume_scheme 的默认值将从 "http" 更改为 "https"。在 Django 5.x 发布周期中，可以设置 FORMS_URLFIELD_ASSUME_HTTPS 过渡设置为 True，以选择在使用 "https"。

`UUIDField`¶

class UUIDField(**kwargs)[source]¶

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

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

稍复杂的内置 `Field` 类¶

`ComboField`¶

class ComboField(**kwargs)[source]¶

默认部件：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)[source]¶

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

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

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

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

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

还需要一些可选的参数：

require_all_fields¶

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

Field.required 属性设置为 False 时，可将单个字段设置为 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)[source]¶

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

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

`SplitDateTimeField`¶

class SplitDateTimeField(**kwargs)[source]¶

默认部件：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)[source]¶

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

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

允许选择一个单一的模型对象，适合代表一个外键。请注意，当条目数量增加时，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 是必填的并且具有默认的初始值，或者 widget 设置为 RadioSelect 并且 ModelChoiceField.blank 参数为 False，则不会创建空选择项（无论 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>

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

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)[source]¶

默认部件：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 相同。

迭代关系选择¶

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

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

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 子类化，以自定义产生的二元元组选择。

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)[source]¶

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

需要一个参数：

field¶: ModelChoiceField 或 ModelMultipleChoiceField 的实例来迭代和产生选择。

ModelChoiceIter 有以下方法：

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

`ModelChoiceIteratorValue`¶

class ModelChoiceIteratorValue(value, instance)[source]¶

需要两个参数：

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

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

ModelChoiceIteratorValue 有以下方法：

__str__()[source]¶: 返回 value 作为一个字符串在 HTML 中显示。

创建自定义字段¶

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

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

表单字段¶

核心字段参数¶

required¶

label¶

label_suffix¶

initial¶

widget¶

help_text¶

error_messages¶

validators¶

localize¶

disabled¶

template_name¶

检查字段数据是否有变化¶

has_changed()¶

内置 Field 类¶

BooleanField¶

CharField¶

ChoiceField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FilePathField¶

FloatField¶

GenericIPAddressField¶

ImageField¶

IntegerField¶

JSONField¶

MultipleChoiceField¶

NullBooleanField¶

RegexField¶

SlugField¶

TimeField¶

TypedChoiceField¶

TypedMultipleChoiceField¶

URLField¶

UUIDField¶

稍复杂的内置 Field 类¶

ComboField¶

MultiValueField¶

SplitDateTimeField¶

处理关系的字段¶

ModelChoiceField¶

ModelMultipleChoiceField¶

迭代关系选择¶

ModelChoiceIterator¶

ModelChoiceIteratorValue¶

创建自定义字段¶

Additional Information

Support Django!

Contents

Getting help

Download:

`required`¶

`label`¶

`label_suffix`¶

`initial`¶

`widget`¶

`help_text`¶

`error_messages`¶

`validators`¶

`localize`¶

`disabled`¶

`template_name`¶

`has_changed()`¶

内置 `Field` 类¶

`BooleanField`¶

`CharField`¶

`ChoiceField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FilePathField`¶

`FloatField`¶

`GenericIPAddressField`¶

`ImageField`¶

`IntegerField`¶

`JSONField`¶

`MultipleChoiceField`¶

`NullBooleanField`¶

`RegexField`¶

`SlugField`¶

`TimeField`¶

`TypedChoiceField`¶

`TypedMultipleChoiceField`¶

`URLField`¶

`UUIDField`¶

稍复杂的内置 `Field` 类¶

`ComboField`¶

`MultiValueField`¶

`SplitDateTimeField`¶

`ModelChoiceField`¶

`ModelMultipleChoiceField`¶

`ModelChoiceIterator`¶

`ModelChoiceIteratorValue`¶