Django 5.1.dev 文档

Home | Table of contents | Index | Modules

« previous | up | next »

表单字段¶

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 或空字符串 ("" )--然后 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(" ")
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

要将字段指定为 not 必填，通过 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'

如果A 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 参数允许您指定呈现此项时要使用的初始值 Field 未绑定的 Form .

要指定动态初始数据，请参见 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 值为 not 如果未给出特定字段的值，则在验证中用作“备用”数据。 initial 值为 only 用于初始表单显示：

>>> 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* 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())
<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 当 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)
<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 属性，请确保还包括 id 的 help_text 元素(如果使用)按所需顺序排列。对于屏幕阅读器用户，将按其在内部的出现顺序阅读描述 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 Development version:

aria-describedby 添加了对以下各项的支持 <fieldset> 。

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

在 built-in Field classes 以下各节 Field 定义它使用的错误消息键。

`validators`¶

Field.validators¶

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

见 validators documentation 更多信息。

`localize`¶

Field.localize¶

这个 localize 参数启用表单数据输入以及呈现的输出的本地化。

见 format localization 有关详细信息的文档。

`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()[源代码]¶

这个 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 （例如，选中或未选中的复选框），您必须记住输入 required=False 当创建 BooleanField .

`CharField`¶

class CharField(**kwargs)[源代码]¶

默认小部件： TextInput
空值：你所给予的一切 empty_value .
规范化为：字符串。
使用 MaxLengthValidator 和 MinLengthValidator 如果 max_length 和 min_length 提供。否则，所有输入都有效。
错误消息键： required ， max_length ， min_length

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

max_length¶

min_length¶: 如果提供了这些参数，这些参数将确保字符串的长度不超过给定的长度。

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

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

`ChoiceField`¶

class ChoiceField(**kwargs)[源代码]¶

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

这个 invalid_choice 错误消息可能包含 %(value)s ，将替换为所选选项。

多带一个参数：

choices¶: 要么是一个 iterable 要用作该字段的选项的2元组， enumeration type ，或返回此类迭代数的可调用对象。此参数接受的格式与 choices 参数添加到模型字段。请参阅 model field reference documentation on choices 了解更多详细信息。如果该参数是可调用的，则除了在呈现期间以外，每次初始化该字段的表单时都会对其进行计算。默认为空列表。

选择类型

此字段将选择标准化为字符串，因此如果其他数据类型(如整数或布尔值)需要选择，请考虑使用 TypedChoiceField 取而代之的是。

Changed in Django 5.0:

支持映射和使用 enumeration types 直接在 choices 已添加。

`DateField`¶

class DateField(**kwargs)[源代码]¶

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

接受一个可选参数：

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

如果没有 input_formats 参数，则默认输入格式取自活动区域设置格式 DATE_INPUT_FORMATS 密钥，或从 DATE_INPUT_FORMATS 如果本地化被禁用。另请参阅 format localization 。

`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 参数，则默认输入格式取自活动区域设置格式 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 密钥，或来自 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 如果本地化被禁用。另请参阅 format localization 。

`DecimalField`¶

class DecimalField(**kwargs)[源代码]¶

默认小部件： NumberInput 什么时候？ Field.localize 是 False ，否则 TextInput .
空值： None
规范化为：Python decimal .
验证给定值是否为小数。用途 MaxValueValidator 和 MinValueValidator 如果 max_value 和 min_value 都提供了。用途 StepValueValidator 如果 step_size 是提供的。前导空格和尾随空格被忽略。
错误消息键： 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)[源代码]¶

默认小部件： 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 。这个 max_length 参数默认为320(请参见 RFC 3696#section-3 )。

`FileField`¶

class FileField(**kwargs)[源代码]¶

默认小部件： ClearableFileInput
空值： None
规范化为： UploadedFile 将文件内容和文件名包装为单个对象的对象。
无法验证非空文件数据是否已绑定到表单。
错误消息键： required ， invalid ， missing ， empty ， max_length

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

了解更多关于 UploadedFile 对象，请参见 file uploads documentation .

当你使用 FileField 在表格中，您还必须记住 bind the file data to the form .

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

`FilePathField`¶

class FilePathField(**kwargs)[源代码]¶

默认小部件： 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)[源代码]¶

默认小部件： NumberInput 什么时候？ Field.localize 是 False ，否则 TextInput .
空值： None
规范化为：python float。
验证给定值是否为浮点型。用途 MaxValueValidator 和 MinValueValidator 如果 max_value 和 min_value 都提供了。用途 StepValueValidator 如果 step_size 是提供的。允许使用前导空格和尾随空格，就像在Python的 float() 功能。
错误消息键： required ， invalid ， max_value ， min_value ， step_size 。

接受三个可选参数：

max_value¶

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

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

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

`ImageField`¶

class ImageField(**kwargs)[源代码]¶

默认小部件： ClearableFileInput
空值： None
规范化为： UploadedFile 将文件内容和文件名包装为单个对象的对象。
验证文件数据是否已绑定到表单。还使用 FileExtensionValidator 验证枕头是否支持文件扩展名。
错误消息键： required ， invalid ， missing ， empty ， invalid_image

使用一个 ImageField 要求 Pillow 安装时支持您使用的图像格式。如果你遇到 corrupt image 上传图片时出错，通常意味着枕头不理解其格式。要修复此问题，请安装相应的库并重新安装枕头。

