表单域 — Django 文档
表单字段
- class Field(**kwargs)
创建 Form
类时,最重要的部分是定义表单的字段。 每个字段都有自定义的验证逻辑,以及一些其他的钩子。
- Field.clean(value)
尽管使用 Field
类的主要方式是在 Form
类中,但您也可以实例化它们并直接使用它们以更好地了解它们的工作方式。 每个 Field
实例都有一个 clean()
方法,该方法接受一个参数并引发 django.forms.ValidationError
异常或返回干净值:
>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
'foo@example.com'
>>> f.clean('invalid email address')
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']
核心字段参数
每个 Field
类构造函数至少接受这些参数。 一些 Field
类采用额外的、特定于字段的参数,但以下内容应 始终 被接受:
required
- Field.required
默认情况下,每个 Field
类都假定该值是必需的,因此如果您传递一个空值 – None
或空字符串 (""
) – 那么 [ X156X] 将引发 ValidationError
异常:
>>> from django import forms
>>> f = forms.CharField()
>>> f.clean('foo')
'foo'
>>> f.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(' ')
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
要指定字段 不需要 ,请将 required=False
传递给 Field
构造函数:
>>> f = forms.CharField(required=False)
>>> f.clean('foo')
'foo'
>>> f.clean('')
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
如果 Field
具有 required=False
并且您传递 clean()
一个空值,那么 clean()
将返回一个 标准化 空值而不是提高ValidationError
。 对于 CharField
,这将是一个空字符串。 对于其他 Field
类,它可能是 None
。 (这因领域而异。)
必填表单字段的小部件具有 required
HTML 属性。 将 Form.use_required_attribute 属性设置为 False
以禁用它。 required
属性不包含在表单集的表单中,因为在添加和删除表单集时浏览器验证可能不正确。
label
- Field.label
label
参数允许您为此字段指定“人性化”标签。 当 Field
显示在 Form
中时使用。
如上面“将表单输出为 HTML”所述,Field
的默认标签是通过将所有下划线转换为空格并将第一个字母大写从字段名称生成的。 如果默认行为没有产生足够的标签,请指定 label
。
这是一个完整的示例 Form
,它为其两个字段实现了 label
。 我们指定了 auto_id=False
来简化输出:
>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(label='Your name')
... url = forms.URLField(label='Your website', required=False)
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>
label_suffix
- Field.label_suffix
label_suffix
参数允许您在每个字段的基础上覆盖表单的 label_suffix:
>>> class ContactForm(forms.Form):
... age = forms.IntegerField()
... nationality = forms.CharField()
... captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')
>>> f = ContactForm(label_suffix='?')
>>> print(f.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required></p>
initial
- Field.initial
initial
参数允许您指定在未绑定的 Form
中渲染此 Field
时要使用的初始值。
要指定动态初始数据,请参阅 Form.initial 参数。
用例是当您想要显示一个“空”表单时,其中的字段被初始化为特定值。 例如:
>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>
您可能会想,为什么不在显示表单时将初始值的字典作为数据传递? 好吧,如果您这样做,您将触发验证,并且 HTML 输出将包含任何验证错误:
>>> class CommentForm(forms.Form):
... name = forms.CharField()
... url = forms.URLField()
... comment = forms.CharField()
>>> default_data = {'name': 'Your name', 'url': 'http://'}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>
这就是为什么 initial
值仅对未绑定表单显示的原因。 对于绑定表单,HTML 输出将使用绑定数据。
另请注意,如果未给出特定字段的值,则 initial
值是 而非 用作验证中的“后备”数据。 initial
值是 only 用于初始表格显示:
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='Your name')
... url = forms.URLField(initial='http://')
... comment = forms.CharField()
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}
除了常量,您还可以传递任何可调用对象:
>>> import datetime
>>> class DateForm(forms.Form):
... day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>
只有在显示未绑定的表单时,而不是在定义表单时,才会对可调用对象表单执行。
help_text
- Field.help_text
help_text
参数允许您为此 Field
指定描述性文本。 如果您提供 help_text
,当 Field
通过其中一种便利的 Form
方法(例如 as_ul()
)。
与模型字段的 help_text 一样,该值在自动生成的表单中不是 HTML 转义的。
这是一个完整的示例 Form
,它为其两个字段实现了 help_text
。 我们指定了 auto_id=False
来简化输出:
>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
... subject = forms.CharField(max_length=100, help_text='100 characters max.')
... message = forms.CharField()
... sender = forms.EmailField(help_text='A valid email address, please.')
... cc_myself = forms.BooleanField(required=False)
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>
error_messages
- Field.error_messages
error_messages
参数允许您覆盖该字段将引发的默认消息。 传入一个字典,其键与要覆盖的错误消息匹配。 例如,这是默认的错误消息:
>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
这是一条自定义错误消息:
>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
...
ValidationError: ['Please enter your name']
在下面的 内置字段类 部分中,每个 Field
定义了它使用的错误消息键。
disabled
- Field.disabled
disabled
布尔参数设置为 True
时,会禁用使用 disabled
HTML 属性的表单字段,以便用户无法对其进行编辑。 即使用户篡改了提交给服务器的字段值,它也会被忽略,取而代之的是表单初始数据中的值。
检查字段数据是否有变化
has_changed()
- Field.has_changed()
has_changed()
方法用于确定字段值是否从初始值发生变化。 返回 True
或 False
。
有关更多信息,请参阅 Form.has_changed() 文档。
内置 Field 类
自然地,forms
库带有一组代表常见验证需求的 Field
类。 本节记录每个内置字段。
对于每个字段,如果您未指定 widget
,我们将描述使用的默认小部件。 我们还指定了当您提供空值时返回的值(请参阅上面有关 required
的部分以了解其含义)。
BooleanField
- class BooleanField(**kwargs)
默认小部件:CheckboxInput
空值:
False
标准化为:Python
True
或False
值。验证值是否为
True
(例如 复选框被选中)如果字段有required=True
。错误信息键:
required
笔记
由于所有
Field
子类默认都有required=True
,所以这里的验证条件很重要。 如果您想在表单中包含一个布尔值,它可以是True
或False
(例如 一个勾选或未勾选的复选框),创建BooleanField
时一定要记得传入required=False
。
CharField
- class CharField(**kwargs)
默认小部件:TextInput
空值:无论你给出的是 empty_value。
规范化为:一个字符串。
如果提供了
max_length
和min_length
,则使用 MaxLengthValidator 和 MinLengthValidator。 否则,所有输入都有效。错误信息键:
required
、max_length
、min_length
需要四个可选参数进行验证:
- max_length
- min_length
如果提供了这些参数,这些参数确保字符串的长度最多或至少是给定的长度。
- strip
如果
True
(默认),该值将被去除前导和尾随空格。
- empty_value
用于表示“空”的值。 默认为空字符串。
ChoiceField
- class ChoiceField(**kwargs)
默认小部件:选择
空值:
(空字符串)
规范化为:一个字符串。
验证给定值是否存在于选择列表中。
错误信息键:
required
、invalid_choice
invalid_choice
错误消息可能包含%(value)s
,它将被替换为选定的选项。需要一个额外的参数:
- choices
用作此字段选择的 2 元组的 iterable,或返回此类可迭代对象的可调用对象。 此参数接受与模型字段的
choices
参数相同的格式。 有关更多详细信息,请参阅有关选择 的 模型字段参考文档。 如果参数是可调用的,则每次初始化字段的表单时都会对其进行评估。 默认为空列表。
TypedChoiceField
- class TypedChoiceField(**kwargs)
就像 ChoiceField,除了 TypedChoiceField 需要两个额外的参数,coerce 和 empty_value。
默认小部件:选择
空值:无论你给出的是 empty_value。
规范化为: coerce 参数提供的类型的值。
验证给定的值是否存在于选择列表中,并且可以被强制执行。
错误信息键:
required
、invalid_choice
需要额外的参数:
- coerce
一个接受一个参数并返回一个强制值的函数。 示例包括内置
int
、float
、bool
和其他类型。 默认为身份函数。 请注意,强制发生在输入验证之后,因此可以强制转换为choices
中不存在的值。
- empty_value
用于表示“空”的值。 默认为空字符串;
None
是这里的另一个常见选择。 请注意,此值不会被coerce
参数中给出的函数强制转换,因此请相应地选择它。
DateField
- class DateField(**kwargs)
默认小部件:DateInput
空值:
None
标准化为:一个 Python
datetime.date
对象。验证给定的值是
datetime.date
、datetime.datetime
或以特定日期格式格式化的字符串。错误信息键:
required
、invalid
需要一个可选的参数:
- input_formats
用于尝试将字符串转换为有效
datetime.date
对象的格式列表。
如果未提供
input_formats
参数,则默认输入格式为:['%Y-%m-%d', # '2006-10-25' '%m/%d/%Y', # '10/25/2006' '%m/%d/%y'] # '10/25/06'
此外,如果您指定 :设置:`USE_L10N=假 ` 在您的设置中,以下内容也将包含在默认输入格式中:
['%b %d %Y', # 'Oct 25 2006' '%b %d, %Y', # 'Oct 25, 2006' '%d %b %Y', # '25 Oct 2006' '%d %b, %Y', # '25 Oct, 2006' '%B %d %Y', # 'October 25 2006' '%B %d, %Y', # 'October 25, 2006' '%d %B %Y', # '25 October 2006' '%d %B, %Y'] # '25 October, 2006'
另见 格式本地化 。
DateTimeField
- class DateTimeField(**kwargs)
默认小部件:DateTimeInput
空值:
None
标准化为:一个 Python
datetime.datetime
对象。验证给定的值是
datetime.datetime
、datetime.date
或以特定日期时间格式格式化的字符串。错误信息键:
required
、invalid
需要一个可选的参数:
- input_formats
用于尝试将字符串转换为有效
datetime.datetime
对象的格式列表。
如果未提供
input_formats
参数,则默认输入格式为:['%Y-%m-%d %H:%M:%S', # '2006-10-25 14:30:59' '%Y-%m-%d %H:%M', # '2006-10-25 14:30' '%Y-%m-%d', # '2006-10-25' '%m/%d/%Y %H:%M:%S', # '10/25/2006 14:30:59' '%m/%d/%Y %H:%M', # '10/25/2006 14:30' '%m/%d/%Y', # '10/25/2006' '%m/%d/%y %H:%M:%S', # '10/25/06 14:30:59' '%m/%d/%y %H:%M', # '10/25/06 14:30' '%m/%d/%y'] # '10/25/06'
另见 格式本地化 。
DecimalField
- class DecimalField(**kwargs)
默认小部件:NumberInput 当 Field.localize 为
False
时,否则为 TextInput。空值:
None
标准化为:Python
decimal
。验证给定的值是小数。 如果提供了
max_value
和min_value
,则使用 MaxValueValidator 和 MinValueValidator。 忽略前导和尾随空格。错误信息键:
required
、invalid
、max_value
、min_value
、max_digits
、max_decimal_places
、[ X90X]
max_value
和min_value
错误消息可能包含%(limit_value)s
,它们将被适当的限制替换。 类似地,max_digits
、max_decimal_places
和max_whole_digits
错误消息可能包含%(max)s
。需要四个可选的参数:
- max_value
- min_value
这些控制字段中允许的值范围,应以
decimal.Decimal
值的形式给出。
- max_digits
值中允许的最大数字(小数点前的数字加上小数点后的数字,去掉前导零)。
- decimal_places
允许的最大小数位数。
DurationField
- class DurationField(**kwargs)
默认小部件:TextInput
空值:
None
标准化为:Python
timedelta
。验证给定的值是一个可以转换为
timedelta
的字符串。 该值必须介于datetime.timedelta.min
和datetime.timedelta.max
之间。错误信息键:
required
、invalid
、overflow
。
接受 parse_duration() 理解的任何格式。
EmailField
- class EmailField(**kwargs)
默认小部件:EmailInput
空值:
(空字符串)
规范化为:一个字符串。
使用 EmailValidator 来验证给定值是否为有效的电子邮件地址,并使用适度复杂的正则表达式。
错误信息键:
required
、invalid
有两个可选的验证参数,
max_length
和min_length
。 如果提供了这些参数,这些参数确保字符串的长度最多或至少是给定的长度。
FileField
- class FileField(**kwargs)
默认小部件:ClearableFileInput
空值:
None
规范化为:一个
UploadedFile
对象,它将文件内容和文件名包装到一个对象中。可以验证非空文件数据已经绑定到表单中。
错误信息键:
required
、invalid
、missing
、empty
、max_length
有两个可选的验证参数,
max_length
和allow_empty_file
。 如果提供,这些确保文件名最多为给定的长度,即使文件内容为空,验证也会成功。要了解有关
UploadedFile
对象的更多信息,请参阅 文件上传文档 。在表单中使用
FileField
时,还必须记得将文件数据绑定到表单。max_length
错误是指文件名的长度。 在该键的错误消息中,%(max)d
将替换为最大文件名长度,而%(length)d
将替换为当前文件名长度。
FilePathField
- class FilePathField(**kwargs)
默认小部件:选择
空值:
(空字符串)
规范化为:一个字符串。
验证选择是否存在于选择列表中。
错误信息键:
required
、invalid_choice
该字段允许从某个目录中的文件中进行选择。 它需要五个额外的参数; 仅需要
path
:- path
要列出其内容的目录的绝对路径。 该目录必须存在。
- recursive
如果
False
(默认)只有path
的直接内容将被提供作为选择。 如果是True
,目录将被递归下降,所有后代将作为选择列出。
- match
正则表达式模式;只允许将名称与此表达式相匹配的文件作为选择。
- allow_files
可选的。
True
或False
。 默认值为True
。 指定是否应包含指定位置的文件。 此或 allow_folders 必须为True
。
- allow_folders
可选的。
True
或False
。 默认值为False
。 指定是否应包括指定位置的文件夹。 此或 allow_files 必须为True
。
FloatField
- class FloatField(**kwargs)
默认小部件:NumberInput 当 Field.localize 为
False
时,否则为 TextInput。空值:
None
规范化为:Python 的浮点数。
验证给定的值是一个浮点数。 如果提供了
max_value
和min_value
,则使用 MaxValueValidator 和 MinValueValidator。 允许前导和尾随空格,如 Python 的float()
函数。错误信息键:
required
、invalid
、max_value
、min_value
采用两个可选参数进行验证,
max_value
和min_value
。 这些控制了该字段允许的数值范围。
ImageField
- class ImageField(**kwargs)
默认小部件:ClearableFileInput
空值:
None
规范化为:一个
UploadedFile
对象,它将文件内容和文件名包装到一个对象中。验证文件数据已绑定到表单。 还使用 FileExtensionValidator 来验证 Pillow 是否支持文件扩展名。
错误信息键:
required
、invalid
、missing
、empty
、invalid_image
使用
ImageField
需要安装 Pillow 并支持您使用的图像格式。 如果您在上传图片时遇到corrupt image
错误,通常表示 Pillow 不了解其格式。 要解决此问题,请安装相应的库并重新安装 Pillow。在表单上使用
ImageField
时,还必须记住将文件数据 绑定到表单 。清理并验证字段后,
UploadedFile
对象将有一个额外的image
属性,其中包含用于检查文件是否为有效图像的 Pillow Image 实例。 Pillow 在验证图像后关闭底层文件描述符,因此虽然非图像数据属性,如format
、height
和width
可用,访问如果不重新打开文件,则无法使用底层图像数据,例如getdata()
或getpixel()
。 例如:>>> from PIL import Image >>> from django import forms >>> from django.core.files.uploadedfile import SimpleUploadedFile >>> class ImageForm(forms.Form): ... img = forms.ImageField() >>> file_data = {'img': SimpleUploadedFile('test.png', <file data>)} >>> form = ImageForm({}, file_data) # Pillow closes the underlying file descriptor. >>> form.is_valid() True >>> image_field = form.cleaned_data['img'] >>> image_field.image <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18> >>> image_field.image.width 191 >>> image_field.image.height 287 >>> image_field.image.format 'PNG' >>> image_field.image.getdata() # Raises AttributeError: 'NoneType' object has no attribute 'seek'. >>> image = Image.open(image_field) >>> image.getdata() <ImagingCore object at 0x7f5984f874b0>
此外,如果 Pillow 可以确定
UploadedFile.content_type
将使用图像的内容类型更新,否则将设置为None
。
IntegerField
- class IntegerField(**kwargs)
默认小部件:NumberInput 当 Field.localize 为
False
时,否则为 TextInput。空值:
None
规范化为:Python 的整数。
验证给定的值是一个整数。 如果提供了
max_value
和min_value
,则使用 MaxValueValidator 和 MinValueValidator。 允许前导和尾随空格,如 Python 的int()
函数。错误信息键:
required
、invalid
、max_value
、min_value
max_value
和min_value
错误消息可能包含%(limit_value)s
,它们将被适当的限制替换。需要两个可选参数进行验证:
- max_value
- min_value
这些控制了该字段允许的数值范围。
GenericIPAddressField
- class GenericIPAddressField(**kwargs)
一个包含 IPv4 或 IPv6地址 的字段。
默认小部件:TextInput
空值:
(空字符串)
规范化为:一个字符串。 IPv6 地址按如下所述进行规范化。
验证给定的值是一个有效的 IP 地址。
错误信息键:
required
、invalid
IPv6 地址规范化遵循 RFC 4291#section-2.2 第 2.2 节,包括使用该节第 3 段中建议的 IPv4 格式,如
::ffff:192.0.2.0
。 例如,2001:0::0:01
将归一化为2001::1
,而::ffff:0a0a:0a0a
将归一化为::ffff:10.10.10.10
。 所有字符都转换为小写。需要两个可选的参数:
- protocol
将有效输入限制为指定协议。 可接受的值为
both
(默认)、IPv4
或IPv6
。 匹配不区分大小写。
- unpack_ipv4
解压缩 IPv4 映射地址,如
::ffff:192.0.2.1
。 如果启用此选项,该地址将被解压缩到192.0.2.1
。 默认为禁用。 仅当protocol
设置为'both'
时才能使用。
MultipleChoiceField
- class MultipleChoiceField(**kwargs)
默认小部件:SelectMultiple
空值:
[]
(空列表)规范化为:一个字符串列表。
验证给定值列表中的每个值是否存在于选择列表中。
错误信息键:
required
、invalid_choice
、invalid_list
invalid_choice
错误消息可能包含%(value)s
,它将被替换为选定的选项。需要一个额外的必需参数,
choices
,就像 ChoiceField。
TypedMultipleChoiceField
- class TypedMultipleChoiceField(**kwargs)
就像 MultipleChoiceField,除了 TypedMultipleChoiceField 需要两个额外的参数,
coerce
和empty_value
。默认小部件:SelectMultiple
空值:无论你给出的是
empty_value
规范化为:
coerce
参数提供的类型的值列表。验证给定的值是否存在于选择列表中,并且可以被强制执行。
错误信息键:
required
、invalid_choice
invalid_choice
错误消息可能包含%(value)s
,它将被替换为选定的选项。需要两个额外的参数,
coerce
和empty_value
,对于 TypedChoiceField。
NullBooleanField
- class NullBooleanField(**kwargs)
- ;* 默认小部件:NullBooleanSelect
- 空值:
None
- 标准化为:Python
True
、False
或None
值。 - 不验证任何内容(即,它从不引发
ValidationError
)。
- 空值:
RegexField
- class RegexField(**kwargs)
默认小部件:TextInput
空值:
(空字符串)
规范化为:一个字符串。
使用 RegexValidator 来验证给定值是否与某个正则表达式匹配。
错误信息键:
required
、invalid
需要一个额外的参数:
- regex
一个正则表达式,可以是字符串,也可以是编译后的正则表达式对象。
还采用
max_length
、min_length
和strip
,它们的工作方式与 CharField 一样。- strip
默认为
False
。 如果启用,将在正则表达式验证之前应用剥离。
SlugField
- class SlugField(**kwargs)
默认小部件:TextInput
空值:
(空字符串)
规范化为:一个字符串。
使用 validate_slug 或 validate_unicode_slug 来验证给定的值是否仅包含字母、数字、下划线和连字符。
错误信息:
required
、invalid
此字段旨在用于在表单中表示模型 SlugField。
需要两个可选的参数:
- allow_unicode
指示字段除 ASCII 字母外还接受 Unicode 字母的布尔值。 默认为
False
。
TimeField
- class TimeField(**kwargs)
默认小部件:TimeInput
空值:
None
标准化为:一个 Python
datetime.time
对象。验证给定值是
datetime.time
或以特定时间格式格式化的字符串。错误信息键:
required
、invalid
需要一个可选的参数:
- input_formats
用于尝试将字符串转换为有效
datetime.time
对象的格式列表。
如果未提供
input_formats
参数,则默认输入格式为:'%H:%M:%S', # '14:30:59' '%H:%M', # '14:30'
URLField
- class URLField(**kwargs)
默认小部件:URLInput
空值:
(空字符串)
规范化为:一个字符串。
使用 URLValidator 来验证给定的值是一个有效的 URL。
错误信息键:
required
、invalid
采用以下可选参数:
- max_length
- min_length
它们与
CharField.max_length
和CharField.min_length
相同。
UUIDField
- class UUIDField(**kwargs)
默认小部件:TextInput
空值:
(空字符串)
标准化为:
UUID
对象。错误信息键:
required
、invalid
该字段将接受作为
UUID
构造函数的hex
参数接受的任何字符串格式。
稍微复杂的内置 Field 类
ComboField
- class ComboField(**kwargs)
默认小部件:TextInput
空值:
(空字符串)
规范化为:一个字符串。
针对指定为
ComboField
的参数的每个字段验证给定值。错误信息键:
required
、invalid
需要一个额外的必要参数。
- fields
用于验证字段值的字段列表(按提供顺序)。
>>> from django.forms import ComboField >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) >>> f.clean('test@example.com') 'test@example.com' >>> f.clean('longemailaddress@example.com') Traceback (most recent call last): ... ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
MultiValueField
- class MultiValueField(fields=(), **kwargs)
默认小部件:TextInput
空值:
(空字符串)
规范化为:子类的
compress
方法返回的类型。针对指定为
MultiValueField
的参数的每个字段验证给定值。错误信息键:
required
、invalid
、incomplete
将多个字段的逻辑聚合在一起产生一个值。
该字段是抽象的,必须是子类。 与单值字段相比,MultiValueField 的子类不能实现 clean(),而是 - 实现 compress()。
需要一个额外的必要参数。
- fields
字段的元组,其值被清理并随后组合成单个值。 该字段的每个值都由
fields
中的相应字段清理 - 第一个值由第一个字段清理,第二个值由第二个字段清理,依此类推。 清理完所有字段后,清理值列表将通过 compress() 合并为一个值。
还需要一些可选的参数:
- require_all_fields
默认为
True
,在这种情况下,如果没有为任何字段提供值,则会引发required
验证错误。当设置为
False
时,可以将 Field.required 属性设置为False
以针对单个字段使它们成为可选。 如果没有为必填字段提供值,则会引发incomplete
验证错误。可以在 MultiValueField 子类上定义默认的
incomplete
错误消息,或者可以在每个单独的字段上定义不同的消息。 例如:from django.core.validators import RegexValidator class PhoneField(MultiValueField): def __init__(self, **kwargs): # Define one message for all fields. error_messages = { 'incomplete': 'Enter a country calling code and a phone number.', } # Or define a different message for each field. fields = ( CharField( error_messages={'incomplete': 'Enter a country calling code.'}, validators=[ RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'), ], ), CharField( error_messages={'incomplete': 'Enter a phone number.'}, validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')], ), CharField( validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')], required=False, ), ) super().__init__( error_messages=error_messages, fields=fields, require_all_fields=False, **kwargs )
- widget
必须是 django.forms.MultiWidget 的子类。 默认值为 TextInput,在这种情况下可能不是很有用。
- compress(data_list)
获取有效值列表并返回这些值的“压缩”版本——在单个值中。 例如,SplitDateTimeField 是一个子类,它将时间字段和日期字段组合成一个
datetime
对象。这个方法必须在子类中实现。
SplitDateTimeField
- class SplitDateTimeField(**kwargs)
默认小部件:SplitDateTimeWidget
空值:
None
标准化为:一个 Python
datetime.datetime
对象。验证给定值是
datetime.datetime
或以特定日期时间格式格式化的字符串。错误信息键:
required
、invalid
、invalid_date
、invalid_time
需要两个可选的参数:
- input_date_formats
用于尝试将字符串转换为有效
datetime.date
对象的格式列表。
如果未提供
input_date_formats
参数,则使用 DateField 的默认输入格式。- input_time_formats
用于尝试将字符串转换为有效
datetime.time
对象的格式列表。
如果未提供
input_time_formats
参数,则使用 TimeField 的默认输入格式。
处理关系的字段
有两个字段可用于表示模型之间的关系:ModelChoiceField 和 ModelMultipleChoiceField。 这两个字段都需要一个 queryset
参数,用于为字段创建选项。 在表单验证时,这些字段会将一个模型对象(在 ModelChoiceField
的情况下)或多个模型对象(在 ModelMultipleChoiceField
的情况下)放入 cleaned_data
字典表格。
对于更复杂的用途,您可以在声明表单字段时指定 queryset=None
,然后在表单的 __init__()
方法中填充 queryset
:
class FooMultipleChoiceForm(forms.Form):
foo_select = forms.ModelMultipleChoiceField(queryset=None)
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.fields['foo_select'].queryset = ...
ModelChoiceField
- class ModelChoiceField(**kwargs)
默认小部件:选择
空值:
None
规范化为:一个模型实例。
验证给定的 id 是否存在于查询集中。
错误信息键:
required
、invalid_choice
允许选择单个模型对象,适用于表示外键。 请注意,当条目数量增加时,
ModelChoiceField
的默认小部件变得不切实际。 您应该避免将它用于 100 多个项目。需要一个参数:
- queryset
模型对象的
QuerySet
,从中派生字段选择并用于验证用户的选择。 在呈现表单时对其进行评估。
ModelChoiceField
也有两个可选参数:- empty_label
默认情况下,
ModelChoiceField
使用的<select>
小部件将在列表顶部有一个空选项。 您可以使用empty_label
属性更改此标签的文本(默认为"---------"
),也可以通过将empty_label
设置为None
:# A custom empty label field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") # No empty label field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
请注意,如果需要
ModelChoiceField
且具有默认初始值,则不会创建空选项(无论empty_label
的值如何)。
- to_field_name
此可选参数用于指定要用作字段小部件中选项值的字段。 确保它是模型的唯一字段,否则所选值可能匹配多个对象。 默认情况下,它设置为
None
,在这种情况下,将使用每个对象的主键。 例如:# No custom to_field_name field1 = forms.ModelChoiceField(queryset=...)
会产生:
<select id="id_field1" name="field1"> <option value="obj1.pk">Object1</option> <option value="obj2.pk">Object2</option> ... </select>
和:
# to_field_name provided field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
会产生:
<select id="id_field2" name="field2"> <option value="obj1.name">Object1</option> <option value="obj2.name">Object2</option> ... </select>
模型的
__str__()
方法将被调用以生成用于字段选择的对象的字符串表示。 要提供自定义表示,子类ModelChoiceField
并覆盖label_from_instance
。 此方法将接收一个模型对象,并应返回一个适合表示它的字符串。 例如:from django.forms import ModelChoiceField class MyModelChoiceField(ModelChoiceField): def label_from_instance(self, obj): return "My Object #%i" % obj.id
ModelMultipleChoiceField
- class ModelMultipleChoiceField(**kwargs)
默认小部件:SelectMultiple
空值:空
QuerySet
(self.queryset.none())归一化为:模型实例的
QuerySet
。验证给定值列表中的每个 id 是否存在于查询集中。
错误信息键:
required
、list
、invalid_choice
、invalid_pk_value
invalid_choice
消息可能包含%(value)s
,而invalid_pk_value
消息可能包含%(pk)s
,它们将被适当的值替换。允许选择一个或多个模型对象,适用于表示多对多关系。 与 ModelChoiceField 一样,您可以使用
label_from_instance
自定义对象表示。需要一个参数:
- queryset
需要一个可选的参数:
- to_field_name
创建自定义字段
如果内置的 Field
类不能满足您的需求,您可以轻松创建自定义 Field
类。 为此,只需创建 django.forms.Field
的子类。 它唯一的要求是它实现了一个 clean()
方法并且它的 __init__()
方法接受上面提到的核心参数(required
、label
、[ X162X]、widget
、help_text
)。
您还可以通过覆盖 get_bound_field() 来自定义如何访问字段。