フォームフィールド

class Field(**kwargs)

Formクラスを作成する場合、最も重要な部分はフォームのフィールドを定義することです。各フィールドには、他のいくつかのフックとともに、カスタム検証ロジックがあります。

Field.clean(value)

Fieldクラスを使用する主な方法は、Formクラスですが、それらをインスタンス化して直接使用することで、それらがどのように機能するかをよりよく理解することもできます。各Fieldインスタンスにはclean()メソッドがあります。このメソッドは、単一の引数を取り、django.core.exceptions.ValidationError例外を発生させるか、クリーンな値を返します。

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('[email protected]')
'[email protected]'
>>> f.clean('invalid email address')
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

コアフィールド引数

各Fieldクラスコンストラクターは、少なくともこれらの引数を取ります。一部のFieldクラスは、追加のフィールド固有の引数を取りますが、常にを受け入れる必要があります。

required

Field.required

デフォルトでは、各Fieldクラスは値が必須であると想定しているため、空の値（Noneまたは空の文字列（""））を渡すと、 [ X156X]は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'

Fieldにrequired=Falseがあり、clean()に空の値を渡すと、clean()は正規化の空の値を返すのではなく返します。 ValidationError。 CharFieldの場合、これは empty_value を返しますが、デフォルトでは空の文字列になります。他のFieldクラスの場合、Noneの場合があります。（これはフィールドごとに異なります。）

必須のフォームフィールドのウィジェットには、required HTML属性があります。 Form.use_required_attribute 属性をFalseに設定して、無効にします。 required属性は、フォームセットを追加および削除するときにブラウザーの検証が正しくない可能性があるため、フォームセットのフォームには含まれていません。

label

Field.label

label引数を使用すると、このフィールドに「人に優しい」ラベルを指定できます。 FieldがFormに表示されている場合に使用します。

上記の「フォームをHTMLとして出力する」で説明したように、Fieldのデフォルトのラベルは、すべてのアンダースコアをスペースに変換し、最初の文字を大文字にすることによって、フィールド名から生成されます。デフォルトの動作で適切なラベルが得られない場合は、labelを指定してください。

これは、2つのフィールドにlabelを実装する完全な例Formです。出力を簡略化するために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>

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>

呼び出し可能オブジェクトは、定義されているときではなく、バインドされていないフォームが表示されているときにのみ評価されます。

help_text

Field.help_text

help_text引数を使用すると、このFieldの説明テキストを指定できます。 help_textを指定すると、Fieldが便利なFormメソッドの1つ（as_ul()）。

モデルフィールドの help_text と同様に、この値は自動生成されたフォームでHTMLエスケープされません。

これは、2つのフィールドにhelp_textを実装する完全な例Formです。出力を簡略化するためにauto_id=Falseを指定しました。

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

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

以下の組み込みフィールドクラスセクションでは、各Fieldが使用するエラーメッセージキーを定義します。

validators

Field.validators

validators引数を使用すると、このフィールドの検証関数のリストを提供できます。

詳細については、バリデーターのドキュメントを参照してください。

localize

Field.localize

localize引数は、フォームデータ入力とレンダリングされた出力のローカリゼーションを可能にします。

詳細については、形式のローカリゼーションのドキュメントを参照してください。

disabled

Field.disabled

disabledブール引数をTrueに設定すると、disabled HTML属性を使用してフォームフィールドが無効になり、ユーザーが編集できないようになります。ユーザーがサーバーに送信されたフィールドの値を改ざんした場合でも、フォームの初期データの値を優先して無視されます。

フィールドデータが変更されたかどうかを確認する

has_changed()

Field.has_changed()

has_changed()メソッドは、フィールド値が初期値から変更されたかどうかを判別するために使用されます。 TrueまたはFalseを返します。

詳細については、 Form.has_changed（）のドキュメントを参照してください。

組み込みのFieldクラス

当然、formsライブラリには、一般的な検証ニーズを表すFieldクラスのセットが付属しています。このセクションでは、各組み込みフィールドについて説明します。

フィールドごとに、widgetを指定しない場合に使用されるデフォルトのウィジェットについて説明します。空の値を指定したときに返される値も指定します（その意味を理解するには、上記のrequiredのセクションを参照してください）。

BooleanField

class BooleanField(**kwargs)

デフォルトのウィジェット： CheckboxInput
空の値：False
正規化：Python TrueまたはFalse値。
値がTrueであることを検証します（例：フィールドにrequired=Trueがある場合、チェックボックスがオンになります。
エラーメッセージキー：required

ノート

