核心字段参数
每个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'
要指定一个字段不是必需的,通过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'
label
Field.label
该label参数允许您为此字段指定“人性化”标签。当Field在a中显示时使用Form。
如上面的“将表单作为HTML输出”中所述,a的默认标签 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>
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']
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='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>
只有在显示未绑定的表单时才会计算callable,而不是在定义时。