核心字段参数

required

给字段添加必填属性。默认情况下,每个Field类的都假定该值是必须的,因此如果传递一个空置或者是空字符串,那么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'

需要指定一个字段不是必须的,通过设置required=False

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

label

label参数用来给字段添加人类友好的提示信息。如果没有设置这个参数,那么将使用字段首字母大写的名字。

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

Django默认label参数后面加个冒号后缀,如果需要自定义,可以使用lable_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

为HTML页面中表单元素定义初始值,也就是input元素的value参数的值。

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

如果在渲染表单的时候传递一个包含初始化值的字典给表单,将触发表单的验证过程,此时输出的HTML页面将包含验证中产生的错误。这也是initial参数值用在未绑定的表单上的原因。

>>> 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的值不会作为默认的数据。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

指定渲染Widget时使用的widget类,也就是这个form字段在HTML页面中显示为文本输入框、密码输入框、单选按钮、多选按钮还是其他的。

help_text

该参数用于设置字段的辅助描述文本。

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

该参数允许覆盖字段引发异常时的默认信息。传递的是一个字段,其键为你想要覆盖的错误信息。
默认错误信息示例:

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

validators

指定一个列表,其中包含了为字段进行验证的函数。也就是说,如果自定义了验证方法,不用使用Django内置的验证功能,那么要通过这个参数,将字段和自定义的验证方式链接起来。

localize

localize参数帮助实现表单数据输入的本地化。

disabled

设置有该属性的字段在前端页面中将显示为不可编辑状态。
该参数接受布尔值,当设置为True时,使用HTML的disabled属性禁用表单域,以使用户无法编辑该字段,即便非法篡改了前端页面的属性,向服务器提交了该字段的值,也将依然被忽略。

内置的Field类

BoolenField

  • 默认的Widget:CheckboxInput。
  • 空置:False。
  • 规范:Python的False或True。
  • 可用的错误信息键:required。

CharField

  • 默认的Widget:TextInput。
  • 空置:empty_value给出的任何值。
  • 规范:一个Unicode对象。
  • 如果设置了max_length或min_length,将对值进行验证,否则所有的输入都将是合法的。
  • 可用的错误信息键:required, min_length, max_length。

ChoiceField

  • 默认的Widget:Select。
  • 空置:””(一个空字符串)。
  • 规范:一个Unicode对象。
  • 验证给定的值是否在选项列表中。
  • 可用的错误信息键:required, invalid_choice。
  • 参数choices:用来作为该字段选项的一个二元组组成的可迭代对象或者一个可调用对象。格式与用于和ORM模型字段的choices参数相同。

TypedChoiceField

  • 默认的Widget:Select。
  • 空置:empty_value参数设置的值。
  • 规范:coerce参数类型的值。
  • 验证给定的值在选项列表中存在并且可以被强制转换。
  • 可用的错误信息键:required, invalid_choice。

DateField

  • 默认的Widget:DateInput。
  • 空置:None。
  • 规范:datetime.date对象。
  • 验证给出的值是一个datetime.date、datetime.datetime 或指定日期格式的字符串。
  • 可用的错误信息键:required, invalid。
  • 可选参数:input_formats,一个格式的列表,用于转换字符串为datetime.date对象,如果没有提供,默认格式为:['%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y']

DateTimeField

  • 默认的Widget:Widget:DateTimeInput。
  • 空置:None。
  • 规范:datetime.datetime。
  • 验证给出的值是一个datetime.datetime、datetime.date或指定日期格式的字符串。
  • 的错误信息键:required, invalid。
  • 接受可选参数:input_formats,一个格式的列表,用于转换字符串为datetime.date对象,如果没有提供,默认格式为:['%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d', '%m/%d/%Y %H:%M:%S', '%m/%d/%Y %H:%M', '%m/%d/%Y', '%m/%d/%y %H:%M:%S', '%m/%d/%y %H:%M', '%m/%d/%y']

DecimalField

  • 默认的Widget:当Field.localize是False时为NumberInput,否则为TextInput。
  • 空置:None。
  • 规范:Python decimal对象。
  • 验证给定的值为一个十进制数。 忽略前导和尾随的空白。
  • 可用的错误信息键:max_whole_digits, max_digits, max_decimal_places, max_value, invalid, required, min_value。
  • 可选参数:
    • max_value, min_value:允许的值的范围,需要复制decimal.Decimal对象,不能直接给个整数类型。
    • max_digits:值允许的最大位数(小数点之前和之后的数字总共的位数,前导零奖杯删除)。
    • decimal_places:允许的最大小数位。

DurationField

  • 默认的Widget:TextInput。
  • 空置:None。
  • 规范:Python timedelta。
  • 验证给出的值是一个字符串,而且可以转换为timedelta对象。
  • 可用的错误信息键:required, invalid。

EmailField

  • 默认的Widget:EmailInput。
  • 空置:””(一个空字符串)。
  • 规范:Unicode 对象。
  • 使用正则表达式验证给出的值是一个合法的邮件地址。
  • 可用的错误信息键:required, invalid。
  • 可选参数:max_length, min_length。

FileField

  • 默认的Widget:ClearableFileInput。
  • 空置:None。
  • 规范:一个UploadedFile对象,它封装文件内容和文件名到一个对象内。
  • 验证非空的文件数据已经绑定到表单。
  • 可用的错误信息键:missing, invalid, required, empty, max_length。
  • 可选参数:max_length, allow_empty_file。