すべてのFieldサブクラスにはデフォルトでrequired=Trueがあるため、ここでの検証条件は重要です。 TrueまたはFalseのいずれかであるブール値をフォームに含める場合（例：チェックボックスがオンまたはオフの場合）、BooleanFieldを作成するときに、required=Falseを忘れずに渡す必要があります。

CharField

class CharField(**kwargs)

デフォルトのウィジェット： TextInput
空の値： empty_value として指定したもの。
正規化：文字列。
max_lengthおよびmin_lengthが指定されている場合は、 MaxLengthValidator および MinLengthValidator を使用します。それ以外の場合、すべての入力が有効です。
エラーメッセージキー：required、max_length、min_length

検証用に4つのオプションの引数があります。

max_length

min_length: 指定されている場合、これらの引数は、文字列が最大で、または少なくとも指定された長さであることを保証します。

strip: True（デフォルト）の場合、値の先頭と末尾の空白が削除されます。

empty_value: 「空」を表すために使用する値。デフォルトは空の文字列です。

ChoiceField

class ChoiceField(**kwargs)

デフォルトのウィジェット：選択
空の値：（空の文字列）
正規化：文字列。
指定された値が選択肢のリストに存在することを検証します。
エラーメッセージキー：required、invalid_choice

invalid_choiceエラーメッセージには、%(value)sが含まれている場合があります。これは、選択した選択肢に置き換えられます。

1つの追加の引数を取ります：

choices: このフィールドの選択肢として使用する2タプルの iterable 、 enumeration の選択肢、またはそのようなiterableを返すcallableのいずれか。この引数は、モデルフィールドのchoices引数と同じ形式を受け入れます。詳細については、選択肢に関するモデルフィールドリファレンスドキュメントを参照してください。引数が呼び出し可能である場合、レンダリング中だけでなく、フィールドのフォームが初期化されるたびに評価されます。デフォルトは空のリストです。

TypedChoiceField

class TypedChoiceField(**kwargs)

ChoiceField と同じですが、 TypedChoiceField が coerce と empty_value の2つの追加引数を取る点が異なります。

デフォルトのウィジェット：選択
空の値： empty_value として指定したもの。
次のように正規化します。 coerce 引数によって提供されるタイプの値。
指定された値が選択肢のリストに存在し、強制できることを検証します。
エラーメッセージキー：required、invalid_choice

追加の引数を取ります：

coerce: 1つの引数を取り、強制値を返す関数。例としては、組み込みのint、float、boolなどのタイプがあります。デフォルトは恒等関数です。強制は入力検証後に発生するため、choicesに存在しない値に強制することが可能であることに注意してください。

empty_value: 「空」を表すために使用する値。デフォルトは空の文字列です。 Noneはここでのもう1つの一般的な選択です。この値は、coerce引数で指定された関数によって強制されないことに注意してください。したがって、それに応じて選択してください。

DateField

class DateField(**kwargs)

デフォルトのウィジェット： DateInput
空の値：None
正規化：Python datetime.dateオブジェクト。
指定された値がdatetime.date、datetime.datetime、または特定の日付形式でフォーマットされた文字列であることを検証します。
エラーメッセージキー：required、invalid

オプションの引数を1つ取ります。

input_formats: 文字列を有効なdatetime.dateオブジェクトに変換するために使用される形式のリスト。

input_formats引数が指定されていない場合、：setting： `USE_L10N` がFalseの場合、デフォルトの入力形式は：setting：` DATE_INPUT_FORMATS` から取得されます。 ]、またはローカリゼーションが有効になっている場合は、アクティブなロケール形式DATE_INPUT_FORMATSキーから。フォーマットのローカリゼーションも参照してください。

DateTimeField

class DateTimeField(**kwargs)

デフォルトのウィジェット： DateTimeInput
空の値：None
正規化：Python datetime.datetimeオブジェクト。
指定された値がdatetime.datetime、datetime.date、または特定の日時形式でフォーマットされた文字列であることを検証します。
エラーメッセージキー：required、invalid

オプションの引数を1つ取ります。

input_formats: ISO 8601形式に加えて、文字列を有効なdatetime.datetimeオブジェクトに変換するために使用される形式のリスト。

このフィールドは、 parse_datetime（）によって認識されるISO8601形式の日付または同様の文字列を常に受け入れます。いくつかの例は次のとおりです。

* '2006-10-25 14:30:59'
* '2006-10-25T14:30:59'
* '2006-10-25 14:30'
* '2006-10-25T14:30'
* '2006-10-25T14:30Z'
* '2006-10-25T14:30+02:00'
* '2006-10-25'

