フォームフィールド

revision-up-to:11321 (1.1) unfinished
class 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

Django 1.0 で新たに登場しました: リリースノートを参照してください
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
Django 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 つあります:

CharField.max_length
CharField.min_length

これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たし ているか検証します。

ChoiceField

class ChoiceField(**kwargs)
  • デフォルトのウィジェット: Select
  • 空のフォームデータに対する値: '' (空文字列)
  • Python データへの正規化: Unicode 文字列オブジェクト
  • 入力値が選択肢内にある値かどうか検証します。
  • エラーメッセージのキー: required, invalid_choice

必須の引数を一つとります:

ChoiceField.choices

イテレーション可能オブジェクト (たとえばリストやタプルなど) で、各要素 はフィールドの選択肢として使える 2 要素のタプルでなければなりません。

TypedChoiceField

class TypedChoiceField(**kwargs)

ChoiceField に似ていますが、 TypedChoiceField には coerce 引数があります。

  • デフォルトのウィジェット: Select
  • 空のフォームデータに対する値: empty_value の指定値
  • Python データへの正規化: coerce 引数の戻り値
  • 入力値が選択肢内にある値かどうか検証します。
  • エラーメッセージのキー: required, invalid_choice

以下の追加の引数をとります:

TypedChoiceField.coerce

引数を一つとり、型強制した値を返す関数を指定します。例えば、組み込みの int, float, bool などです。等値関数がデフォルト値として設定 されています。

TypedChoiceField.empty_value

「空の入力」を示すのに使う値です。デフォルト値は空文字列です。 None も良く使う値です。

DateField

class DateField(**kwargs)
  • デフォルトのウィジェット: DateInput
  • 空のフォームデータに対する値: None
  • Python データへの正規化: Python datetime.date オブジェクト
  • 入力値が datetime.datedatetime.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'
Django 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.datedatetime.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'
Django 1.0 で変更されました: DateTimeField はデフォルトで TextInput を使っていましたが、変更 されました。

DecimalField

Django 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 つのオプション引数を取ります:

DecimalField.max_value
DecimalField.min_value

それぞれ、フィールドの値のとり得る最大/最小値です。

DecimalField.max_digits

最大の桁数 (先頭のゼロ詰め桁を除いた上での小数点前後の桁数の合計) です。

DecimalField.decimal_places

decimal_places は小数部の最大桁数です。

EmailField

class EmailField(**kwargs)
  • デフォルトのウィジェット: TextInput
  • 空のフォームデータに対する値: '' (空文字列)
  • Python データへの正規化: Unicode 文字列オブジェクト
  • やや複雑な正規表現を使って、入力値が有効なメールアドレスであるか検証 します。
  • エラーメッセージのキー: required, invalid

オプションの引数として、 max_lengthmin_length の二つをとれます。 これらの引数を指定すると、文字列長が最大、あるいは最小値の条件を満たしてい るか検証します。

FileField

Django 1.0 で新たに登場しました: リリースノートを参照してください
class FileField(**kwargs)
  • デフォルトのウィジェット: FileInput
  • 空のフォームデータに対する値: None
  • Python データへの正規化: ファイルコンテンツとファイル名を一つのオブジェ クトとしてラップする UploadedFile オブジェクト。
  • フォームに結びつけられているファイルデータが空でないか検証します。
  • エラーメッセージのキー: required, invalid, missing, empty

UploadedFile オブジェクトの詳細は ファイルアップロードのドキュメント を参照して ください。

FileField をフォームで使う場合、 フォームにファイルデータを束縛する のを忘れ ないようにしてください。

FilePathField

Django 1.0 で新たに登場しました: リリースノートを参照してください
class FilePathField(**kwargs)
  • デフォルトのウィジェット: Select
  • 空のフォームデータに対する値: None
  • Python データへの正規化: unicode オブジェクト
  • 入力値が選択肢内にある値かどうか検証します。
  • エラーメッセージのキー: 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

Django 1.0 で新たに登場しました: リリースノートを参照してください
class ImageField(**kwargs)
  • デフォルトのウィジェット: FileInput
  • 空のフォームデータに対する値: None
  • Python データへの正規化: ファイルコンテンツとファイル名を一つのオブジェ クトとしてラップする UploadedFile オブジェクト。
  • 空でないファイルデータがフォームに結びつけられていて、かつその内容が PIL で扱えるファイル形式であるか検証します。
  • エラーメッセージのキー: required, invalid, missing, empty, invalid_image

ImageField を使いたい場合、 Python Imaging Library をインストールしてお かねばなりません。

ImageField をフォームで使う場合、 フォームにファイルデータを束縛する のを忘れないようにしてください。

IntegerField

class IntegerField(**kwargs)
  • デフォルトのウィジェット: TextInput
  • 空のフォームデータに対する値: None
  • Python データへの正規化: Python 整数型または長整数型
  • 入力値が整数であるか検証します。 Python の int() 関数と同様、先頭 や末尾に空白があってもかまいません。
  • エラーメッセージのキー: required, invalid, max_value, min_value

以下の二つの引数をとります:

IntegerField.max_value
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 の意味は ChoiceFieldchoices と同じです。

NullBooleanField

class NullBooleanField(**kwargs)
  • デフォルトのウィジェット: NullBooleanSelect
  • 空のフォームデータに対する値: None
  • Python データへの正規化: True, False または None
  • バリデーションを実行しません (VaridationError を送出しません)。

RegexField

class RegexField(**kwargs)
  • デフォルトのウィジェット: TextInput
  • 空のフォームデータに対する値: '' (空文字列)
  • Python データへの正規化: Unicode 文字列オブジェクト
  • 入力値が特定の正規表現にマッチするかどうか検証します。
  • エラーメッセージのキー: required, invalid

追加の引数を一つ持っています:

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

オプションの引数を一つ持っています:

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

以下のオプションの引数をとります:

URLField.max_length
URLField.min_length

CharField.max_lengthCharField.min_length と同じです。

URLField.verify_exists

True にすると、バリデータが指定された URLをロードできるか調べ、該当 ページの HTTP レスポンスが 404 のときに ValidationError を送出しま す。デフォルト値は False です。

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:

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.

Django 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 辞書内にモ デルオブジェクトをいれます。どちらのフィールド型にも必須の引数が一つありま す:

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) を持たせることだけです。