.. _ref-forms-fields:
======================
フォームフィールド
======================
:revision-up-to: 11321 (1.1) unfinished
.. module:: django.forms.fields
:synopsis: Django の組み込みフォームフィールドです。
.. currentmodule:: django.forms
.. class:: Field(**kwargs)
フォームクラスの作成で一番重要なのは、フォームの各フィールドの定義です。各
フィールドには固有のデータ検証ロジックと、いくつかのフックが備わっています。
.. method:: 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``
~~~~~~~~~~~~
.. attribute:: 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``
~~~~~~~~~
.. attribute:: 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
Your name: | |
Your Web site: | |
Comment: | |
``initial``
~~~~~~~~~~~
.. attribute:: Field.initial
``initial`` 引数を使うと、非束縛フォーム内でフィールドをレンダするときの初
期値を指定できます。
初期値を動的に設定したいなら、 :attr:`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
Name: | |
Url: | |
Comment: | |
こんなことをしなくても、フォームに初期データの入った辞書を渡せばいいのにと
思うかもしれませんね。しかし、フォームにデータを渡して束縛フォームにすると、
データを表示する際に検証がトリガされてしまい、 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
Name: | |
Url: | |
Comment: | |
このため、非束縛フォームの場合に限って ``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()
Day: | | |
The callable will be evaluated only when the unbound form is displayed, not when it is defined.
``widget``
~~~~~~~~~~
.. attribute:: Field.widget
``widget`` 引数を使うと、フィールドをレンダリングするときの ``Widget`` クラ
スを指定できます。詳しくは :ref:`ref-forms-widgets` を参照してください。
``help_text``
~~~~~~~~~~~~~
.. attribute:: 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()
Subject: | 100 characters max. |
Message: | |
Sender: | A valid e-mail address, please. |
Cc myself: | |
>>> print f.as_ul()
Subject: 100 characters max.
Message:
Sender: A valid e-mail address, please.
Cc myself:
>>> print f.as_p()
Subject: 100 characters max.
Message:
Sender: A valid e-mail address, please.
Cc myself:
``error_messages``
~~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0
.. attribute:: 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``
~~~~~~~~~~~~~~~~
.. class:: BooleanField(**kwargs)
* デフォルトのウィジェット: ``CheckboxInput``
* 空のフォームデータに対する値: ``False``
* Python データへの正規化: Python の ``True`` または ``False`` 値
* ``required=True`` の場合、チェックボックスがチェックされているか (値
が ``True`` であるか) 検証します。
* エラーメッセージのキー: ``required``
.. versionchanged:: 1.0
``CheckboxInput`` (および標準の ``BooleanField``) に空の値を指定した場合
のデフォルト値が ``None`` から ``False`` に変更されました。
.. note::
全てのフィールドのサブクラスにデフォルトで ``required=True`` が設定され
るようになったので、バリデーション条件の設定は重要です。チェックされる
場合とされない場合のあるチェックボックスをフォームに含めたい場合は、
``BooleanField`` を生成する際に ``required=False`` を忘れずに指定せねば
なりません。
``CharField``
~~~~~~~~~~~~~
.. class:: CharField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``''`` (空文字列)
* Python データへの正規化: Unicode 文字列オブジェクト
* ``max_length`` または ``min_length`` が指定された場合、文字列長を検証
します。それ以外の場合、どのような入力も valid とみなします。
* エラーメッセージのキー: ``required``, ``max_length``, ``min_length``
オプションの引数が 2 つあります:
.. attribute:: CharField.max_length
.. attribute:: CharField.min_length
これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たし
ているか検証します。
``ChoiceField``
~~~~~~~~~~~~~~~
.. class:: ChoiceField(**kwargs)
* デフォルトのウィジェット: ``Select``
* 空のフォームデータに対する値: ``''`` (空文字列)
* Python データへの正規化: Unicode 文字列オブジェクト
* 入力値が選択肢内にある値かどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid_choice``
必須の引数を一つとります:
.. attribute:: ChoiceField.choices
イテレーション可能オブジェクト (たとえばリストやタプルなど) で、各要素
はフィールドの選択肢として使える 2 要素のタプルでなければなりません。
``TypedChoiceField``
~~~~~~~~~~~~~~~~~~~~
.. class:: TypedChoiceField(**kwargs)
:class:`ChoiceField` に似ていますが、 :class:`TypedChoiceField` には
``coerce`` 引数があります。
* デフォルトのウィジェット: ``Select``
* 空のフォームデータに対する値: ``empty_value`` の指定値
* Python データへの正規化: ``coerce`` 引数の戻り値
* 入力値が選択肢内にある値かどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid_choice``
以下の追加の引数をとります:
.. attribute:: TypedChoiceField.coerce
引数を一つとり、型強制した値を返す関数を指定します。例えば、組み込みの
``int``, ``float``, ``bool`` などです。等値関数がデフォルト値として設定
されています。
.. attribute:: TypedChoiceField.empty_value
「空の入力」を示すのに使う値です。デフォルト値は空文字列です。 ``None``
も良く使う値です。
``DateField``
~~~~~~~~~~~~~
.. class:: DateField(**kwargs)
* デフォルトのウィジェット: ``DateInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python ``datetime.date`` オブジェクト
* 入力値が ``datetime.date`` や ``datetime.datetime`` オブジェクト、ま
たは特定の日付フォーマットの形式に従っているか検証します。
* エラーメッセージのキー: ``required``, ``invalid``
以下のオプションの引数をとります:
.. attribute:: 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'
.. versionchanged:: 1.1
The ``DateField`` previously used a ``TextInput`` widget by default. It now
uses a ``DateInput`` widget.
``DateTimeField``
~~~~~~~~~~~~~~~~~
.. class:: DateTimeField(**kwargs)
* デフォルトのウィジェット: ``DateTimeInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python ``datetime.datetime`` オブジェクト
* 入力値が ``datetime.date`` や ``datetime.datetime`` オブジェクト、ま
たは特定の日付フォーマットの形式に従っているか検証します。
* エラーメッセージのキー: ``required``, ``invalid``
以下のオプションの引数をとります:
.. attribute:: 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'
.. versionchanged:: 1.0
``DateTimeField`` はデフォルトで ``TextInput`` を使っていましたが、変更
されました。
``DecimalField``
~~~~~~~~~~~~~~~~
.. versionadded:: 1.0
.. class:: DecimalField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python の ``decimal`` オブジェクト
* 値が 10 進小数に変換可能か検証します。文字列の先頭および末尾の空白文
字は除去されます。
* エラーメッセージのキー: ``required``, ``invalid``, ``max_value``,
``min_value``, ``max_digits``, ``max_decimal_places``,
``max_whole_digits``
4 つのオプション引数を取ります:
.. attribute:: DecimalField.max_value
.. attribute:: DecimalField.min_value
それぞれ、フィールドの値のとり得る最大/最小値です。
.. attribute:: DecimalField.max_digits
最大の桁数 (先頭のゼロ詰め桁を除いた上での小数点前後の桁数の合計) です。
.. attribute:: DecimalField.decimal_places
``decimal_places`` は小数部の最大桁数です。
``EmailField``
~~~~~~~~~~~~~~
.. class:: EmailField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``''`` (空文字列)
* Python データへの正規化: Unicode 文字列オブジェクト
* やや複雑な正規表現を使って、入力値が有効なメールアドレスであるか検証
します。
* エラーメッセージのキー: ``required``, ``invalid``
オプションの引数として、 ``max_length`` と ``min_length`` の二つをとれます。
これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たしてい
るか検証します。
``FileField``
~~~~~~~~~~~~~
.. versionadded:: 1.0
.. class:: FileField(**kwargs)
* デフォルトのウィジェット: ``FileInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: ファイルコンテンツとファイル名を一つのオブジェ
クトとしてラップする ``UploadedFile`` オブジェクト。
* フォームに結びつけられているファイルデータが空でないか検証します。
* エラーメッセージのキー: ``required``, ``invalid``, ``missing``, ``empty``
``UploadedFile`` オブジェクトの詳細は
:ref:`ファイルアップロードのドキュメント ` を参照して
ください。
``FileField`` をフォームで使う場合、
:ref:`フォームにファイルデータを束縛する ` のを忘れ
ないようにしてください。
``FilePathField``
~~~~~~~~~~~~~~~~~
.. versionadded:: 1.0
.. class:: FilePathField(**kwargs)
* デフォルトのウィジェット: ``Select``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: unicode オブジェクト
* 入力値が選択肢内にある値かどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid_choice``
このフィールドを使うと、あるディレクトリの下にあるファイルを選択できます。
フィールドは以下の 3 つの引数を追加で取り、 ``path`` のみ必須の引数です:
.. attribute:: FilePathField.path
ファイルの一覧を表示したいディレクトリの絶対パスです。実在するディレク
トリを指定せねばなりません。
.. attribute:: FilePathField.recursive
``False`` (デフォルト値) の場合、 ``path`` の直下にあるファイルのみを選
択肢として表示します。 ``True`` にすると、 ``path`` 以下の全てのファイ
ルを再帰的に探索して選択肢にします。
.. attribute:: FilePathField.match
正規表現です。この引数を指定すると、正規表現にマッチしたファイル名だけ
を選択肢として表示します。
``FloatField``
~~~~~~~~~~~~~~
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python の float 型
* 指定された値が浮動小数点数を表すかどうか検証します。 Python の
``float()`` 関数と同じく、前後に空白があってもかまいません。
* エラーメッセージのキー: ``required``, ``invalid``, ``max_value``,
``min_value``
オプションの引数として、 ``max_value`` および ``min_value`` をとります。こ
れらの値は、入力値のとりえる値域の調整に使われます。
``ImageField``
~~~~~~~~~~~~~~
.. versionadded:: 1.0
.. class:: ImageField(**kwargs)
* デフォルトのウィジェット: ``FileInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: ファイルコンテンツとファイル名を一つのオブジェ
クトとしてラップする ``UploadedFile`` オブジェクト。
* 空でないファイルデータがフォームに結びつけられていて、かつその内容が
PIL で扱えるファイル形式であるか検証します。
* エラーメッセージのキー: ``required``, ``invalid``, ``missing``, ``empty``,
``invalid_image``
ImageField を使いたい場合、 `Python Imaging Library`_ をインストールしてお
かねばなりません。
``ImageField`` をフォームで使う場合、
:ref:`フォームにファイルデータを束縛する `
のを忘れないようにしてください。
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
``IntegerField``
~~~~~~~~~~~~~~~~
.. class:: IntegerField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python 整数型または長整数型
* 入力値が整数であるか検証します。 Python の ``int()`` 関数と同様、先頭
や末尾に空白があってもかまいません。
* エラーメッセージのキー: ``required``, ``invalid``, ``max_value``,
``min_value``
以下の二つの引数をとります:
.. attribute:: IntegerField.max_value
.. attribute:: IntegerField.min_value
フィールドのとり得る値の最大値および最小値です。
``IPAddressField``
~~~~~~~~~~~~~~~~~~
.. class:: IPAddressField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``''`` (空の文字列)
* Python データへの正規化: Unicode オブジェクト
* 正規表現を使って、値が正しい IPv4 アドレス形式であるか検証します。
* エラーメッセージのキー: ``required``, ``invalid``
``MultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~
.. class:: MultipleChoiceField(**kwargs)
* デフォルトのウィジェット: ``SelectMultiple``
* 空のフォームデータに対する値: ``[]`` (空のリスト)
* Python データへの正規化: Unicode 文字列オブジェクトのリスト
* 入力値のリスト中の全ての値が選択肢内の値であるかどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid_choice``, ``invalid_list``
追加の引数として ``choices`` をとります。 ``choices`` の意味は
``ChoiceField`` の ``choices`` と同じです。
``NullBooleanField``
~~~~~~~~~~~~~~~~~~~~
.. class:: NullBooleanField(**kwargs)
* デフォルトのウィジェット: ``NullBooleanSelect``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: ``True``, ``False`` または ``None`` 。
* バリデーションを実行しません (``VaridationError`` を送出しません)。
``RegexField``
~~~~~~~~~~~~~~
.. class:: RegexField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``''`` (空文字列)
* Python データへの正規化: Unicode 文字列オブジェクト
* 入力値が特定の正規表現にマッチするかどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid``
追加の引数を一つ持っています:
.. attribute:: RegexField.regex
``regex`` は正規表現を表す文字列またはコンパイル済みの正規表現オブジェ
クトです。
``CharField`` と同様、 ``max_length`` および ``min_length`` をとります。
以前のバージョンとの互換性のため、オプション引数 ``error_message`` も指定で
きるようになっています。エラーメッセージを指定したければ、
``error_messages`` を使って、 ``'invalid'`` をキーにしたメッセージを指定す
るよう薦めます。
``TimeField``
~~~~~~~~~~~~~
.. class:: TimeField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``None``
* Python データへの正規化: Python ``datetime.time`` オブジェクト
* 入力値が ``datetime.time`` オブジェクトまたは特定の日付フォーマットの
形式に従っているか検証します。
* エラーメッセージのキー: ``required``, ``invalid``
オプションの引数を一つ持っています:
.. attribute:: TimeField.input_formats
文字列から有効な ``datetime.time`` オブジェクトへの変換を試みるために使
われるフォーマット文字列からなるリストです。
``input_formats`` を指定しない場合、デフォルトで以下の入力フォーマットをサ
ポートします::
'%H:%M:%S', # '14:30:59'
'%H:%M', # '14:30'
``URLField``
~~~~~~~~~~~~
.. class:: URLField(**kwargs)
* デフォルトのウィジェット: ``TextInput``
* 空のフォームデータに対する値: ``''`` (空文字列)
* Python データへの正規化: Unicode 文字列オブジェクト
* 入力値が有効な URL であるかどうか検証します。
* エラーメッセージのキー: ``required``, ``invalid``, ``invalid_link``
以下のオプションの引数をとります:
.. attribute:: URLField.max_length
.. attribute:: URLField.min_length
``CharField.max_length`` や ``CharField.min_length`` と同じです。
.. attribute:: URLField.verify_exists
``True`` にすると、バリデータが指定された URLをロードできるか調べ、該当
ページの HTTP レスポンスが 404 のときに ``ValidationError`` を送出しま
す。デフォルト値は ``False`` です。
.. attribute:: URLField.validator_user_agent
URL が存在するか確かめるときに使うユーザエージェントを表す文字列です。
デフォルト値は ``URL_VALIDATOR_USER_AGENT`` 設定の値です。
やや複雑な組み込みフィールドクラス
----------------------------------
以下のフィールドはまだドキュメント化されていません。
.. class:: ComboField(**kwargs)
.. class:: MultiValueField(**kwargs)
.. class:: SplitDateTimeField(**kwargs)
* Default widget: ``SplitDateTimeWidget``
* Empty value: ``None``
* Normalizes to: A Python ``datetime.datetime`` object.
* Validates that the given value is a ``datetime.datetime`` or string
formatted in a particular datetime format.
* Error message keys: ``required``, ``invalid``
Takes two optional arguments:
.. attribute:: 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.
.. attribute:: 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.
.. versionchanged:: 1.1
The ``SplitDateTimeField`` previously used two ``TextInput`` widgets by
default. The ``input_date_formats`` and ``input_time_formats`` arguments
are also new.
リレーションを扱うフィールド
---------------------------------
モデル間のリレーションを表現するために、二つのフィールドが提供されています。
これらのフィールドは、選択肢を ``QuerySet`` から取り出します:
.. class:: ModelChoiceField(**kwargs)
.. class:: ModelMultipleChoiceField(**kwargs)
これらのフィールドは、入力に応じて、フォームの ``cleaned_data`` 辞書内にモ
デルオブジェクトをいれます。どちらのフィールド型にも必須の引数が一つありま
す:
.. attribute:: 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
.. attribute:: ModelChoiceField.empty_label
By default the ``