input_formats引数が指定されていない場合、デフォルトの入力形式は：setting： `DATETIME_INPUT_FORMATS` および：setting：` DATE_INPUT_FORMATS` if ：settingから取得されます。： `USE_L10N` はFalseであるか、ローカリゼーションが有効になっている場合はアクティブなロケール形式DATETIME_INPUT_FORMATSおよびDATE_INPUT_FORMATSキーからです。フォーマットのローカリゼーションも参照してください。

バージョン3.1で変更： ISO 8601日付文字列解析（オプションのタイムゾーンを含む）のサポートが追加されました。

デフォルトのinput_formatsのDATE_INPUT_FORMATSでのフォールバックが追加されました。

DecimalField

class DecimalField(**kwargs)

デフォルトウィジェット： Field.localize がFalseの場合は NumberInput 、それ以外の場合は TextInput 。
空の値：None
正規化：Python decimal。
指定された値が10進数であることを検証します。 max_valueおよびmin_valueが指定されている場合は、 MaxValueValidator および MinValueValidator を使用します。先頭と末尾の空白は無視されます。
エラーメッセージキー：required、invalid、max_value、min_value、max_digits、max_decimal_places、 [ X90X]

max_valueおよびmin_valueエラーメッセージには%(limit_value)sが含まれている場合があり、適切な制限で置き換えられます。同様に、max_digits、max_decimal_places、およびmax_whole_digitsのエラーメッセージには、%(max)sが含まれている場合があります。

4つのオプションの引数を取ります。

max_value

min_value: これらは、フィールドで許可される値の範囲を制御し、decimal.Decimal値として指定する必要があります。

max_digits: 値で許可される最大桁数（小数点の前の桁と小数点の後の桁、先行ゼロは削除されます）。

decimal_places: 許可される小数点以下の最大桁数。

DurationField

class DurationField(**kwargs)

デフォルトのウィジェット： TextInput
空の値：None
正規化：Python timedelta。
指定された値がtimedeltaに変換できる文字列であることを検証します。値はdatetime.timedelta.minとdatetime.timedelta.maxの間でなければなりません。
エラーメッセージキー：required、invalid、overflow。

parse_duration（）が理解できるすべての形式を受け入れます。

EmailField

class EmailField(**kwargs)

デフォルトのウィジェット： EmailInput
空の値：empty_valueとして指定したもの。
正規化：文字列。
EmailValidator を使用して、適度に複雑な正規表現を使用して、指定された値が有効な電子メールアドレスであることを検証します。
エラーメッセージキー：required、invalid

CharField の場合と同じように機能する、3つのオプションの引数max_length、min_length、およびempty_valueがあります。

FileField

class FileField(**kwargs)

デフォルトのウィジェット： ClearableFileInput
空の値：None
正規化：ファイルの内容とファイル名を単一のオブジェクトにラップするUploadedFileオブジェクト。
空でないファイルデータがフォームにバインドされていることを検証できます。
エラーメッセージキー：required、invalid、missing、empty、max_length

検証用の2つのオプションの引数、max_lengthとallow_empty_fileがあります。提供されている場合、これらはファイル名が最大で指定された長さであることを保証し、ファイルの内容が空であっても検証が成功することを保証します。

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

フォームでFileFieldを使用する場合は、ファイルデータをフォームにバインドすることも忘れないでください。

max_lengthエラーは、ファイル名の長さを示します。そのキーのエラーメッセージで、%(max)dはファイル名の最大長に置き換えられ、%(length)dは現在のファイル名の長さに置き換えられます。

FilePathField

class FilePathField(**kwargs)

デフォルトのウィジェット：選択
空の値：（空の文字列）
正規化：文字列。
選択した選択肢が選択肢のリストに存在することを検証します。
エラーメッセージキー：required、invalid_choice

このフィールドでは、特定のディレクトリ内のファイルから選択できます。 5つの追加の引数が必要です。 pathのみが必要です。

path: 内容を一覧表示するディレクトリへの絶対パス。このディレクトリが存在する必要があります。

recursive: False（デフォルト）の場合、pathの直接コンテンツのみが選択肢として提供されます。 Trueの場合、ディレクトリは再帰的に降順になり、すべての子孫が選択肢として一覧表示されます。

match: 正規表現パターン。この式に一致する名前のファイルのみが選択肢として許可されます。

allow_files: オプション。 TrueまたはFalseのいずれか。デフォルトはTrueです。指定した場所にあるファイルを含めるかどうかを指定します。これまたは allow_folders はTrueである必要があります。

allow_folders: オプション。 TrueまたはFalseのいずれか。デフォルトはFalseです。指定した場所のフォルダーを含めるかどうかを指定します。これまたは allow_files はTrueである必要があります。

