表单字段

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 中显示时，会用到这个标签。

As explained in 将表单输出为 HTML, the default label for a Field is generated from the field name by converting all underscores to spaces and upper-casing the first letter. Specify a string for label if that default behavior doesn't result in an adequate label. Use an empty string ("") to hide the 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)
Your name:
Your website:
Comment:

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)
Age?
Nationality?
2 + 2 =

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)
Name:
Url:
Comment:

你可能会想，为什么不在显示表单时直接传递初始值的字典作为数据呢？如果你这样做，你会触发验证，并且 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)
Name:
  

Url:
  
Enter a valid URL.
  

Comment:
  
This field is required.
  

这就是为什么 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())
Day:

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

widget

Field.widget

widget 参数让你指定一个 Widget 类，以便在渲染这个 Field 时使用。参见 部件 了解更多信息。

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)
Subject:
100 characters max.

Message:
Sender:
A valid email address, please.

Cc myself:

当字段有帮助文本时，它使用 aria-describedby HTML 属性与其输入关联。如果小部件在

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

Username:
e.g., user@example.com

>>> 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"])

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

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

bound_field_class

Field.bound_field_class

The bound_field_class attribute allows a per-field override of Form.bound_field_class.

has_changed()

Field.has_changed()[source]

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

See the Form.has_changed documentation for more information.

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 代替。

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

Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

allow_folders

Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be 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.

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

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

此外，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

A json.JSONEncoder subclass to serialize data types not supported by the standard JSON serializer (e.g. datetime.datetime or UUID). For example, you can use the DjangoJSONEncoder class.

默认为 json.JSONEncoder。

decoder

A json.JSONDecoder subclass to deserialize the input. Your deserialization may need to account for the fact that you can't be certain of the input type. For example, you run the risk of returning a datetime that was actually a string that just happened to be in the same format chosen for datetimes.

The decoder can be used to validate the input. If json.JSONDecodeError is raised during the deserialization, a ValidationError will be raised.

默认为 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

The scheme assumed for URLs provided without one. Defaults to "https". For example, if assume_scheme is "https" and the provided value is "example.com", the normalized value will be "https://example.com".

UUIDField

class UUIDField(**kwargs)[source]

• 默认部件：TextInput

• 空值：None

• 规范化为：UUID 对象。

• 错误信息键：required、invalid

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

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

A tuple of fields whose values are cleaned and subsequently combined into a single value. Each value of the field is cleaned by the corresponding field in fields -- the first value is cleaned by the first field, the second value is cleaned by the second field, etc. Once all fields are cleaned, the list of clean values is combined into a single value by 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

class ModelChoiceField(**kwargs)[source]

• 默认部件：Select

• 空值：None

• 规范化为：一个模型实例。

• 验证给定的 id 是否存在于查询集中。

• 错误信息键：required、invalid_choice

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

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

需要一个参数：

queryset

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

ModelChoiceField 还接受几个可选参数：

empty_label

默认情况下，ModelChoiceField 使用的 小组件将在列表顶部有一个空的选择。你可以用 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">Object1option>
<option value="obj2.pk">Object2option>
...
select>

和：

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

会产生：

<select id="id_field2" name="field2">
<option value="obj1.name">Object1option>
<option value="obj2.name">Object2option>
...
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 添加到 。

例如，考虑以下模型：

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，包含在每个 元素中：

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">mushroomsoption>
<option value="2" data-price="1.25">onionsoption>
<option value="3" data-price="1.75">peppersoption>
<option value="4" data-price="2.00">pineappleoption>
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 元素的 value 属性。

instance

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

ModelChoiceIteratorValue 有以下方法：

__str__()[source]

返回 value 作为一个字符串在 HTML 中显示。

创建自定义字段

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

You can also customize how a field will be accessed by overriding bound_field_class or override Field.get_bound_field() if you need more flexibility when creating the BoundField:

Field.get_bound_field(form, field_name)[source]

Takes an instance of Form and the name of the field. The returned BoundField instance will be used when accessing the field in a template.

See 自定义 BoundField for examples of overriding a BoundField.

Django Python API参考 Web开发

上一篇：Django参考文档：表单 API

下一篇：Django参考文档：表单集函数

相关内容

热门资讯

玻璃硬盘原理图 玻璃硬盘原理 玻璃硬盘，又称为磁头悬浮硬盘（Magnetic Head Flying Disk，MHFD），是一种...

闲鱼搜索规则与技巧 闲鱼最新特... 在闲鱼这个二手交易平台上，有很多用户都希望能够找到一些特殊的东西，比如一些罕见的收藏品、独特的手工艺...

家里监控最长能保存多少天的记录... 家里监控一般保存多久 随着科技的发展，家庭监控系统已经成为了许多家庭的必备设备，它不仅可以帮助我们...

华为tag有用吗 华为tag-... 华为Tag是华为手机中的一种功能，它可以帮助用户更好地管理自己的手机数据和应用，通过使用华为Tag，...

ps5手柄可用手机快充充电吗 ... PS5手柄，即PlayStation 5的DualSense手柄，是索尼公司为PlayStation...

QQ音乐提示代理模式可能无法正... QQ音乐提示代理模式可能无法正常访问，如上图所示，是怎么回事呢？ 这个可能和你的网络设置有关系，首先...

收到微信有提示音怎么去掉 微信... 微信收到信息没有提示音，可能是由多种原因导致的，以下是一些可能的原因及解决方法： 1. 手机静音或...

a100显卡对应的cuda版本 在进行GPU加速的编程中，CUDA是常用的架构和平台，其版本和显卡型号之间存在着一定的对应关系。本篇...

别人打电话听不见我说话怎么回事... 当我们在使用手机时，可能会遇到别人打电话过来听不见声音的情况，这种情况可能是由多种原因导致的，下面我...

苹果手机非通讯录电话打不进来 ... 手机电话打不进来可能有多种原因，以下是一些常见的问题及解决方法： 1. **信号问题**： ...

2026 © 晓说杂谈 豫ICP备13019747号-13

• 科技分享
• 网络技术
• 硬件设备
• 程序人生
• 探索发现
• 机械加工
• 电商
• 其他
• 日常知识
• 每日语录