表单字段

Field(**kwargs)[source]

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

领域。clean(value)[source]

虽然您将使用Field类的主要方法是在Form类中,但您也可以实例化它们并直接使用它们以更好地了解它们的工作方式。 每个Field实例都有一个clean()方法,它只接受一个参数,并引发一个django.forms.ValidationError异常或返回clean值:

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

领域。需要 T0> ¶ T1>

By default, each Field class assumes the value is required, so if you pass an empty value – either None or the empty string ("") – then clean() will raise a ValidationError exception:

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

If a Field has required=False and you pass clean() an empty value, then clean() will return a normalized empty value rather than raising ValidationError. 对于CharField,这将是一个空字符串。 对于其他Field类,它可能是None (这因场而异)

所需表单域的小部件具有required HTML属性。 Form.use_required_attribute属性设置为False以禁用它。 required属性不包含在表单集的表单中,因为在添加和删除表单集时浏览器验证可能不正确。

label

领域。标签 T0> ¶ T1>

使用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

领域。 label_suffix T0> ¶ T1>

使用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

领域。初始 T0> ¶ T1>

使用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值仅用于用于初始格式显示:

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

只有在显示未绑定表单时才会对可调用对象进行评估,而不是对其进行定义。

widget

领域。插件 T0> ¶ T1>

widget参数允许您在呈现Field时指定Widget类。 有关更多信息,请参阅Widgets

help_text

领域。 help_text T0> ¶ T1>