FloatField

class FloatField(**kwargs)

デフォルトウィジェット： Field.localize がFalseの場合は NumberInput 、それ以外の場合は TextInput 。
空の値：None
正規化：Python浮動小数点。
指定された値がfloatであることを検証します。 max_valueおよびmin_valueが指定されている場合は、 MaxValueValidator および MinValueValidator を使用します。 Pythonのfloat()関数のように、先頭と末尾の空白が許可されます。
エラーメッセージキー：required、invalid、max_value、min_value

検証には、max_valueとmin_valueの2つのオプションの引数を取ります。これらは、フィールドで許可される値の範囲を制御します。

ImageField

class ImageField(**kwargs)

デフォルトのウィジェット： ClearableFileInput
空の値：None
正規化：ファイルの内容とファイル名を単一のオブジェクトにラップするUploadedFileオブジェクト。
ファイルデータがフォームにバインドされていることを検証します。また、 FileExtensionValidator を使用して、ファイル拡張子がPillowでサポートされていることを検証します。
エラーメッセージキー：required、invalid、missing、empty、invalid_image

ImageFieldを使用するには、使用する画像形式をサポートする Pillow がインストールされている必要があります。画像のアップロード時にcorrupt imageエラーが発生した場合は、通常、Pillowがその形式を理解していないことを意味します。これを修正するには、適切なライブラリをインストールして、Pillowを再インストールします。

フォームでImageFieldを使用する場合は、ファイルデータをフォームにバインドすることも忘れないでください。

フィールドがクリーンアップおよび検証された後、UploadedFileオブジェクトには、ファイルが有効なイメージであるかどうかを確認するために使用されるピロー Image インスタンスを含む追加のimage属性があります。 Pillowは、画像を検証した後、基になるファイル記述子を閉じるため、format、height、widthなどの非画像データ属性を使用できますが、 getdata()やgetpixel()などの基になる画像データは、ファイルを再度開かないと使用できません。例えば：

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
...     img = forms.ImageField()
>>> file_data = {'img': SimpleUploadedFile('test.png', <file data>)}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data['img']
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>

さらに、UploadedFile.content_typeは、Pillowが判断できる場合は画像のコンテンツタイプで更新され、それ以外の場合はNoneに設定されます。

IntegerField

class IntegerField(**kwargs)

デフォルトウィジェット： Field.localize がFalseの場合は NumberInput 、それ以外の場合は TextInput 。
空の値：None
正規化：Python整数。
指定された値が整数であることを検証します。 max_valueおよびmin_valueが指定されている場合は、 MaxValueValidator および MinValueValidator を使用します。 Pythonのint()関数のように、先頭と末尾の空白が許可されます。
エラーメッセージキー：required、invalid、max_value、min_value

max_valueおよびmin_valueエラーメッセージには%(limit_value)sが含まれている場合があり、適切な制限で置き換えられます。

検証のために2つのオプションの引数を取ります。

max_value

min_value: これらは、フィールドで許可される値の範囲を制御します。

JSONField

class JSONField(encoder=None, decoder=None, **kwargs)

バージョン3.1の新機能。

JSONField のJSONエンコードされたデータを受け入れるフィールド。

デフォルトのウィジェット： Textarea
空の値：None
正規化： JSONField.decoder に応じて、JSON値のPython表現（通常はdict、list、またはNoneとして）。
指定された値が有効なJSONであることを検証します。
エラーメッセージキー：required、invalid

2つのオプションの引数を取ります。

encoder

標準のJSONシリアライザーでサポートされていないデータ型をシリアル化するためのjson.JSONEncoderサブクラス（例： datetime.datetimeまたはUUID）。たとえば、 DjangoJSONEncoder クラスを使用できます。

デフォルトはjson.JSONEncoderです。

decoder

入力を逆シリアル化するためのjson.JSONDecoderサブクラス。デシリアライズでは、入力タイプを特定できないという事実を考慮する必要がある場合があります。たとえば、実際にはdatetimeに選択されたのと同じ形式の文字列であるdatetimeを返すリスクがあります。

decoderを使用して、入力を検証できます。デシリアライズ中にjson.JSONDecodeErrorが発生すると、ValidationErrorが発生します。

デフォルトはjson.JSONDecoderです。

ノート

ModelForm を使用する場合、 JSONField のencoderおよびdecoderが使用されます。

ユーザーフレンドリーなフォーム

JSONFieldは、ほとんどの場合、特にユーザーフレンドリーではありません。ただし、サーバーに送信するためにクライアント側ウィジェットからデータをフォーマットするのに便利な方法です。

