revision-up-to: | 11321 (1.1) unfinished |
---|
Field
(**kwargs)¶フォームクラスの作成で一番重要なのは、フォームの各フィールドの定義です。各 フィールドには固有のデータ検証ロジックと、いくつかのフックが備わっています。
Field.
clean
(value)¶フィールドクラスの主な用途はフォームクラスにおけるフィールド定義ですが、フィー
ルドクラスは直接インスタンス化して使えるので、フィールドの動作を理解する役
に立つはずです。各フィールドインスタンスは clean()
メソッドを備えており、
単一の引数を取って検証を行い、その結果に応じて
django.newforms.ValidationError
を送出するか、クリーニング済みの値を返
します:
>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
u'foo@example.com'
>>> f.clean(u'foo@example.com')
u'foo@example.com'
>>> f.clean('invalid e-mail address')
Traceback (most recent call last):
...
ValidationError: [u'Enter a valid e-mail address.']
各フィールドクラスのコンストラクタは、少なくとも以下に示す引数を取ります。 フィールドクラスによっては他にもフィールド固有の引数をとりますが。ここに示 す引数はどのフィールドクラスでも 常に 指定できる引数です:
required
¶Field.
required
¶デフォルトでは、フィールドクラスはフィールドが必須 (reqired) であると仮定し
ています。従って、フィールドに空の値、すなわち None
や空文字列 (""
)
を渡すと、 clean()
は VaridationError
例外を送出します:
>>> f = forms.CharField()
>>> f.clean('foo')
u'foo'
>>> f.clean('')
Traceback (most recent call last):
...
ValidationError: [u'This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: [u'This field is required.']
>>> f.clean(' ')
u' '
>>> f.clean(0)
u'0'
>>> f.clean(True)
u'True'
>>> f.clean(False)
u'False'
必須で ない フィールドにするには、フィールドのコンストラクタに
required=False
を指定します:
>>> f = forms.CharField(required=False)
>>> f.clean('foo')
u'foo'
>>> f.clean('')
u''
>>> f.clean(None)
u''
>>> f.clean(0)
u'0'
>>> f.clean(True)
u'True'
>>> f.clean(False)
u'False'
required=False
のフィールドの clean()
に空の値を渡して呼び出すと、
clean()
は VaridationError
を送出する代わりに 正規化された 空の値
を返します。例えば CharField
の場合なら、 Unicode の空文字列になります。
その他のフィールドクラスでは None
になるはずです (フィールドによって異
なります)。
label
¶Field.
label
¶label
引数を使うと、フィールドに「人間に優しい」ラベルを指定できます。
このラベルはフォーム内でフィールドを表示するときに使われます。
フィールドのデフォルトのラベルはフィールド名のアンダースコアを除去して、頭 文字を大文字にしたものです。デフォルトのラベル命名規則で期待通りのラベルが 出力されない場合には、この引数を指定してください。
label
を指定したフォームの例を以下に示します。出力を短くするために
auto_id=False
にしています:
>>> class CommentForm(forms.Form):
... name = forms.CharField(label='Your name')
... url = forms.URLField(label='Your Web site', required=False)
... comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print f
<tr><th>Your name:</th><td><input type="text" name="name" /></td></tr>
<tr><th>Your Web site:</th><td><input type="text" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
initial
¶Field.
initial
¶initial
引数を使うと、非束縛フォーム内でフィールドをレンダするときの初
期値を指定できます。
初期値を動的に設定したいなら、 Form.initial
パラメタの解説を参照し
てください。
この引数を使うケースは、例えば以下のように、「空の」フォームの各フィールド を特定の値で初期化して表示したい場合です:
>>> 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" /></td></tr>
<tr><th>Url:</th><td><input type="text" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></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" /></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="text" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></td></tr>
このため、非束縛フォームの場合に限って initial
に指定した値が出力される
ようになっているのです。束縛フォームの場合、出力は常に束縛済みのデータです。
また、 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
# フォームの値は初期値にフォールバック *しません。*
>>> f.errors
{'url': [u'This field is required.'], 'name': [u'This field is required.']}
Instead of a constant, you can also pass any callable:
>>> 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" /><td></tr>
The callable will be evaluated only when the unbound form is displayed, not when it is defined.
widget
¶Field.
widget
¶widget
引数を使うと、フィールドをレンダリングするときの Widget
クラ
スを指定できます。詳しくは ref-forms-widgets を参照してください。
help_text
¶Field.
help_text
¶help_text
引数を使うと、フィールドに説明文をつけられます。
help_text
を指定した場合、フォームを (as_ul()
のような) フォームメ
ソッドでレンダした時に、該当フィールドの隣に表示されます。
以下に、 help_text
を使ったフォームの例を示します。この例では、フォーム
の二つのフィールドに help_text
を指定しています。出力を単純にするために、
auto_id=False
を指定しています:
>>> 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 e-mail 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" /><br />100 characters max.</td></tr>
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
<tr><th>Sender:</th><td><input type="text" name="sender" /><br />A valid e-mail 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" /> 100 characters max.</li>
<li>Message: <input type="text" name="message" /></li>
<li>Sender: <input type="text" name="sender" /> A valid e-mail 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" /> 100 characters max.</p>
<p>Message: <input type="text" name="message" /></p>
<p>Sender: <input type="text" name="sender" /> A valid e-mail address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
error_messages
¶Field.
error_messages
¶error_messages
引数を使うと、フィールドが送出するデフォルトのメッセージ
をオーバライドできます。オーバライドしたいメッセージに対応する文字列をキー
とし、メッセージを値に持つ辞書を渡してください。例えば、デフォルトのメッセー
ジが以下のようだったとします:
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
...
ValidationError: [u'This field is required.']
カスタムのエラーメッセージは以下のようにして設定します:
>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
...
ValidationError: [u'Please enter your name']
各フィールドで定義されているエラーメッセージのキーは、後述の 組み込みフォームフィールドクラス の節で定義しています。
通常、 forms
ライブラリには、一般的なバリデーション機能を備えたフィー
ルドクラスのセットがついてきます。この節では、そうした組み込みフィールドに
ついて述べます。
各フィールドについて、 widget
パラメタを指定しなかったときのデフォルト
のウィジェット型について説明しています。また、データが空の値だったとき
(前述の requied
の節を参照してください) に返される値についても定義して
います。
BooleanField
¶BooleanField
(**kwargs)¶CheckboxInput
False
True
または False
値required=True
の場合、チェックボックスがチェックされているか (値
が True
であるか) 検証します。required
CheckboxInput
(および標準の BooleanField
) に空の値を指定した場合
のデフォルト値が None
から False
に変更されました。Note
全てのフィールドのサブクラスにデフォルトで required=True
が設定され
るようになったので、バリデーション条件の設定は重要です。チェックされる
場合とされない場合のあるチェックボックスをフォームに含めたい場合は、
BooleanField
を生成する際に required=False
を忘れずに指定せねば
なりません。
CharField
¶CharField
(**kwargs)¶TextInput
''
(空文字列)max_length
または min_length
が指定された場合、文字列長を検証
します。それ以外の場合、どのような入力も valid とみなします。required
, max_length
, min_length
オプションの引数が 2 つあります:
CharField.
max_length
¶CharField.
min_length
¶これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たし ているか検証します。
ChoiceField
¶ChoiceField
(**kwargs)¶Select
''
(空文字列)required
, invalid_choice
必須の引数を一つとります:
ChoiceField.
choices
¶イテレーション可能オブジェクト (たとえばリストやタプルなど) で、各要素 はフィールドの選択肢として使える 2 要素のタプルでなければなりません。
TypedChoiceField
¶TypedChoiceField
(**kwargs)¶ChoiceField
に似ていますが、 TypedChoiceField
には
coerce
引数があります。
- デフォルトのウィジェット:
Select
- 空のフォームデータに対する値:
empty_value
の指定値- Python データへの正規化:
coerce
引数の戻り値- 入力値が選択肢内にある値かどうか検証します。
- エラーメッセージのキー:
required
,invalid_choice
以下の追加の引数をとります:
TypedChoiceField.
coerce
¶引数を一つとり、型強制した値を返す関数を指定します。例えば、組み込みの
int
, float
, bool
などです。等値関数がデフォルト値として設定
されています。
TypedChoiceField.
empty_value
¶「空の入力」を示すのに使う値です。デフォルト値は空文字列です。 None
も良く使う値です。
DateField
¶DateField
(**kwargs)¶DateInput
None
datetime.date
オブジェクトdatetime.date
や datetime.datetime
オブジェクト、ま
たは特定の日付フォーマットの形式に従っているか検証します。required
, invalid
以下のオプションの引数をとります:
DateField.
input_formats
¶文字列から有効な datetime.date
オブジェクトへの変換を試みるために使
われるフォーマット文字列からなるリストです。
input_formats
を指定しない場合、デフォルトで以下の入力フォーマットをサ
ポートします:
'%Y-%m-%d', '%m/%d/%Y', '%m/%d/%y', # '2006-10-25', '10/25/2006', '10/25/06'
'%b %d %Y', '%b %d, %Y', # 'Oct 25 2006', 'Oct 25, 2006'
'%d %b %Y', '%d %b, %Y', # '25 Oct 2006', '25 Oct, 2006'
'%B %d %Y', '%B %d, %Y', # 'October 25 2006', 'October 25, 2006'
'%d %B %Y', '%d %B, %Y', # '25 October 2006', '25 October, 2006'
DateField
previously used a TextInput
widget by default. It now
uses a DateInput
widget.DateTimeField
¶DateTimeField
(**kwargs)¶DateTimeInput
None
datetime.datetime
オブジェクトdatetime.date
や datetime.datetime
オブジェクト、ま
たは特定の日付フォーマットの形式に従っているか検証します。required
, invalid
以下のオプションの引数をとります:
DateTimeField.
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'
DateTimeField
はデフォルトで TextInput
を使っていましたが、変更
されました。DecimalField
¶DecimalField
(**kwargs)¶TextInput
None
decimal
オブジェクトrequired
, invalid
, max_value
,
min_value
, max_digits
, max_decimal_places
,
max_whole_digits
4 つのオプション引数を取ります:
DecimalField.
max_value
¶DecimalField.
min_value
¶それぞれ、フィールドの値のとり得る最大/最小値です。
DecimalField.
max_digits
¶最大の桁数 (先頭のゼロ詰め桁を除いた上での小数点前後の桁数の合計) です。
DecimalField.
decimal_places
¶decimal_places
は小数部の最大桁数です。
EmailField
¶EmailField
(**kwargs)¶TextInput
''
(空文字列)required
, invalid
オプションの引数として、 max_length
と min_length
の二つをとれます。
これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たしてい
るか検証します。
FileField
¶FileField
(**kwargs)¶FileInput
None
UploadedFile
オブジェクト。required
, invalid
, missing
, empty
UploadedFile
オブジェクトの詳細は
ファイルアップロードのドキュメント を参照して
ください。
FileField
をフォームで使う場合、
フォームにファイルデータを束縛する のを忘れ
ないようにしてください。
FilePathField
¶FilePathField
(**kwargs)¶Select
None
required
, invalid_choice
このフィールドを使うと、あるディレクトリの下にあるファイルを選択できます。
フィールドは以下の 3 つの引数を追加で取り、 path
のみ必須の引数です:
FilePathField.
path
¶ファイルの一覧を表示したいディレクトリの絶対パスです。実在するディレク トリを指定せねばなりません。
FilePathField.
recursive
¶False
(デフォルト値) の場合、 path
の直下にあるファイルのみを選
択肢として表示します。 True
にすると、 path
以下の全てのファイ
ルを再帰的に探索して選択肢にします。
FilePathField.
match
¶正規表現です。この引数を指定すると、正規表現にマッチしたファイル名だけ を選択肢として表示します。
FloatField
¶
- デフォルトのウィジェット:
TextInput
- 空のフォームデータに対する値:
None
- Python データへの正規化: Python の float 型
- 指定された値が浮動小数点数を表すかどうか検証します。 Python の
float()
関数と同じく、前後に空白があってもかまいません。- エラーメッセージのキー:
required
,invalid
,max_value
,min_value
オプションの引数として、 max_value
および min_value
をとります。こ
れらの値は、入力値のとりえる値域の調整に使われます。
ImageField
¶ImageField
(**kwargs)¶FileInput
None
UploadedFile
オブジェクト。required
, invalid
, missing
, empty
,
invalid_image
ImageField を使いたい場合、 Python Imaging Library をインストールしてお かねばなりません。
ImageField
をフォームで使う場合、
フォームにファイルデータを束縛する
のを忘れないようにしてください。
IntegerField
¶IntegerField
(**kwargs)¶TextInput
None
int()
関数と同様、先頭
や末尾に空白があってもかまいません。required
, invalid
, max_value
,
min_value
以下の二つの引数をとります:
IntegerField.
max_value
¶IntegerField.
min_value
¶フィールドのとり得る値の最大値および最小値です。
IPAddressField
¶IPAddressField
(**kwargs)¶TextInput
''
(空の文字列)required
, invalid
MultipleChoiceField
¶MultipleChoiceField
(**kwargs)¶SelectMultiple
[]
(空のリスト)required
, invalid_choice
, invalid_list
追加の引数として choices
をとります。 choices
の意味は
ChoiceField
の choices
と同じです。
NullBooleanField
¶NullBooleanField
(**kwargs)¶NullBooleanSelect
None
True
, False
または None
。VaridationError
を送出しません)。RegexField
¶RegexField
(**kwargs)¶TextInput
''
(空文字列)required
, invalid
追加の引数を一つ持っています:
RegexField.
regex
¶regex
は正規表現を表す文字列またはコンパイル済みの正規表現オブジェ
クトです。
CharField
と同様、 max_length
および min_length
をとります。
以前のバージョンとの互換性のため、オプション引数 error_message
も指定で
きるようになっています。エラーメッセージを指定したければ、
error_messages
を使って、 'invalid'
をキーにしたメッセージを指定す
るよう薦めます。
TimeField
¶TimeField
(**kwargs)¶TextInput
None
datetime.time
オブジェクトdatetime.time
オブジェクトまたは特定の日付フォーマットの
形式に従っているか検証します。required
, invalid
オプションの引数を一つ持っています:
TimeField.
input_formats
¶文字列から有効な datetime.time
オブジェクトへの変換を試みるために使
われるフォーマット文字列からなるリストです。
input_formats
を指定しない場合、デフォルトで以下の入力フォーマットをサ
ポートします:
'%H:%M:%S', # '14:30:59'
'%H:%M', # '14:30'
URLField
¶URLField
(**kwargs)¶TextInput
''
(空文字列)required
, invalid
, invalid_link
以下のオプションの引数をとります:
URLField.
max_length
¶URLField.
min_length
¶CharField.max_length
や CharField.min_length
と同じです。
URLField.
verify_exists
¶True
にすると、バリデータが指定された URLをロードできるか調べ、該当
ページの HTTP レスポンスが 404 のときに ValidationError
を送出しま
す。デフォルト値は False
です。
URLField.
validator_user_agent
¶URL が存在するか確かめるときに使うユーザエージェントを表す文字列です。
デフォルト値は URL_VALIDATOR_USER_AGENT
設定の値です。
以下のフィールドはまだドキュメント化されていません。
ComboField
(**kwargs)¶MultiValueField
(**kwargs)¶SplitDateTimeField
(**kwargs)¶SplitDateTimeWidget
None
datetime.datetime
object.datetime.datetime
or string
formatted in a particular datetime format.required
, invalid
Takes two optional arguments:
SplitDateTimeField.
input_date_formats
¶A list of formats used to attempt to convert a string to a valid
datetime.date
object.
If no input_date_formats
argument is provided, the default input formats
for DateField
are used.
SplitDateTimeField.
input_time_formats
¶A list of formats used to attempt to convert a string to a valid
datetime.time
object.
If no input_time_formats
argument is provided, the default input formats
for TimeField
are used.
SplitDateTimeField
previously used two TextInput
widgets by
default. The input_date_formats
and input_time_formats
arguments
are also new.モデル間のリレーションを表現するために、二つのフィールドが提供されています。
これらのフィールドは、選択肢を QuerySet
から取り出します:
ModelChoiceField
(**kwargs)¶ModelMultipleChoiceField
(**kwargs)¶これらのフィールドは、入力に応じて、フォームの cleaned_data
辞書内にモ
デルオブジェクトをいれます。どちらのフィールド型にも必須の引数が一つありま
す:
ModelChoiceField.
queryset
¶フィールドが選択肢として表示するモデルオブジェクトの QuerySet
です。
また、フィールドはこの QuerySet
を使って、ユーザの選択値が
QuerySet
内に含まれているかを検証します。
ModelChoiceField
¶モデルオブジェクト一つを選択できるフィールドです。外部キーを表現するのに適 しています。
フィールドの選択肢として表示される文字列の取得には、モデルオブジェクトの
__unicode__
メソッドを使います。表示をカスタマイズしたければ、
ModelChoicefield
をサブクラス化して、 label_for_instance
メソッドを
オーバライドしてください。このメソッドはモデルオブジェクトを引数にとり、表
示に適した文字列を返さねばなりません:
class MyModelChoiceField(ModelChoiceField):
def label_from_instance(self, obj):
return "My Object #%i" % obj.id
ModelChoiceField.
empty_label
¶By default the <select>
widget used by ModelChoiceField
will have a
an empty choice at the top of the list. You can change the text of this label
(which is "---------"
by default) with the empty_label
attribute, or
you can disable the empty label entirely by setting empty_label
to
None
:
# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
Note that if a ModelChoiceField
is required and has a default
initial value, no empty choice is created (regardless of the value
of empty_label
).
ModelMultipleChoiceField
¶複数のモデルオブジェクトを選択できるフィールドです。多対多のリレーションを
表現するのに向いています。 ModelChoiceField
と同様、オブジェクトの表示
を変更するには label_from_instance
メソッドをオーバライドしてください。
組み込みのフィールドクラスが用途に合わなくても、カスタムのフィールドクラス
は簡単に作成できるので大丈夫です。カスタムのフィールドクラスは
django.forms.Field
をサブクラス化して作成します。
フィールドクラスを定義する際の制約は、 clean()
メソッドを実装すること、
__init__()
メソッドにコアの引数 (required
, label
, initial
,
widget
, help_text
) を持たせることだけです。
Oct 26, 2017