获取帮助

el
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
语言：en

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
文档版本：5.1

表单字段¶

class Field[source]¶

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

Field.clean(value)[source]¶

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

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("[email protected]")
'[email protected]'
>>> 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., [email protected]")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., [email protected]</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., [email protected]",
...         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>

Django 5.0 中的更改

添加了 aria-describedby 以将 help_text 与其输入相关联。

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 类部分，每个 Field 都定义了它使用的错误消息键。

`validators`¶

Field.validators¶

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

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

`localize`¶

Field.localize¶

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

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

`disabled`¶

Field.disabled¶

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

`template_name`¶

Field.template_name¶

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

注意

由于所有 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 参数相同的格式。有关更多详细信息，请参阅模型字段参考文档中的选项。如果该参数是可调用的，则在每次初始化字段的表单时以及在渲染期间对其进行评估。默认为空列表。

选项类型

此字段将选项规范化为字符串，因此，如果需要其他数据类型（如整数或布尔值）的选项，请考虑使用 TypedChoiceField。

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 第 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 地址。
错误消息键：required、invalid

IPv6 地址规范化遵循 RFC 4291 第 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' 时才能使用。

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

此外，如果Pillow可以确定图像的媒体类型，则UploadedFile.content_type将更新为该媒体类型，否则将其设置为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]¶

一个字段，接受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并不是特别用户友好。但是，它是一种将来自客户端小部件的数据格式化为提交到服务器的有用方法。

`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 可以与 Select 或 RadioSelect 等小部件一起使用，方法是为小部件提供 choices

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。如果启用，则在正则表达式验证之前应用去除空格操作。

`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，它将被选定的选项替换。

与 TypedChoiceField 一样，需要两个额外的参数 coerce 和 empty_value。

`URLField`¶

class URLField(**kwargs)[source]¶

默认小部件：URLInput
空值：您作为 empty_value 提供的任何值。
规范化为：字符串。
使用 URLValidator 验证给定值是否为有效的 URL。
错误消息键：required、invalid

具有可选参数 max_length、min_length、empty_value，它们的作用与 CharField 中的一样，以及另一个参数

assume_scheme¶: Django 5.0 中的新功能。

为未提供方案的 URL 假设的方案。默认为 "http"。例如，如果 assume_scheme 为 "https" 且提供的值为 "example.com"，则规范化后的值为 "https://example.com"。

自版本 5.0 起已弃用: assume_scheme 的默认值将从 Django 6.0 中的 "http" 更改为 "https"。将 FORMS_URLFIELD_ASSUME_HTTPS 过渡设置设置为 True 以选择在 Django 5.x 发布周期中使用 "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("[email protected]")
'[email protected]'
>>> f.clean("[email protected]")
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 验证错误。

设置为 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)[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 且 blank 参数为 False，则不会创建空选项（无论 empty_label 的值如何）。

to_field_name¶

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

# 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，它们将被相应的 value 替换。

允许选择一个或多个模型对象，适合表示多对多关系。与 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 元素的 2 元组选项。ModelChoiceIteratorValue 包装选项值，同时保持对源模型实例的引用，该实例可用于自定义小部件实现，例如，向 <option> 元素添加 data-* 属性。

例如，考虑以下模型

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

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)[source]¶

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

需要一个参数

field¶: ModelChoiceField 或 ModelMultipleChoiceField 的实例，用于迭代并生成选择项。

ModelChoiceIterator 具有以下方法

__iter__()[source]¶: 生成 2 元组的选择项，格式为 (value, label)，与 ChoiceField.choices 使用的格式相同。第一个 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() 来自定义访问字段的方式。

表单 API

模型表单函数

返回顶部

文档

表单字段¶

核心字段参数¶

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¶

创建自定义字段¶

其他信息

支持 Django！

内容

浏览

您当前位置

获取帮助

下载

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