GenericIPAddressField

class GenericIPAddressField(**kwargs)

IPv4またはIPv6アドレスのいずれかを含むフィールド。

デフォルトのウィジェット： TextInput
空の値：（空の文字列）
正規化：文字列。 IPv6アドレスは、以下のように正規化されています。
指定された値が有効なIPアドレスであることを検証します。
エラーメッセージキー：required、invalid

IPv6アドレスの正規化は、 RFC 4291＃section-2.2 セクション2.2に従います。これには、::ffff:192.0.2.0などのセクションの段落3で提案されているIPv4形式の使用も含まれます。たとえば、2001:0::0:01は2001::1に正規化され、::ffff:0a0a:0a0aは::ffff:10.10.10.10に正規化されます。すべての文字は小文字に変換されます。

2つのオプションの引数を取ります。

protocol: 有効な入力を指定されたプロトコルに制限します。受け入れられる値は、both（デフォルト）、IPv4、またはIPv6です。マッチングでは大文字と小文字は区別されません。

unpack_ipv4: ::ffff:192.0.2.1のようなIPv4マップアドレスを解凍します。このオプションを有効にすると、そのアドレスは192.0.2.1に解凍されます。デフォルトは無効です。 protocolが'both'に設定されている場合にのみ使用できます。

MultipleChoiceField

class MultipleChoiceField(**kwargs)

デフォルトのウィジェット： SelectMultiple
空の値：[]（空のリスト）
正規化：文字列のリスト。
指定された値のリスト内のすべての値が選択肢のリストに存在することを検証します。
エラーメッセージキー：required、invalid_choice、invalid_list

invalid_choiceエラーメッセージには、%(value)sが含まれている場合があります。これは、選択した選択肢に置き換えられます。

ChoiceField と同様に、1つの追加の必須引数choicesを取ります。

TypedMultipleChoiceField

class TypedMultipleChoiceField(**kwargs)

MultipleChoiceField と同じですが、 TypedMultipleChoiceField がcoerceとempty_valueの2つの追加引数を取る点が異なります。

デフォルトのウィジェット： SelectMultiple
空の値：empty_valueとして指定したもの
正規化：coerce引数によって提供されるタイプの値のリスト。
指定された値が選択肢のリストに存在し、強制できることを検証します。
エラーメッセージキー：required、invalid_choice

invalid_choiceエラーメッセージには、%(value)sが含まれている場合があります。これは、選択した選択肢に置き換えられます。

TypedChoiceField と同様に、coerceとempty_valueの2つの追加引数を取ります。

NullBooleanField

class NullBooleanField(**kwargs)

デフォルトのウィジェット： NullBooleanSelect
空の値：None
正規化：Python True、False、またはNoneの値。
何も検証しません（つまり、ValidationErrorを発生させることはありません）。

NullBooleanFieldは、ウィジェットchoicesを提供することにより、 Select や RadioSelect などのウィジェットで使用できます。

NullBooleanField(
    widget=Select(
        choices=[
            ('', 'Unknown'),
            (True, 'Yes'),
            (False, 'No'),
        ]
    )
)

RegexField

class RegexField(**kwargs)

デフォルトのウィジェット： TextInput
空の値：empty_valueとして指定したもの。
正規化：文字列。
RegexValidator を使用して、指定された値が特定の正規表現に一致することを検証します。
エラーメッセージキー：required、invalid

1つの必須の引数を取ります：

regex: 文字列またはコンパイルされた正規表現オブジェクトとして指定された正規表現。

また、max_length、min_length、strip、およびempty_valueも使用できます。これらは、 CharField の場合と同じように機能します。

strip: デフォルトはFalseです。有効にすると、正規表現の検証の前にストリッピングが適用されます。

SlugField

class SlugField(**kwargs)

デフォルトのウィジェット： TextInput
空の値： empty_value として指定したもの。
正規化：文字列。
validate_slug または validate_unicode_slug を使用して、指定された値に文字、数字、アンダースコア、およびハイフンのみが含まれていることを検証します。
エラーメッセージ：required、invalid

このフィールドは、モデル SlugField をフォームで表すために使用することを目的としています。

2つのオプションのパラメータを取ります：

allow_unicode: ASCII文字に加えてUnicode文字を受け入れるようにフィールドに指示するブール値。デフォルトはFalseです。

empty_value: 「空」を表すために使用する値。デフォルトは空の文字列です。

TimeField

class TimeField(**kwargs)

デフォルトのウィジェット： TimeInput
空の値：None
正規化：Python datetime.timeオブジェクト。
指定された値がdatetime.timeまたは特定の時間形式でフォーマットされた文字列であることを検証します。
エラーメッセージキー：required、invalid