FilePathField

  • 默认的Widget:Select。
  • 空置:None。
  • 规范:Unicode 对象。
  • 验证选择的选项在选项列表中存在。
  • 可用的错误信息键:required, invalid_choice。
  • 额外参数:
    • path(必须):要列出的目录的绝对路径。这个目录必须存在。
    • recursive:如果为False(默认值),只用直接位于path下的文件或目录作为选项。如果为True,将递归访问这个目录,其内所有的子目录和文件都将作为选项。
    • match:正则表达模式;只有具有与此表达式匹配的文件名称才被允许作为选项。
    • allow_fiels:默认为True。表示是否应该包含指定位置的文件,它和allow_floders必须有一个为True。
    • allow_floders:默认为False,表示是否应该包含指定位置的目录。

FloatField

  • 默认的Widget:当Field.localize是False时为NumberInput,否则为TextInput。
  • 空值:None。
  • 规范:Float对象。
  • 验证给定的值是一个浮点数。
  • 错误信息的键:max_value, min_value, invalid, required。
  • 可选参数:max_value和min_value,控制允许的值的范围。

ImageField

  • 默认的Widget:ClearableFileInput。
  • 空值:None。
  • 规范:一个UploadedFile对象,它封装文件内容和文件名为一个单独的对象。
  • 验证文件数据已绑定到表单,并且该文件是Pillow可以解析的图像格式。
  • 错误信息的键:missing, invalid, required, empty, invalid_image。

IntegerField

  • 默认的Widget:当Field/.loaclize是Fasle时为NumberInput,否则为TextInput。
  • 空值:None。
  • 规范:Python整数或长整数。
  • 验证给定值是一个整数。允许前导和尾随空格,类似Python的int()函数。
  • 错误信息的键:max_value, min_value, required, invalid。
  • 可选参数:max_value, min_value,空值允许的值的范围。

GenericlIPAddressField

包含IPv4或IPv6地址的字段。

  • 默认的Widget:TextInput。
  • 空值:””(一个空字符串)。
  • 规范:一个Unicode对象。
  • 验证给定值是有效的IP地址。
  • 错误信息的键:required, invalid。
  • 可选参数:protocol, unpack_ipv4。

MultipleChoiceField

  • 默认的Widget:SelectMultiple。
  • 空值:[](一个空列表)
  • 规范:一个Unicode对象列表。
  • 验证给定值列表中的每个值都存在于选项列表中。
  • 错误信息的键:invalid_list, invalid_choice, required。

TypeMultipleChoiceField

类似MultipleChoiceField,只不过TypeMultipleChoiceField需要额外接受两个参数:coerce, empty_value。

  • 默认的Widget:SelectMultiple。
  • 空值:empty_value。
  • 规范:coerce参数提供的类型值列表。
  • 验证给定值存在于选项列表中并且可以强制转换。
  • 错误信息的键:required, invalid_choice。

NullBooleanField

  • 默认的Widget:NullBooleanSelect。
  • 空值:None。
  • 规范:Python的None, False或True值。
  • 不验证任何内容,即,从不引发ValidationError。

RegexField

  • 默认的Widget:TextInput。
  • 空值:””(一个空字符串)。
  • 规范:一个Unicode对象。
  • 验证给定值与某个正则表达式匹配。
  • 错误信息的键:required, invalid。
  • 必填参数:regex,需要匹配的正则表达式。
  • 可选参数:max_length, min_length, strip。

SlugField

  • 默认的Widget:TextInput。
  • 空值:””(一个空字符串)。
  • 规范:一个Unicode对象。
  • 验证给定的字符串只包含字母、数字、下划线及连字符。
  • 错误信息的键:required, invalid。

TimeField

  • 默认的Widget:TextInput。
  • 空值:None。
  • 规范:一个Pythond的datetime.time对象。
  • 验证给定值是datetime.time或以特定时间格式格式化的字符串。
  • 错误信息的键:required, invalid。
  • 可选参数:input_formats,用于尝试将字符串转换为有效的datetime.time对象的格式列表。

URLField

  • 默认的Widget:URLInput。
  • 空值:””(一个空字符串)。
  • 规范:一个Unicode对象。
  • 验证给定值是个有效的URL。
  • 错误信息的键:required, invalid。
  • 可选参数:min_length, max_length

UUIDField

  • 默认的Widget:TextInupt。
  • 空值:””(一个空字符串)。
  • 规范:Unicode对象。
  • 根据指定为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

  • 默认的Widget:TextInput。
  • 空值:””(一个空字符串)。
  • 规范:子类的compress方法返回的类型。
  • 根据指定为MultiValueField的参数的每个字段验证给定值。
  • 错误信息的键:incomplete, invalid, required。

SplitDateTimeField

  • 默认的Widget:SplitDateTimeWidget。
  • 空值:None。
  • 规范:Python的datetime.datetime对象。
  • 验证给定的值是datetime.datetime或以特定日期格式格式化的字符串。
  • 错误信息的键:invalid_date, invalid, required, invalid_time。

创建自定义字段

如果内置的Field真的不能满足需求,还可以自定义Field。只需要创建一个django.forms.Field的子类,并实现clean()__init__()构造方法。__init__()构造方法需要接受前面提到过的那些核心参数,比如widget, required, label, help_text, initial。
还可以通过覆盖get_bound_field()方法来自定义访问字段的方式。

0条评论

相关推荐

django教程

r

Django 2019-05-20 10:53:53

Celery

celery学习资料

Django 2019-05-25 18:41:55

Django-rest-framework教程

django-rest-framework教程。

Django 2019-07-18 16:33:26

django实用资料

django项目从0到1自己总结的实用的资料,大部分常用的功能这里都有

Django 2019-05-08 18:21:34