help_text参数允许您为Field指定描述性文本。 If you provide help_text, it will be displayed next to the Field when the Field is rendered by one of the convenience Form methods (e.g., 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

领域。 error_messages T0> ¶ T1>

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

领域。验证 T0> ¶ T1>

您可以使用validators参数提供该字段的验证功能列表。

有关更多信息,请参阅validators documentation

localize

领域。局部化 T0> ¶ T1>

localize参数可以实现表单数据输入的本地化,以及呈现的输出。

有关更多信息,请参阅format localization文档。

disabled

领域。停用 T0> ¶ T1>

当设置为True时,disabled布尔参数将使用disabled HTML属性禁用表单域,以便用户不可编辑。 即使用户篡改提交给服务器的字段值,也会忽略表单的初始数据中的值。

检查字段数据是否已经改变

has_changed()

领域。has_changed()[source]

has_changed()方法用于确定字段值是否已从初始值更改。 返回TrueFalse

有关更多信息,请参阅Form.has_changed()文档。

内置Field

当然,forms库附带了一组代表常见验证需求的Field类。 本节介绍每个内置字段。

对于每个字段,如果不指定widget,则描述所使用的默认窗口小部件。 我们还指定了在提供空值​​时返回的值(请参阅required上面的部分来理解这意味着什么)。

BooleanField

BooleanField(**kwargs)[source]
  • 默认控件:CheckboxInput
  • 空值:False
  • 规范化为:Python TrueFalse值。
  • 如果字段的required=True,则验证值是True(例如,选中复选框)。
  • 错误消息键:required

注意

由于默认情况下所有Field子类都具有required=True,所以此处的验证条件非常重要。 如果你想在你的表单中包含一个可以是TrueFalse的布尔值(例如,选中或取消选中的复选框),则必须记住要传递required=False创建BooleanField时。

CharField

CharField(**kwargs)[source]
  • 默认小部件:TextInput
  • Empty value: Whatever you’ve given as empty_value.
  • 规范化为:一个字符串。
  • 如果提供,则验证max_lengthmin_length 否则,所有的输入都是有效的。
  • 错误消息键:requiredmax_lengthmin_length

有三个可选的验证参数:

MAX_LENGTH T0> ¶ T1>
MIN_LENGTH T0> ¶ T1>

如果提供,这些参数确保字符串最多或至少是给定的长度。

条 T0> ¶ T1>

如果True(默认),则该值将被剥离前导和尾随空白。

empty_value T0> ¶ T1>
Django 1.11新增功能

用来表示“空”的值。 缺省为空字符串。

ChoiceField

ChoiceField(**kwargs)[source]
  • 默认小部件:Select
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 验证给定值存在于选项列表中。
  • 错误消息键:requiredinvalid_choice

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

多一个参数:

选择 T0> ¶ T1>

要么是一个可以迭代(例如,一个列表或元组)的元组作为这个字段的选择,要么是一个返回这样一个可迭代的可调用对象。 该参数接受与模型字段的choices参数相同的格式。 有关更多详细信息,请参阅model field reference documentation on choices 如果参数是可调用的,则每次字段的表单被初始化时都会对其进行评估。 默认为一个空的列表。

TypedChoiceField

TypedChoiceField(**kwargs)[source]

就像一个ChoiceField,除了TypedChoiceField需要两个额外的参数:coerceempty_value

  • 默认小部件:Select
  • Empty value: Whatever you’ve given as empty_value.
  • 标准化为:由coerce参数提供的类型的值。
  • 验证给定值存在于选择列表中,并且可以被强制。
  • 错误消息键:requiredinvalid_choice

需要额外的参数:

裹胁 T0> ¶ T1>

采用一个参数并返回强制值的函数。 例子包括内置的intfloatbool等类型。 默认为一个标识函数。 请注意,输入验证之后会发生强制,所以可以强制为choices中不存在的值。

empty_value T0> ¶ T1>

The value to use to represent “empty.” Defaults to the empty string; None is another common choice here. 请注意,这个值不会被coerce参数中给出的函数强制,因此请相应地选择它。

DateField

DateField(**kwargs)[source]
  • 默认控件:DateInput
  • 空值:None
  • 规范化为:Python datetime.date对象。
  • 验证给定值是以特定日期格式格式化的datetime.datedatetime.datetime还是字符串。
  • 错误消息键:requiredinvalid

采取一个可选参数:

input_formats T0> ¶ T1>

用于尝试将字符串转换为有效的datetime.date对象的格式列表。

如果没有提供input_formats参数,默认的输入格式是:

['%Y-%m-%d',      # '2006-10-25'
 '%m/%d/%Y',      # '10/25/2006'
 '%m/%d/%y']      # '10/25/06'

另外,如果您在设置中指定了USE_L10N=False,则以下内容也将包含在默认输入格式中:

['%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'

另见format localization

DateTimeField

DateTimeField(**kwargs)[source]
  • 默认控件:DateTimeInput
  • 空值:None
  • 规范化为:Python datetime.datetime对象。
  • 验证给定的值是以特定的日期时间格式格式化的datetime.datetimedatetime.date或字符串。
  • 错误消息键:requiredinvalid

采取一个可选参数:

input_formats T0> ¶ T1>

用于尝试将字符串转换为有效的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'

另见format localization

DecimalField

DecimalField(**kwargs)[source]
  • Field.localizeFalse时,默认widget:NumberInput,否则TextInput
  • 空值:None
  • 规范化为:Python decimal
  • 验证给定的值是一个小数。 前导和尾随的空白被忽略。
  • Error message keys: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits

max_valuemin_value错误消息可能包含%(limit_value)s,它将被适当的限制替代。 Similarly, the max_digits, max_decimal_places and max_whole_digits error messages may contain %(max)s.

采取四个可选参数:

MAX_VALUE T0> ¶ T1>
MIN_VALUE T0> ¶ T1>

这些控制字段中允许的值的范围,应该以decimal.Decimal值给出。

max_digits T0> ¶ T1>

数值中允许的最大位数(小数点前的数字加上小数点后的数字,前面的零除去)。

decimal_places T0> ¶ T1>

允许的最大小数位数。

DurationField

DurationField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:None
  • 规范化为:Python timedelta
  • 验证给定值是一个可以转换为timedelta的字符串。
  • 错误消息键:requiredinvalid

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

EmailField

EmailField(**kwargs)[source]
  • 默认widget:EmailInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 使用适度复杂的正则表达式验证给定的值是否是有效的电子邮件地址。
  • 错误消息键:requiredinvalid

有两个用于验证的可选参数:max_lengthmin_length 如果提供,这些参数确保字符串最多或至少是给定的长度。

FileField

FileField(**kwargs)[source]
  • 默认小部件:ClearableFileInput
  • 空值:None
  • 标准化为:将文件内容和文件名称封装到单个对象中的UploadedFile对象。
  • 可以验证非空文件数据已被绑定到表单。
  • 错误消息键:requiredinvalidmissingemptymax_length

有两个可选参数用于验证,max_lengthallow_empty_file 如果提供,这些确保文件名至多是给定的长度,即使文件内容为空,验证也会成功。

要详细了解UploadedFile对象,请参阅file uploads documentation

在表单中使用FileField时,还必须记住将bind the file data to the form

max_length错误指的是文件名的长度。 In the error message for that key, %(max)d will be replaced with the maximum filename length and %(length)d will be replaced with the current filename length.

FilePathField

FilePathField(**kwargs)[source]
  • 默认小部件:Select
  • 空值:None
  • 规范化为:一个字符串。
  • 验证所选选项是否存在于选择列表中。
  • 错误消息键:requiredinvalid_choice

该字段允许从某个目录内的文件中进行选择。 它需要五个额外的论据;只有path是必需的:

路径 T0> ¶ T1>

要列出其内容的目录的绝对路径。 该目录必须存在。

递归 T0> ¶ T1>

如果False(默认),则只有path的直接内容将作为选项提供。 如果True,目录将递归递减,所有后代将被列为选项。

匹配 T0> ¶ T1>

正则表达式模式;只有名称匹配此表达式的文件将被允许作为选择。

allow_files T0> ¶ T1>

可选的。 可以是TrueFalse 默认是True 指定是否应该包含指定位置的文件。 这个或者allow_folders必须是True

allow_folders T0> ¶ T1>

可选的。 可以是TrueFalse 默认是False 指定是否应该包含指定位置的文件夹。 这个或者allow_files必须是True

FloatField

FloatField(**kwargs)[source]
  • Field.localizeFalse时,默认widget:NumberInput,否则TextInput
  • 空值:None
  • 规范化为:Python浮点数。
  • 验证给定的值是一个浮点数。 在Python的float()函数中,允许前导空格和尾部空格。
  • 错误消息键:requiredinvalidmax_valuemin_value

采用两个可选参数进行验证,max_valuemin_value 这些控制着现场允许的数值范围。

ImageField

ImageField(**kwargs)[source]
  • 默认小部件:ClearableFileInput
  • 空值:None
  • 标准化为:将文件内容和文件名称封装到单个对象中的UploadedFile对象。
  • 验证文件数据是否已绑定到表单,并且该文件是Pillow可以理解的图像格式。
  • 错误消息键:requiredinvalidmissingemptyinvalid_image

使用ImageField需要安装Pillow,并支持您使用的图像格式。 如果您在上传图片时遇到损坏 图片错误,通常意味着枕头无法理解其格式。 要解决这个问题,安装适当的库并重新安装枕头。

当您在表单上使用ImageField时,还必须记住bind the file data to the form

After the field has been cleaned and validated, the UploadedFile object will have an additional image attribute containing the Pillow Image instance used to check if the file was a valid image. 另外,如果Pillow可以确定,那么UploadedFile.content_type将更新为图像的内容类型,否则将被设置为None

IntegerField

IntegerField(**kwargs)[source]
  • Field.localizeFalse时,默认widget:NumberInput,否则TextInput
  • 空值:None
  • 规范化为:一个Python整数。
  • 验证给定的值是一个整数。 在Python的int()函数中,允许前导和尾随空格。
  • 错误消息键:requiredinvalidmax_valuemin_value

max_valuemin_value错误消息可能包含%(limit_value)s,它将被适当的限制替代。

采用两个可选参数进行验证:

MAX_VALUE T0> ¶ T1>
MIN_VALUE T0> ¶ T1>

这些控制着现场允许的数值范围。

GenericIPAddressField

GenericIPAddressField(**kwargs)[source]

包含IPv4或IPv6地址的字段。

  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。 IPv6地址如下所述进行标准化。
  • 验证给定的值是一个有效的IP地址。
  • 错误消息键:requiredinvalid

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 所有的字符都被转换成小写字母。

采取两个可选参数:

协议 T0> ¶ T1>

限制有效的输入到指定的协议。 Accepted values are both (default), IPv4 or IPv6. 匹配不区分大小写。

unpack_ipv4 T0> ¶ T1>

解压IPv4映射地址,如::ffff:192.0.2.1 如果启用此选项,则该地址将被解压到192.0.2.1 默认是禁用的。 只能在protocol设置为'both'时使用。

MultipleChoiceField

MultipleChoiceField(**kwargs)[source]
  • 默认小部件:SelectMultiple
  • 空值:[](空列表)
  • 规范化为:字符串列表。
  • 验证给定值列表中的每个值都存在于选项列表中。
  • 错误消息键:requiredinvalid_choiceinvalid_list

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

ChoiceField所示,需要一个额外的必需参数choices

TypedMultipleChoiceField

TypedMultipleChoiceField(**kwargs)[source]

就像一个MultipleChoiceField,除了TypedMultipleChoiceField外,还有两个额外的参数:coerceempty_value

  • 默认小部件:SelectMultiple
  • Empty value: Whatever you’ve given as empty_value
  • 规范化为:由coerce参数提供的类型值列表。
  • 验证给定的值存在于选择列表中,并且可以被强制。
  • 错误消息键:requiredinvalid_choice

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

针对TypedChoiceField引入两个额外的参数,coerceempty_value

NullBooleanField

NullBooleanField(**kwargs)[source]
  • 默认控件:NullBooleanSelect
  • 空值:None
  • 规范化为:Python TrueFalseNone值。
  • 什么都不验证(即从不引发ValidationError)。

RegexField

RegexField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 验证给定值是否与某个正则表达式匹配。
  • 错误消息键:requiredinvalid

采取一个必要的论据:

正则表达式 T0> ¶ T1>

指定为字符串或编译的正则表达式对象的正则表达式。

同样需要max_lengthmin_lengthstrip,它们与CharField一样工作。

条 T0> ¶ T1>

默认为False 如果启用,将在正则表达式验证之前应用剥离。

SlugField

SlugField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 验证给定值仅包含字母,数字,下划线和连字符。
  • 错误消息:requiredinvalid

该字段旨在用于在表单中表示模型SlugField

采取可选参数:

allow_unicode T0> ¶ T1>

指示字段除了ASCII字母外还接受Unicode字母的布尔值。 默认为False

TimeField

TimeField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:None
  • 规范化为:Python datetime.time对象。
  • 验证给定值是以特定时间格式格式化的datetime.time或字符串。
  • 错误消息键:requiredinvalid

采取一个可选参数:

input_formats T0> ¶ T1>

用于尝试将字符串转换为有效的datetime.time对象的格式列表。

如果没有提供input_formats参数,默认的输入格式是:

'%H:%M:%S',     # '14:30:59'
'%H:%M',        # '14:30'

URLField

URLField(**kwargs)[source]
  • 默认小部件:URLInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 验证给定的值是一个有效的URL。
  • 错误消息键:requiredinvalid

采取以下可选参数:

MAX_LENGTH T0> ¶ T1>
MIN_LENGTH T0> ¶ T1>

这些与CharField.max_lengthCharField.min_length相同。

UUIDField

UUIDField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:UUID对象。
  • 错误消息键:requiredinvalid

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

稍微复杂的内置Field

ComboField

ComboField(**kwargs)[source]
  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:一个字符串。
  • 根据指定为ComboField的参数的每个字段验证给定的值。
  • 错误消息键:requiredinvalid

另外需要一个参数:

字段 T0> ¶ T1>

应该用来验证字段值的字段列表(按照提供的顺序)。

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

MultiValueField(fields=(), **kwargs)[source]
  • 默认小部件:TextInput
  • 空值:''(一个空字符串)
  • 规范化为:子类的compress方法返回的类型。
  • 根据指定为MultiValueField的参数的每个字段验证给定的值。
  • 错误消息键:requiredinvalidincomplete

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

这个领域是抽象的,必须分类。 与单值字段相比,MultiValueField的子类不能实现clean(),而是实现compress()

另外需要一个参数:

字段 T0> ¶ T1>

一个字段的元组,其值被清除并随后组合成单个值。 每个字段的值由fields中的相应字段清除 - 第一个值由第一个字段清除,第二个值由第二个字段清除等。一旦清除了所有字段,干净值列表通过compress()合并为一个值。

也需要一些可选的参数:

require_all_fields T0> ¶ T1>

默认是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
        )
插件 T0> ¶ T1>

必须是django.forms.MultiWidget的子类。 默认值是TextInput,在这种情况下这可能不是很有用。

compress(data_list)[source]

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

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

SplitDateTimeField

SplitDateTimeField(**kwargs)[source]
  • 默认控件:SplitDateTimeWidget
  • 空值:None
  • 规范化为:Python datetime.datetime对象。
  • 验证给定值是以特定日期时间格式格式化的datetime.datetime或字符串。
  • 错误消息键:requiredinvalidinvalid_dateinvalid_time

采取两个可选参数:

input_date_formats T0> ¶ T1>

用于尝试将字符串转换为有效的datetime.date对象的格式列表。

如果没有提供input_date_formats参数,则使用DateField的默认输入格式。

input_time_formats T0> ¶ T1>

用于尝试将字符串转换为有效的datetime.time对象的格式列表。

如果没有提供input_time_formats参数,则使用TimeField的默认输入格式。

处理关系的字段

两个字段可用于表示模型之间的关系:ModelChoiceFieldModelMultipleChoiceField 这两个字段都需要使用一个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

ModelChoiceField(**kwargs)[source]
  • 默认小部件:Select
  • 空值:None
  • 规范化为:模型实例。
  • 验证给定的ID是否存在于查询集中。
  • 错误消息键:requiredinvalid_choice

允许选择适合于表示外键的单个模型对象。 请注意,当条目数量增加时,ModelChoiceField的默认控件变得不切实际。 你应该避免使用它超过100个项目。

一个参数是必需的:

查询集 T0> ¶ T1>

模型对象的一个​​QuerySet,从中导出字段的选项,并用于验证用户的选择。 它在表单呈现时被评估。

ModelChoiceField also takes two optional arguments:

empty_label T0> ¶ T1>

默认情况下,由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 T0> ¶ T1>

此可选参数用于指定要用作字段小部件中的选项值的字段。 确保它是模型的唯一字段,否则所选值可以匹配多个对象。 默认情况下,它被设置为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

ModelMultipleChoiceField(**kwargs)[source]
  • 默认小部件:SelectMultiple
  • 空值:一个空的QuerySet(self.queryset.none())
  • 规范化为:模型实例的QuerySet
  • 验证给定值列表中的每个id是否存在于查询集中。
  • 错误消息键:requiredlistinvalid_choiceinvalid_pk_value

The invalid_choice message may contain %(value)s and the invalid_pk_value message may contain %(pk)s, which will be substituted by the appropriate values.

允许选择一个或多个模型对象,适合表示多对多的关系。 ModelChoiceField一样,您可以使用label_from_instance自定义对象表示。

一个参数是必需的:

查询集 T0> ¶ T1>

ModelChoiceField.queryset相同。

采取一个可选参数:

to_field_name T0> ¶ T1>

ModelChoiceField.to_field_name相同。

创建自定义字段

如果内置的Field类不能满足您的需求,您可以轻松创建自定义的Field类。 为此,只需创建django.forms.Field的子类。 Its only requirements are that it implement a clean() method and that its __init__() method accept the core arguments mentioned above (required, label, initial, widget, help_text).

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