オプションの引数を1つ取ります。

input_formats: 文字列を有効なdatetime.timeオブジェクトに変換するために使用される形式のリスト。

input_formats引数が指定されていない場合、：setting： `USE_L10N` がFalseの場合、デフォルトの入力形式は：setting：` TIME_INPUT_FORMATS` から取得されます。 ]、またはローカリゼーションが有効になっている場合は、アクティブなロケール形式TIME_INPUT_FORMATSキーから。フォーマットのローカリゼーションも参照してください。

URLField

class URLField(**kwargs)

デフォルトのウィジェット： URLInput
空の値：empty_valueとして指定したもの。
正規化：文字列。
URLValidator を使用して、指定された値が有効なURLであることを検証します。
エラーメッセージキー：required、invalid

CharField の場合と同じように機能する、3つのオプションの引数max_length、min_length、およびempty_valueがあります。

UUIDField

class UUIDField(**kwargs)

デフォルトのウィジェット： TextInput
空の値：None
正規化：UUIDオブジェクト。
エラーメッセージキー：required、invalid

このフィールドは、UUIDコンストラクターのhex引数として受け入れられるすべての文字列形式を受け入れます。

やや複雑なビルトインFieldクラス

ComboField

class ComboField(**kwargs)

デフォルトのウィジェット： TextInput
空の値：（空の文字列）
正規化：文字列。
ComboFieldへの引数として指定された各フィールドに対して指定された値を検証します。
エラーメッセージキー：required、invalid

必要な引数を1つ追加します。

fields

フィールドの値を検証するために使用する必要があるフィールドのリスト（提供された順序で）。

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('[email protected]')
'[email protected]'
>>> f.clean('[email protected]')
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

MultiValueField

class MultiValueField(fields=(), **kwargs)

デフォルトのウィジェット： TextInput
空の値：（空の文字列）
正規化：サブクラスのcompressメソッドによって返される型。
MultiValueFieldへの引数として指定された各フィールドに対して指定された値を検証します。
エラーメッセージキー：required、invalid、incomplete

一緒に単一の値を生成する複数のフィールドのロジックを集約します。

このフィールドは抽象的であり、サブクラス化する必要があります。単一値フィールドとは対照的に、 MultiValueField のサブクラスは、 clean（）を実装してはならず、代わりに compress（）を実装する必要があります。

必要な引数を1つ追加します。

fields: 値がクリーンアップされ、その後1つの値に結合されるフィールドのタプル。フィールドの各値は、fieldsの対応するフィールドによってクリーンアップされます。最初の値は最初のフィールドによってクリーンアップされ、2番目の値は2番目のフィールドによってクリーンアップされます。すべてのフィールドがクリーンアップされると、クリーンな値のリストが compress（）によって単一の値に結合されます。

また、いくつかのオプションの引数を取ります。

require_all_fields

デフォルトはTrueです。この場合、どのフィールドにも値が指定されていないと、required検証エラーが発生します。

Falseに設定すると、個々のフィールドの Field.required 属性をFalseに設定して、フィールドをオプションにすることができます。必須フィールドに値が指定されていない場合、incomplete検証エラーが発生します。

デフォルトのincompleteエラーメッセージは、 MultiValueField サブクラスで定義できます。または、個々のフィールドごとに異なるメッセージを定義できます。例えば：

from django.core.validators import RegexValidator

class PhoneField(MultiValueField):
    def __init__(self, **kwargs):
        # Define one message for all fields.
        error_messages = {
            'incomplete': 'Enter a country calling code and a phone number.',
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={'incomplete': 'Enter a country calling code.'},
                validators=[
                    RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'),
                ],
            ),
            CharField(
                error_messages={'incomplete': 'Enter a phone number.'},
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')],
            ),
            CharField(
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')],
                required=False,
            ),
        )
        super().__init__(
            error_messages=error_messages, fields=fields,
            require_all_fields=False, **kwargs
        )

widget: django.forms.MultiWidget のサブクラスである必要があります。デフォルト値は TextInput ですが、この場合はおそらくあまり役に立ちません。

compress(data_list)

有効な値のリストを取得し、それらの値の「圧縮」バージョンを単一の値で返します。たとえば、 SplitDateTimeField は、時間フィールドと日付フィールドを組み合わせてdatetimeオブジェクトにするサブクラスです。

このメソッドは、サブクラスに実装する必要があります。

SplitDateTimeField

class SplitDateTimeField(**kwargs)