当你使用 ImageField 在表格上，您还必须记住 bind the file data to the form .

在清理和验证该字段后， UploadedFile 对象将有一个附加的 image 包含枕头的属性 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 如果枕头可以确定图像的内容类型，将更新图像的内容类型，否则将设置为 None .

`IntegerField`¶

class IntegerField(**kwargs)[源代码]¶

默认小部件： NumberInput 什么时候？ Field.localize 是 False ，否则 TextInput .
空值： None
规范化为：python整数。
验证给定值是否为整数。用途 MaxValueValidator 和 MinValueValidator 如果 max_value 和 min_value 都提供了。用途 StepValueValidator 如果 step_size 是提供的。允许使用前导空格和尾随空格，就像在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)[源代码]¶

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

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

采用两个可选参数：

encoder¶

A json.JSONEncoder 子类来序列化标准JSON序列化程序不支持的数据类型（例如。 datetime.datetime 或 UUID ). 例如，可以使用 DjangoJSONEncoder 班级。

默认为 json.JSONEncoder .

decoder¶

A json.JSONDecoder 子类来反序列化输入。反序列化可能需要考虑这样一个事实：您不能确定输入类型。例如，您有可能返回 datetime 这实际上是一个字符串，恰好是为 datetime S

这个 decoder 可用于验证输入。如果 json.JSONDecodeError 在反序列化期间引发，一个 ValidationError 将被提升。

默认为 json.JSONDecoder .

备注

如果你使用 ModelForm , the encoder 和 decoder 从 JSONField 将被使用。

用户友好窗体

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

`MultipleChoiceField`¶

class MultipleChoiceField(**kwargs)[源代码]¶

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

这个 invalid_choice 错误消息可能包含 %(value)s ，将替换为所选选项。

需要一个额外的参数， choices 至于 ChoiceField .

`NullBooleanField`¶

class NullBooleanField(**kwargs)[源代码]¶

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

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

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 . 如果启用，则在regex验证之前应用剥离。

`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 参数，则默认输入格式取自活动区域设置格式 TIME_INPUT_FORMATS 密钥，或从 TIME_INPUT_FORMATS 如果本地化被禁用。另请参阅 format localization 。

`TypedChoiceField`¶

class TypedChoiceField(**kwargs)[源代码]¶

就像一个 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)[源代码]¶

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

默认小部件： SelectMultiple
空值：你所给予的一切 empty_value
规范化为：由 coerce 参数。
验证给定值是否存在于选项列表中并且可以强制。
错误消息键： required ， invalid_choice

这个 invalid_choice 错误消息可能包含 %(value)s ，将替换为所选选项。

需要两个额外的参数， coerce 和 empty_value 至于 TypedChoiceField .

`URLField`¶

class URLField(**kwargs)[源代码]¶

默认小部件： 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" 。

自 5.0 版本弃用: 的缺省值 assume_scheme 将从 "http" 至 "https" 在Django 6.0中。集 FORMS_URLFIELD_ASSUME_HTTPS 将设置过渡到 True 选择使用 "https" 在Django 5.x发布周期中。

`UUIDField`¶

class UUIDField(**kwargs)[源代码]¶

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

此字段将接受作为 hex 论据 UUID 建造师。

稍微复杂的内置 `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 ，在这种情况下a required 如果没有为任何字段提供值，将引发验证错误。

当设置为 False , the Field.required 属性可以设置为 False 对于单个字段，使其成为可选的。如果没有为所需字段提供值，则 incomplete 将引发验证错误。

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

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 当声明表单字段，然后填充 queryset 在表格中 __init__() 方法：

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 属性，该属性指定在生成选项时用于迭代queryset的类。看到了吗迭代关系选择有关详细信息。

`ModelChoiceField`¶

class ModelChoiceField(**kwargs)[源代码]¶

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

这个 invalid_choice 错误消息可能包含 %(value)s ，将替换为所选选项。

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

需要单个参数：

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

ModelChoiceField 还接受几个可选参数：

empty_label¶

默认情况下 <select> 使用的小部件 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)

请注意，不会创建空选项(无论 empty_label )如果 ModelChoiceField 是必需的，并且具有默认的初始值，或者 widget 设置为 RadioSelect 以及 blank 论据是 False 。

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)[源代码]¶

默认小部件： SelectMultiple
Empty value: An empty QuerySet (self.queryset.none())
标准化为：a 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 以自定义生成的2元组选择。

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)¶

分配给的默认类 iterator 属性 ModelChoiceField 和 ModelMultipleChoiceField . 从查询集中产生2元组选择的iterable。

需要单个参数：

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

ModelChoiceIterator 有以下方法：

__iter__()¶: 在 (value, label) 使用的格式 ChoiceField.choices . 第一个 value 元素是 ModelChoiceIteratorValue 实例。

`ModelChoiceIteratorValue`¶

class ModelChoiceIteratorValue(value, instance)¶

需要两个参数：

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

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

ModelChoiceIteratorValue 有以下方法：

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

创建自定义字段¶

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

您还可以通过重写自定义如何访问字段 get_bound_field() .

« previous | up | next »

Django 5.1.dev 文档

表单字段¶

核心字段参数¶

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¶

创建自定义字段¶

Last update:

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