デフォルトのウィジェット： SplitDateTimeWidget
空の値：None
正規化：Python datetime.datetimeオブジェクト。
指定された値がdatetime.datetimeまたは特定の日時形式でフォーマットされた文字列であることを検証します。
エラーメッセージキー：required、invalid、invalid_date、invalid_time

2つのオプションの引数を取ります。

input_date_formats: 文字列を有効なdatetime.dateオブジェクトに変換するために使用される形式のリスト。

input_date_formats引数が指定されていない場合、 DateField のデフォルトの入力形式が使用されます。

input_time_formats: 文字列を有効なdatetime.timeオブジェクトに変換するために使用される形式のリスト。

input_time_formats引数が指定されていない場合、 TimeField のデフォルトの入力形式が使用されます。

関係を処理するフィールド

モデル間の関係を表すために、 ModelChoiceField と ModelMultipleChoiceField の2つのフィールドを使用できます。これらのフィールドは両方とも、フィールドの選択肢を作成するために使用される単一のquerysetパラメーターを必要とします。フォームの検証時に、これらのフィールドは1つのモデルオブジェクト（ModelChoiceFieldの場合）または複数のモデルオブジェクト（ModelMultipleChoiceFieldの場合）をのcleaned_dataディクショナリに配置します。フォーム。

より複雑な使用法の場合は、フォームフィールドを宣言するときにqueryset=Noneを指定してから、フォームの__init__()メソッドにquerysetを入力できます。

class FooMultipleChoiceForm(forms.Form):
    foo_select = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields['foo_select'].queryset = ...

ModelChoiceFieldとModelMultipleChoiceFieldの両方に、選択肢を生成するときにクエリセットを反復処理するために使用されるクラスを指定するiterator属性があります。詳細については、関係の選択の反復を参照してください。

ModelChoiceField

class ModelChoiceField(**kwargs)

デフォルトのウィジェット：選択
空の値：None
正規化：モデルインスタンス。
指定されたIDがクエリセットに存在することを検証します。
エラーメッセージキー：required、invalid_choice

外部キーを表すのに適した単一のモデルオブジェクトを選択できます。 ModelChoiceFieldのデフォルトのウィジェットは、エントリの数が増えると実用的ではなくなることに注意してください。 100を超えるアイテムには使用しないでください。

単一の引数が必要です：

queryset: フィールドの選択肢が導き出され、ユーザーの選択を検証するために使用されるモデルオブジェクトのQuerySet。フォームがレンダリングされるときに評価されます。

ModelChoiceFieldも、2つのオプションの引数を取ります。

empty_label

デフォルトでは、ModelChoiceFieldで使用される<select>ウィジェットのリストの上部に空の選択肢があります。このラベルのテキスト（デフォルトでは"---------"）をempty_label属性で変更するか、empty_labelをNone：

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

ModelChoiceFieldが必要で、デフォルトの初期値がある場合、（empty_labelの値に関係なく）空の選択肢は作成されないことに注意してください。

to_field_name

このオプションの引数は、フィールドのウィジェットの選択肢の値として使用するフィールドを指定するために使用されます。モデルの一意のフィールドであることを確認してください。そうでない場合、選択した値が複数のオブジェクトと一致する可能性があります。デフォルトではNoneに設定されており、この場合、各オブジェクトの主キーが使用されます。例えば：

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

生成されます：

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

と：

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

生成されます：

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

ModelChoiceFieldにも次の属性があります。

iterator: querysetからフィールド選択を生成するために使用されるイテレータクラス。デフォルトでは、 ModelChoiceIterator です。

モデルの__str__()メソッドが呼び出され、フィールドの選択で使用するオブジェクトの文字列表現が生成されます。カスタマイズされた表現を提供するには、ModelChoiceFieldをサブクラス化し、label_from_instanceをオーバーライドします。このメソッドはモデルオブジェクトを受け取り、それを表すのに適した文字列を返す必要があります。例えば：

from django.forms import ModelChoiceField

class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

ModelMultipleChoiceField

class ModelMultipleChoiceField(**kwargs)

デフォルトのウィジェット： SelectMultiple
空の値：空のQuerySet（self.queryset.none()）
正規化：モデルインスタンスのQuerySet。
指定された値のリスト内のすべてのIDがクエリセットに存在することを検証します。
エラーメッセージキー：required、invalid_list、invalid_choice、invalid_pk_value

invalid_choiceメッセージには%(value)sが含まれ、invalid_pk_valueメッセージには%(pk)sが含まれる場合があり、これらは適切な値に置き換えられます。

多対多の関係を表すのに適した、1つ以上のモデルオブジェクトの選択を可能にします。 ModelChoiceField と同様に、label_from_instanceを使用してオブジェクト表現をカスタマイズできます。

単一の引数が必要です：

queryset: ModelChoiceField.queryset と同じです。

オプションの引数を1つ取ります。

to_field_name: ModelChoiceField.to_field_name と同じです。

ModelMultipleChoiceFieldにも次の属性があります。

iterator: ModelChoiceField.iterator と同じです。

バージョン3.1以降非推奨： listメッセージは非推奨です。代わりにinvalid_listを使用してください。

関係の選択を繰り返す

デフォルトでは、 ModelChoiceField および ModelMultipleChoiceField は、 ModelChoiceIterator を使用してフィールドchoicesを生成します。

ModelChoiceIteratorを繰り返すと、各選択肢の最初のvalue要素として ModelChoiceIteratorValue インスタンスを含む2タプルの選択肢が生成されます。 ModelChoiceIteratorValueは、カスタムウィジェットの実装で使用できるソースモデルインスタンスへの参照を維持しながら、選択値をラップします。たとえば、 data- *属性を<option>に追加します。要素。

たとえば、次のモデルについて考えてみます。

from django.db import models

class Topping(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(decimal_places=2, max_digits=6)

    def __str__(self):
        return self.name

class Pizza(models.Model):
    topping = models.ForeignKey(Topping, on_delete=models.CASCADE)

Select ウィジェットサブクラスを使用して、各<option>要素のHTML属性data-priceとしてTopping.priceの値を含めることができます。

from django import forms

class ToppingSelect(forms.Select):
    def create_option(self, name, value, label, selected, index, subindex=None, attrs=None):
        option = super().create_option(name, value, label, selected, index, subindex, attrs)
        if value:
            option['attrs']['data-price'] = value.instance.price
        return option

class PizzaForm(forms.ModelForm):
    class Meta:
        model = Pizza
        fields = ['topping']
        widgets = {'topping': ToppingSelect}

これにより、Pizza.toppingが次のように選択されます。

<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>

より高度な使用法については、ModelChoiceIteratorをサブクラス化して、生成された2タプルの選択肢をカスタマイズできます。

ModelChoiceIterator

class ModelChoiceIterator(field)

ModelChoiceField および ModelMultipleChoiceField のiterator属性に割り当てられたデフォルトのクラス。クエリセットから2タプルの選択肢を生成する反復可能オブジェクト。

単一の引数が必要です：

field: ModelChoiceFieldまたはModelMultipleChoiceFieldのインスタンスを繰り返して、選択肢を生成します。

ModelChoiceIteratorには次の方法があります。

__iter__(): ChoiceField.choices で使用される(value, label)形式で、2タプルの選択肢を生成します。最初のvalue要素は ModelChoiceIteratorValue インスタンスです。

バージョン3.1での変更：古いバージョンでは、選択タプルの最初のvalue要素は、ModelChoiceIteratorValueインスタンスではなく、field値自体です。ほとんどの場合、これは透過的にプロキシしますが、field値自体が必要な場合は、代わりに ModelChoiceIteratorValue.value 属性を使用してください。

ModelChoiceIteratorValue

class ModelChoiceIteratorValue(value, instance)

バージョン3.1の新機能。

2つの引数が必要です。

value: 選択の価値。この値は、HTML <option>要素のvalue属性をレンダリングするために使用されます。

instance: クエリセットのモデルインスタンス。カスタムChoiceWidget.create_option()実装でインスタンスにアクセスして、レンダリングされたHTMLを調整できます。

ModelChoiceIteratorValueには次の方法があります。

__str__(): valueをHTMLでレンダリングされる文字列として返します。

カスタムフィールドの作成

組み込みのFieldクラスがニーズを満たさない場合は、カスタムFieldクラスを作成できます。これを行うには、django.forms.Fieldのサブクラスを作成します。その唯一の要件は、clean()メソッドを実装し、その__init__()メソッドが上記のコア引数（required、label、 [ X162X]、widget、help_text）。

get_bound_field（）をオーバーライドして、フィールドへのアクセス方法をカスタマイズすることもできます。

フォームフィールド—Djangoドキュメント

フォームフィールド

コアフィールド引数

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

フィールドデータが変更されたかどうかを確認する

has_changed()

組み込みのFieldクラス

BooleanField

CharField

ChoiceField

TypedChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

ImageField

IntegerField

JSONField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

やや複雑なビルトインFieldクラス

ComboField

MultiValueField

SplitDateTimeField

関係を処理するフィールド

ModelChoiceField

ModelMultipleChoiceField

関係の選択を繰り返す

ModelChoiceIterator

ModelChoiceIteratorValue

カスタムフィールドの作成