Form クラスを作成時の一番重要な部分は、form のフィールド (field) の定義です。各フィールドにはカスタムの検証ロジックがあり、他にいくつかのフックもあります。
Field クラスを使用する主な方法は Form クラス内ですが、それらを直接インスタンス化して使用することで、その動作をより良く理解できます。各 Field インスタンスには、単一の引数を取る clean() メソッドがあり、django.core.exceptions.ValidationError 例外を発生させるか、クリーンな値を返します。
>>> from django import forms\n>>> f = forms.EmailField()\n>>> f.clean("foo@example.com")\n'foo@example.com'\n>>> f.clean("invalid email address")\nTraceback (most recent call last):\n...\nValidationError: ['Enter a valid email address.']\n各 Field クラスのコンストラクタは少なくとも以下の引数を受け付けます。Field クラスによっては追加のフィールド固有の引数も取れることがありますが、以下に説明する引数は 常に 取ることができます。
requiredLink to this heading#デフォルトでは、各 Field クラスは値が必須であると想定しているため、空の値 (None もしくは空文字列 ("")) を渡すと、clean() は ValidationError 例外を発生させます。
>>> from django import forms\n>>> f = forms.CharField()\n>>> f.clean("foo")\n'foo'\n>>> f.clean("")\nTraceback (most recent call last):\n...\nValidationError: ['This field is required.']\n>>> f.clean(None)\nTraceback (most recent call last):\n...\nValidationError: ['This field is required.']\n>>> f.clean(" ")\n' '\n>>> f.clean(0)\n'0'\n>>> f.clean(True)\n'True'\n>>> f.clean(False)\n'False'\nフィールドが必須で ない ことを指定するには、Field コンストラクタに required=False を渡します:
>>> f = forms.CharField(required=False)\n>>> f.clean("foo")\n'foo'\n>>> f.clean("")\n''\n>>> f.clean(None)\n''\n>>> f.clean(0)\n'0'\n>>> f.clean(True)\n'True'\n>>> f.clean(False)\n'False'\nField に required=False が設定されていて、clean() に空の値を渡した場合、clean() は ValidationError を発生させる代わりに、 正規化された 空の値を返します。CharField の場合、これは empty_value を返し、デフォルトでは空の文字列となります。他の Field クラスでは、None になることもあります。(これはフィールドによって異なります。)
必須フォームフィールドのウィジェットは、required HTML属性を持っています。これを無効にするには、 Form.use_required_attribute 属性を False に設定します。フォームセットのフォームには、required 属性が含まれていません。これは、フォームセットの追加や削除を行う際にブラウザの検証が正しくない可能性があるためです。
labelLink to this heading#label 属性は、フィールドに対する "人が読みやすい" ラベルを指定します。このラベルは Field が Form 内で表示されるときに使用されます。
上述の "HTML としてフォームを出力する" で説明したとおり、Field に対するデフォルトのラベルはアンダースコアを空白に、また単語の最初の小文字を大文字に変換して生成されます。 デフォルトではない文字列を表示したい場合には、label を指定してください。
以下は、2 つのフィールドに対して label を実装する Form の完全な例です。出力を簡略化するために、 auto_id=False を指定しています:
>>> from django import forms\n>>> class CommentForm(forms.Form):\n... name = forms.CharField(label="Your name")\n... url = forms.URLField(label="Your website", required=False)\n... comment = forms.CharField()\n...\n>>> f = CommentForm(auto_id=False)\n>>> print(f)\n<div>Your name:<input type="text" name="name" required></div>\n<div>Your website:<input type="url" name="url"></div>\n<div>Comment:<input type="text" name="comment" required></div>\nlabel_suffixLink to this heading#label_suffix 引数を使用すると、フォームの label_suffix をフィールドごとに上書きできます。
>>> class ContactForm(forms.Form):\n... age = forms.IntegerField()\n... nationality = forms.CharField()\n... captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")\n...\n>>> f = ContactForm(label_suffix="?")\n>>> print(f)\n<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>\n<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>\n<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>\ninitialLink to this heading#initial 属性は、Field が結びつけられていない Form で表示されるときに使われる初期値を指定します。
動的に初期値を指定する方法は、Form.initial パラメータを参照してください。
これの使用例は、あるフィールドが特定の値で初期化された「空」のフォームを表示したい場合です。例えば:
\n>>> from django import forms\n>>> class CommentForm(forms.Form):\n... name = forms.CharField(initial="Your name")\n... url = forms.URLField(initial="http://")\n... comment = forms.CharField()\n...\n>>> f = CommentForm(auto_id=False)\n>>> print(f)\n<div>Name:<input type="text" name="name" value="Your name" required></div>\n<div>Url:<input type="url" name="url" value="http://" required></div>\n<div>Comment:<input type="text" name="comment" required></div>\n初期値の辞書をフォームの表示時にデータとして渡すだけでよいのでは？と考えるかもしれません。しかし、それを行うとバリデーションがトリガーされ、HTML出力にはバリデーションエラーが含まれます。
\n>>> class CommentForm(forms.Form):\n... name = forms.CharField()\n... url = forms.URLField()\n... comment = forms.CharField()\n...\n>>> default_data = {"name": "Your name", "url": "http://"}\n>>> f = CommentForm(default_data, auto_id=False)\n>>> print(f)\n<div>Name:\n <input type="text" name="name" value="Your name" required>\n</div>\n<div>Url:\n <ul class="errorlist"><li>Enter a valid URL.</li></ul>\n <input type="url" name="url" value="http://" required aria-invalid="true">\n</div>\n<div>Comment:\n <ul class="errorlist"><li>This field is required.</li></ul>\n <input type="text" name="comment" required aria-invalid="true">\n</div>\nこれが、initial 値が未結合フォームにのみ表示される理由です。結合フォームの場合、HTML 出力は結合データを使用します。
また、initial 値は、特定のフィールドの値が指定されていない場合に、バリデーション内で "デフォルト" データとして使用されません。initial 値は、初期フォーム表示のためのみに意図されています。
>>> class CommentForm(forms.Form):\n... name = forms.CharField(initial="Your name")\n... url = forms.URLField(initial="http://")\n... comment = forms.CharField()\n...\n>>> data = {"name": "", "url": "", "comment": "Foo"}\n>>> f = CommentForm(data)\n>>> f.is_valid()\nFalse\n# The form does *not* fall back to using the initial values.\n>>> f.errors\n{'url': ['This field is required.'], 'name': ['This field is required.']}\n定数の代わりに、任意の呼び出し可能オブジェクトを渡すこともできます:
\n>>> import datetime\n>>> class DateForm(forms.Form):\n... day = forms.DateField(initial=datetime.date.today)\n...\n>>> print(DateForm())\n<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>\n呼び出し可能オブジェクトは、定義される時ではなく、未バインドの形式が表示される時にのみ評価されます。
\nwidgetLink to this heading#widget 引数は、Field をレンダリングするときに使う Widget クラスを指定します。詳しくは ウィジェット を参照してください。
help_textLink to this heading#help_text 引数は、Field を説明するテキストを指定します。help_text を指定した場合、容易な Form メソッド (たとえば as_ul()) で Field がレンダリングされるときに、Field の隣に表示されます。
モデルフィールドの help_text と同じく、値は自動的に生成されるフォーム内で HTML 用にエスケープされません。
以下は、2つのフィールドに help_text を実装した Form の完全な例です。出力を単純化するために auto_id=False を指定しています:
>>> from django import forms\n>>> class HelpTextContactForm(forms.Form):\n... subject = forms.CharField(max_length=100, help_text="100 characters max.")\n... message = forms.CharField()\n... sender = forms.EmailField(help_text="A valid email address, please.")\n... cc_myself = forms.BooleanField(required=False)\n...\n>>> f = HelpTextContactForm(auto_id=False)\n>>> print(f)\n<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>\n<div>Message:<input type="text" name="message" required></div>\n<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>\n<div>Cc myself:<input type="checkbox" name="cc_myself"></div>\nフィールドにヘルプテキストがあり、ウィジェットが <fieldset> でレンダリングされていない場合、aria-describedby が <input> に追加され、ヘルプテキストと関連付けられます:
>>> from django import forms\n>>> class UserForm(forms.Form):\n... username = forms.CharField(max_length=255, help_text="e.g., user@example.com")\n...\n>>> f = UserForm()\n>>> print(f)\n<div>\n<label for="id_username">Username:</label>\n<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>\n<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">\n</div>\nカスタム aria-describedby 属性を追加する際には、使用している場合は help_text 要素の id も希望する順序で含めることを確認してください。スクリーンリーダーのユーザーにとって、説明は aria-describedby 内の出現順に読み上げられます。
>>> class UserForm(forms.Form):\n... username = forms.CharField(\n... max_length=255,\n... help_text="e.g., user@example.com",\n... widget=forms.TextInput(\n... attrs={"aria-describedby": "custom-description id_username_helptext"},\n... ),\n... )\n...\n>>> f = UserForm()\n>>> print(f["username"])\n<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>\nerror_messagesLink to this heading#error_messages 引数を使用すると、フィールドが出すデフォルトのメッセージを上書きできます。上書きしたいエラーメッセージに一致するキーを持つ辞書を渡してください。例えば、これはデフォルトのエラーメッセージです：
>>> from django import forms\n>>> generic = forms.CharField()\n>>> generic.clean("")\nTraceback (most recent call last):\n ...\nValidationError: ['This field is required.']\nそしてこれがカスタムエラーメッセージです:
\n>>> name = forms.CharField(error_messages={"required": "Please enter your name"})\n>>> name.clean("")\nTraceback (most recent call last):\n ...\nValidationError: ['Please enter your name']\n以下の built-in Field classes セクションでは、各 Field が使用するエラーメッセージのキーを定義しています。
validatorsLink to this heading#validators 引数は、フィールドに対するバリデーション関数のリストを指定します。
詳しくは バリデータのドキュメント を参照してください。
\nlocalizeLink to this heading#localize 引数は、form データの入力とレンダリングした出力のローカライズを有効にします。
詳しくは 表示形式のローカライズ ドキュメントを読んでください。
\ndisabledLink to this heading#disabled はブール値の引数を取ります。 True にセットされた場合、フォームのフィールドを disabled HTML 属性を使って無効化し、ユーザーが編集できないようにします。たとえユーザーが勝手にフィールドの値を書き換えてサーバーに送信したとしても、フォームの初期データを使い、書き換えられたデータは無視します。
template_nameLink to this heading#template_name 引数は、フィールドが as_field_group() でレンダリングされるときにカスタムテンプレートを使用できるようにします。デフォルトの値は "django/forms/field.html" に設定されています。この属性をオーバーライドするか、デフォルトテンプレートをオーバーライドすることで、フィールドごとに変更できます。詳細は、 組み込みのフィールドテンプレートをオーバーライドする も参照してください。
has_changed()Link to this heading#has_changed() メソッドは、フィールドの値が最初の値から変更されたかどうかを確認するのに使用します。True または False を返します。
詳しくは Form.has_changed() ドキュメントを読んでください。
Field クラスLink to this heading#当然ながら、forms ライブラリには共通のバリデーションニーズを代表する一連の Field クラスが含まれています。このセクションでは、各ビルトインフィールドについて説明します。
各フィールドについて、widget を指定しない場合に使用されるデフォルトウィジェットを説明します。また、空の値を提供した場合に返される値も指定します（これがどういう意味かについては required セクションを参照してください）。
BooleanFieldLink to this heading#デフォルトのウィジェット: CheckboxInput
空の値: False
正規化後の値: Pythonの True または False になります。
フィールドが required=True を持つ場合、値が True (例えば、チェックボックスがチェックされている)であることを確認します。
エラーメッセージのキー: required
CharFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: empty_value として与えたもの
正規化後の値: 文字列になります。
max_length と min_length が与えられた場合は、MaxLengthValidator と MinLengthValidator を使用します。それ以外の場合は、すべての入力が有効です。
エラーメッセージキー: required, max_length, min_length
次のオプション引数がバリデーションに使用されます:
\nこれらの引数が提供された場合、文字列が与えられた長さ以下か以上であることを保証します。
\nTrue （デフォルト）の場合、値から先頭と末尾の空白が削除されます。
「空」を表すのに使用する値です。デフォルトは空の文字列です。
\nChoiceFieldLink to this heading#デフォルトのウィジェット: Select
空の値: '' (空の文字列)
正規化後の値: 文字列になります。
指定された値が選択肢のリスト内に存在することを検証します。
エラーメッセージのキー: required, invalid_choice
invalid_choice エラーメッセージには %(value)s が含まれていることがあり、選択された選択肢に置き換えられます。
1つの追加引数を受け取ります:
\nこのフィールドの選択肢として使用する2値タプルの iterable 、 列挙型 、またはそのようなイテラブルを返す呼び出し可能オブジェクトのいずれか。この引数は、モデルフィールドの choices 引数と同じ形式を受け入れます。詳細については、 モデルフィールドのリファレンスドキュメント を参照してください。引数が呼び出し可能オブジェクトの場合、フィールドのフォームが初期化されるたび、およびレンダリング中に評価されます。デフォルトは空のリストです。
DateFieldLink to this heading#デフォルトのウィジェット: DateInput
空の値: None
正規化後の値: Python の datetime.date オブジェクトになります。
与えられた値が datetime.date、datetime.datetime または特定の日付の表示形式のどれかに当てはまるか検証します。
エラーメッセージのキー: required、invalid
1 つの省略可能な引数を取ります:
\n文字列を有効な datetime.date オブジェクトに変換しようとする際に使用されるフォーマットのイテラブル。
input_formats 引数が指定されていない場合、デフォルトの入力形式は有効なロケール形式の DATE_INPUT_FORMATS キーから取得されるか、ローカライズが無効になっている場合は DATE_INPUT_FORMATS から取得されます。また、 表示形式のローカライズ も参照してください。
DateTimeFieldLink to this heading#デフォルトのウィジェット: DateTimeInput
空の値: None
正規化後の値: Python の datetime.datetime オブジェクトになります。
与えられた値が datetime.datetime、datetime.date または特定の日時の表示形式の文字列のどれかに当てはまるか検証します。
エラーメッセージのキー: required、invalid
1 つの省略可能な引数を取ります:
\nISO 8601 形式に加えて、文字列を有効な datetime.datetime オブジェクトに変換しようと試みる際に使用される形式のイテラブル。
このフィールドは常に、ISO 8601形式の日付や parse_datetime() で認識される類似の形式の文字列を受け付けます。いくつかの例を挙げます:
'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 引数が提供されない場合、デフォルトの入力フォーマットはアクティブなロケールフォーマットの DATETIME_INPUT_FORMATS と DATE_INPUT_FORMATS キーから取得されます。もしくは、ローカライズが無効の場合は DATETIME_INPUT_FORMATS と DATE_INPUT_FORMATS から取得されます。また、表示形式のローカライズについては 表示形式のローカライズ も参照してください。
DecimalFieldLink to this heading#デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.
空の値: None
正規化後の値: Python の decimal になります。
指定された値が10進数であることを検証します。 max_value と min_value が提供されている場合は MaxValueValidator および MinValueValidator を使用します。 step_size が提供されている場合は StepValueValidator を使用します。先頭及び末尾の空白は無視されます。
エラーメッセージのキー: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size 。
max_value および min_value のエラーメッセージには %(limit_value)s が含まれる場合があり、これは適切な制限値に置き換えられます。同様に、max_digits、max_decimal_places、および max_whole_digits のエラーメッセージには %(max)s が含まれる場合があります。
5つのオプション引数を受け取ります:
\nこれらはフィールドに許可される値の範囲を制御し、decimal.Decimal 値として指定する必要があります。
値で許容される桁数の最大値 (小数点より前と小数点より後の桁数を合わせ、先頭のゼロは除く)。
\n許可される小数点以下の最大桁数。
\n有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。
DurationFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: None
正規化後の値: Python の timedelta になります。
指定された値が timedelta に変換できる文字列であることを検証します。値は datetime.timedelta.min と datetime.timedelta.max の間でなければなりません。
エラーメッセージのキー: required、invalid、overflow 。
parse_duration() が理解できるどんな形式でも受け入れます。
EmailFieldLink to this heading#デフォルトのウィジェット: EmailInput
空の値: empty_value として指定したものです。
正規化後の値: 文字列になります。
EmailValidator を使用して、与えられた値が有効なメールアドレスであることを、比較的複雑な正規表現を使用してバリデーションします。
エラーメッセージのキー: required、invalid
オプション引数として max_length、min_length、empty_value があり、CharField と同じように機能します。 max_length 引数のデフォルト値は320です( RFC 3696 Section 3 を参照)。
FileFieldLink to this heading#デフォルトのウィジェット: ClearableFileInput
空の値: None
ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした UploadedFile オブジェクトに正規化されます。
フォームに空でないファイルデータがバインドされていることをバリデーションできます。
エラーメッセージのキー: required, invalid, missing, empty, max_length
バリデーションのためのオプション引数には max_length と allow_empty_file があります。もしこれらが指定された場合、ファイル名は与えられた長さ以下でなければならず、ファイルの内容が空でもバリデーションは成功します。
UploadedFile オブジェクトについて詳しく知るには、 ファイルのアップロードのドキュメント を読んでください。
フォーム内で FileField を使用する時は、ファイルのデータをフォームにバインド することも必要です。
max_length エラーは、ファイル名の長さに関連しています。そのキーのエラーメッセージでは、%(max)d は最大ファイル名長さに置き換えられ、%(length)d は現在のファイル名の長さに置き換えられます。
FilePathFieldLink to this heading#デフォルトのウィジェット: Select
空の値: '' (空の文字列)
正規化後の値: 文字列になります。
選択された選択肢が選択肢のリストに存在することを検証します。
エラーメッセージのキー: required, invalid_choice
このフィールドは、特定のディレクトリ内のファイルから選択することを可能にします。5つの追加引数を受け取りますが、path のみが必須です:
リストアップしたいディレクトリの絶対パス。このディレクトリは存在していなければなりません。
\nFalse (デフォルト) の場合、path の直接の内容のみが選択肢として提示されます。True の場合、ディレクトリは再帰的に降りていき、すべての子孫が選択肢としてリストアップされます。
正規表現パターンです。この表現と一致する名前のファイルのみが選択肢として許可されます。
\nオプション。True または False のいずれかを指定します。デフォルトは True です。指定された場所のファイルを含めるかどうかを指定します。これか allow_folders のいずれかを True にする必要があります。
オプションです。True または False です。デフォルトは False です。指定された場所のフォルダを含めるかどうかを指定します。これか allow_files のいずれかが True でなければなりません。
FloatFieldLink to this heading#デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.
空の値: None
正規化後の値: Python の float になります。
指定された値が float であることを検証します。 max_value と min_value が提供されている場合は MaxValueValidator と MinValueValidator を使用します。step_size が提供されている場合は StepValueValidator を使用します。Python の float() 関数と同様、先頭と末尾の空白は許可されます。
エラーメッセージのキー: required、invalid、max_value、min_value、step_size 。
オプションで3つの引数を取ります:
\nこれらは、フィールドに許可される値の範囲を制御します。
\n有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。
GenericIPAddressFieldLink to this heading#IPv4 または IPv6 アドレスのいずれかを持つフィールドです。
\nデフォルトのウィジェット: TextInput
空の値: '' (空の文字列)
正規化後の値: 文字列。以下の説明に従って、IPv6 アドレスは正規化されます。
与えられた値が有効な IP アドレスを表しているか検証します。
Error message keys: required, invalid, max_length
IPv6 アドレスは、 RFC 4291 Section 2.2 section 2.2 (同セクションの paragraph 3 で提案された IPv4 のフォーマットの使用を含む) にしたがって、 ::ffff:192.0.2.0 のように正規化します。たとえば、 2001:0::0:01 は 2001::1 と正規化され、 ::ffff:0a0a:0a0a は ::ffff:10.10.10.10 と正規化されます。そして、すべての文字は小文字に変換されます。
オプションで3つの引数を取ります:
\n有効な入力を指定したプロトコルに限定します。指定できる値は、 both (デフォルト)、 IPv4 または IPv6 です。大文字・小文字は無視されます。
IPv4 にマッピングされた ::ffff:192.0.2.1 のようなアドレスをアンパックします。このオプションを有効にすると、このアドレスは 192.0.2.1 とアンパックされます。デフォルトは無効です。protocol が 'both' に設定されている場合にだけ使用できます。
Defaults to 39, and behaves the same way as it does for\nCharField.
ImageFieldLink to this heading#デフォルトのウィジェット: ClearableFileInput
空の値: None
ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした UploadedFile オブジェクトに正規化されます。
ファイルデータがフォームにバインドされたことを検証します。また、 FileExtensionValidator を使用して、ファイルの拡張子が Pillow でサポートされているかを検証します。
エラーメッセージのキー: required, invalid, missing, empty, invalid_image
ImageField を使用するには、使用する画像形式をサポートする Pillow がインストールされている必要があります。画像をアップロードする際に corrupt image エラーが発生する場合、通常はその形式を理解していないためです。これを修正するには、適切なライブラリをインストールして Pillow を再インストールしてください。
フォームで ImageField を使用する場合、フォームにファイルデータをバインドする 必要も覚えておいてください。
フィールドがクリーンアップされ、バリデーションされた後、UploadedFile オブジェクトには、ファイルが有効な画像であるかを確認するために使用されたPillowの Image インスタンスを含む追加の image 属性があります。Pillow は画像を検証した後にベースとなるファイルディスクリプタを閉じるため、format、height、width などの非画像データ属性は使用可能ですが、getdata() や getpixel() のようにベースとなる画像データにアクセスするメソッドは、ファイルを再度開かない限り使用できません。例えば:
>>> from PIL import Image\n>>> from django import forms\n>>> from django.core.files.uploadedfile import SimpleUploadedFile\n>>> class ImageForm(forms.Form):\n... img = forms.ImageField()\n...\n>>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")}\n>>> form = ImageForm({}, file_data)\n# Pillow closes the underlying file descriptor.\n>>> form.is_valid()\nTrue\n>>> image_field = form.cleaned_data["img"]\n>>> image_field.image\n<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>\n>>> image_field.image.width\n191\n>>> image_field.image.height\n287\n>>> image_field.image.format\n'PNG'\n>>> image_field.image.getdata()\n# Raises AttributeError: 'NoneType' object has no attribute 'seek'.\n>>> image = Image.open(image_field)\n>>> image.getdata()\n<ImagingCore object at 0x7f5984f874b0>\nさらに、Pillowが画像のコンテンツタイプを特定できる場合には、UploadedFile.content_type は画像のコンテンツタイプで更新されます。それ以外の場合は、None に設定されます。
IntegerFieldLink to this heading#デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.
空の値: None
正規化後の値: Python の整数になります。
与えられた値が整数であることを検証します。max_value と min_value が提供されている場合は MaxValueValidator と MinValueValidator を使用します。step_size が提供されている場合は StepValueValidator を使用します。Python の int() 関数と同様、先頭と末尾の空白は許可されます。
エラーメッセージキー: required, invalid, max_value, min_value, step_size
max_value、min_value、および step_size のエラーメッセージには、%(limit_value)s が含まれることがあり、これは適切な制限値に置き換えられます。
バリデーションのために、3つのオプション引数を受け取ります:
\nこれらは、フィールドに許可される値の範囲を制御します。
\n有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。
JSONFieldLink to this heading#JSONField 用の、JSON エンコードされたデータを受け入れるフィールドです。
デフォルトのウィジェット: Textarea
空の値: None
正規化後の値: JSONField.decoder に依存して、JSON 値の Python 表現 (通常は dict、list、または None) に正規化されます。
与えられた値が有効な JSON であることを検証します。
エラーメッセージのキー: required、invalid
次の2つの省略可能な引数を取ります:
\n標準のJSONシリアライザがサポートしていないデータ型 (datetime.datetime や UUID など) をシリアライズするための json.JSONEncoder のサブクラスです。例えば、 DjangoJSONEncoder クラスを使用できます。
デフォルトは json.JSONEncoder です。
入力をデシリアライズするための json.JSONDecoder のサブクラスです。デシリアライズでは、入力タイプを確実に把握できないという事実に対応する必要があります。例えば、datetime 形式と同じ形式を持つ文字列が、実際には datetime として返されるリスクがあります。
decoder を使用して入力をバリデーションできます。デシリアライズ中に json.JSONDecodeError が発生した場合は、ValidationError が発生します。
デフォルトは json.JSONDecoder です。
MultipleChoiceFieldLink to this heading#デフォルトのウィジェット: SelectMultiple
空の値: [] (空のリスト)
正規化後の値: 文字列のリストになります。
与えられた値のリストの各値が、選択肢のリストに存在することを検証します。
エラーメッセージのキー: required, invalid_choice, invalid_list
invalid_choice エラーメッセージには %(value)s が含まれていることがあり、選択された選択肢に置き換えられます。
ChoiceField のために、1つの追加の必須引数 choices を取ります。
NullBooleanFieldLink to this heading#デフォルトのウィジェット: NullBooleanSelect
空の値: None
正規化後の値: Pythonの True、False、または None になります。
何も検証しません（つまり、ValidationError を決して発生させません）。
NullBooleanField は、ウィジェットの choices を指定することで、 Select や RadioSelect などのウィジェットで使用できます。
NullBooleanField(\n widget=Select(\n choices=[\n ("", "Unknown"),\n (True, "Yes"),\n (False, "No"),\n ]\n )\n)\nRegexFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: empty_value として指定したものです。
正規化後の値: 文字列になります。
RegexValidator を使用して、与えられた値が特定の正規表現と一致するかどうかを検証します。
エラーメッセージのキー: required、invalid
1つの必須引数を取ります:
\n文字列またはコンパイルされた正規表現オブジェクトとして指定される正規表現。
\nmax_length、min_length、strip、および empty_value も受け取ります。これらは CharField と全く同じように機能します。
デフォルトは False です。有効にした場合、正規表現バリデーションの前にストリップ処理が適用されます。
SlugFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: empty_value として与えたもの
正規化後の値: 文字列になります。
validate_slug または validate_unicode_slug を使用して、与えられた値が文字、数字、アンダースコア、ハイフンのみを含むかを検証します。
エラーメッセージ: required、invalid
このフィールドは、フォームでモデルの SlugField を表現するために使用することを意図しています。
2つのオプションパラメーターを取ります：
\nフィールドが ASCII 文字に加えて Unicode 文字を受け入れるよう指示するブール値です。デフォルトは False です。
「空」を表すのに使用する値です。デフォルトは空の文字列です。
\nTimeFieldLink to this heading#デフォルトのウィジェット: TimeInput
空の値: None
正規化後の値: Python の datetime.time オブジェクトになります。
与えられた値が datetime.time か、特定の時間形式でフォーマットされた文字列であることを検証します。
エラーメッセージのキー: required、invalid
1 つの省略可能な引数を取ります:
\n文字列を有効な datetime.time オブジェクトに変換するために試みる形式のイテラブル。
input_formats 引数が指定されていない場合、デフォルトの入力形式は、アクティブなロケール形式の TIME_INPUT_FORMATS キーから取得されるか、ローカライズが無効の場合は TIME_INPUT_FORMATS から取得されます。詳細は、表示形式のローカライズ を参照してください。
TypedChoiceFieldLink to this heading#ChoiceField と同様ですが、 TypedChoiceField は2つの追加引数、 coerce と empty_value を取ります。
デフォルトのウィジェット: Select
空の値: empty_value として与えたもの
正規化後の値: coerce 引数で指定された型になります。
指定された値が選択肢のリストに存在し、強制変換できることを検証します。
エラーメッセージのキー: required, invalid_choice
追加の引数を取ります:
\n1つの引数を受け取り、強制された値を返す関数です。例には組み込みの int、float、bool、その他の型が含まれます。デフォルトは恒等関数です。強制は入力バリデーションの後に行われるため、choices に存在しない値への強制が可能です。
"空" を表すために使用する値です。デフォルトは空文字列です。 None もここでよく使用される選択肢の一つです。この値は、 coerce 引数で与えられた関数によって強制されないことに注意してください。それに応じて選択してください。
TypedMultipleChoiceFieldLink to this heading#MultipleChoiceField と同様ですが、 TypedMultipleChoiceField は coerce と empty_value という2つの追加の引数を受け取ります。
デフォルトのウィジェット: SelectMultiple
空の値: empty_value として渡したもの
正規化後の値: coerce 引数によって提供される型の値のリストになります。
指定された値が選択肢のリスト内に存在し、強制変換できることを検証します。
エラーメッセージのキー: required, invalid_choice
invalid_choice エラーメッセージには %(value)s が含まれていることがあり、選択された選択肢に置き換えられます。
TypedChoiceField と同様に、2つの追加引数 coerce と empty_value を取ります。
URLFieldLink to this heading#デフォルトのウィジェット: URLInput
空の値: empty_value として指定したものです。
正規化後の値: 文字列になります。
与えられた値が有効なURLであることを検証するために URLValidator を使用します。
エラーメッセージのキー: required、invalid
オプション引数 max_length、min_length、empty_value は CharField での動作と全く同じように機能し、さらにもう一つの引数があります:
スキーマが省略されたURLに対して想定されるスキーマです。デフォルトは "http" です。たとえば、assume_scheme が "https" で、提供された値が "example.com" の場合、正規化された値は "https://example.com" になります。
UUIDFieldLink to this heading#このフィールドは、 UUID コンストラクタの hex 引数として受け入れられる任意の文字列形式を受け付けます。
Field クラスLink to this heading#ComboFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: '' (空の文字列)
正規化後の値: 文字列になります。
ComboField に引数として指定された各フィールドに対して、与えられた値をバリデーションします。
エラーメッセージのキー: required、invalid
1つの必須の追加引数を受け取ります:
\nフィールドの値を検証するために使用すべきフィールドのリスト(渡した順序で検証されます)。
\n>>> from django.forms import ComboField\n>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])\n>>> f.clean("test@example.com")\n'test@example.com'\n>>> f.clean("longemailaddress@example.com")\nTraceback (most recent call last):\n...\nValidationError: ['Ensure this value has at most 20 characters (it has 28).']\nMultiValueFieldLink to this heading#デフォルトのウィジェット: TextInput
空の値: '' (空の文字列)
正規化後の値: サブクラスの compress メソッドによって返される型になります。
指定された引数としての MultiValueField に各フィールドに対して与えられた値を検証します。
エラーメッセージキー: required, invalid, incomplete
複数のフィールドのロジックを集計し、単一の値を生成します。
\nこのフィールドは抽象フィールドで、サブクラス化する必要があります。単一値フィールドとは対照的に、MultiValueField のサブクラスは clean() を実装してはいけません。代わりに、compress() を実装します。
1つの必須の追加引数を受け取ります:
\n値がクリーニングされた後に単一の値に組み合わされるフィールドのタプル。フィールドの各値は、fields 内の対応するフィールドによってクリーニングされます。最初の値は最初のフィールドによって、2番目の値は2番目のフィールドによって、という具合にクリーニングされます。すべてのフィールドがクリーニングされたら、クリーニングされた値のリストは compress() によって単一の値に結合されます。
オプションの引数もいくつか受け取ります:
\nデフォルトは True で、フィールドに値が指定されていない場合は required バリデーションエラーが発生します。
Field.required 属性を False に設定すると、個々のフィールドをオプションフィールドにすることができます。必須フィールドに値が与えられない場合、incomplete というバリデーションエラーが発生します。
デフォルトの incomplete エラーメッセージは、MultiValueField のサブクラス上で定義できます。また、個々のフィールドごとに異なるメッセージを定義することもできます。例えば:
from django.core.validators import RegexValidator\n\n\nclass PhoneField(MultiValueField):\n def __init__(self, **kwargs):\n # Define one message for all fields.\n error_messages = {\n "incomplete": "Enter a country calling code and a phone number.",\n }\n # Or define a different message for each field.\n fields = (\n CharField(\n error_messages={"incomplete": "Enter a country calling code."},\n validators=[\n RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."),\n ],\n ),\n CharField(\n error_messages={"incomplete": "Enter a phone number."},\n validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")],\n ),\n CharField(\n validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")],\n required=False,\n ),\n )\n super().__init__(\n error_messages=error_messages,\n fields=fields,\n require_all_fields=False,\n **kwargs\n )\ndjango.forms.MultiWidget のサブクラスでなければなりません。デフォルト値は TextInput ですが、この場合にはあまり役に立たないかもしれません。
有効な値のリストを受け取り、それらの値を単一の値に「圧縮」して返します。例えば、SplitDateTimeField は時間フィールドと日付フィールドを組み合わせて datetime オブジェクトにするサブクラスです。
このメソッドはサブクラスで実装されなければなりません。
\nSplitDateTimeFieldLink to this heading#デフォルトのウィジェット: SplitDateTimeWidget
空の値: None
正規化後の値: Python の datetime.datetime オブジェクトになります。
指定された値が datetime.datetime または特定の日時形式でフォーマットされた文字列であることを検証します。
エラーメッセージのキー: required, invalid, invalid_date, invalid_time
次の2つの省略可能な引数を取ります:
\n文字列を有効な datetime.date オブジェクトに変換する試行に使う表示形式のリストです。
input_date_formats 引数が提供されない場合、DateField のデフォルトの入力フォーマットが使用されます。
文字列を有効な datetime.time オブジェクトに変換しようとする際に使用されるフォーマットのリスト。
input_time_formats 引数が提供されない場合、TimeField のデフォルト入力フォーマットが使用されます。
モデル間のリレーションシップを表すために2つのフィールドが利用可能です： ModelChoiceField と ModelMultipleChoiceField です。これらのフィールドの両方には、フィールドの選択肢を作成するために使用される単一の queryset パラメータが必要です。フォーム検証時、これらのフィールドは、フォームの cleaned_data 辞書に一つのモデルオブジェクト ( ModelChoiceField の場合) または複数のモデルオブジェクト ( ModelMultipleChoiceField の場合) を配置します。
より複雑な使い方をする場合は、フォームフィールドを宣言する際に queryset=None を指定し、その後フォームの __init__() メソッド内で queryset を設定できます。
class FooMultipleChoiceForm(forms.Form):\n foo_select = forms.ModelMultipleChoiceField(queryset=None)\n\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.fields["foo_select"].queryset = ...\nModelChoiceField と ModelMultipleChoiceField には、選択肢を生成する際にクエリセットを繰り返すために使用されるクラスを指定する iterator 属性があります。詳細は、 リレーションシップの選択肢をイテレートする を参照してください。
ModelChoiceFieldLink to this heading#デフォルトのウィジェット: Select
空の値: None
正規化後の値: model インスタンスに正規化されます。
指定された id がクエリセット内に存在することを検証します。
エラーメッセージのキー: required, invalid_choice
invalid_choice エラーメッセージには %(value)s が含まれていることがあり、選択された選択肢に置き換えられます。
外部キーを表すのに適した単一のモデルオブジェクトの選択を許可します。ModelChoiceField のデフォルトウィジェットは、エントリーの数が増えると非実用的になることに注意してください。100項目以上には使用を避けるべきです。
引数が1つ必要です:
\nモデルオブジェクトの QuerySet で、フィールドの選択肢を導き出し、ユーザーの選択を検証するために使用されます。フォームがレンダリングされるときに評価されます。
ModelChoiceField は他にもいくつかのオプション引数を取ります:
デフォルトでは、ModelChoiceField が使用する <select> ウィジェットには、リストの先頭に空の選択肢が表示されます。このラベルのテキスト（デフォルトでは "---------"）を empty_label 属性で変更したり、empty_label を None に設定することで空のラベルを完全に無効にできます:
# A custom empty label\nfield1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")\n\n# No empty label\nfield2 = forms.ModelChoiceField(queryset=..., empty_label=None)\nModelChoiceField が必須でデフォルトの初期値を持っている場合や、widget が RadioSelect に設定されており blank 引数が False の場合には、 empty_label の値に関係なく空の選択肢は作成されません。
このオプション引数は、フィールドのウィジェットの選択肢の値として使用するフィールドを指定するために使用されます。選択された値が複数のオブジェクトに一致する可能性があるため、モデルにとって一意のフィールドであることを確認してください。デフォルトでは None に設定されており、この場合、各オブジェクトのプライマリキーが使用されます。たとえば：
# No custom to_field_name\nfield1 = forms.ModelChoiceField(queryset=...)\n上記によって、下記が得られます:
\n<select id="id_field1" name="field1">\n<option value="obj1.pk">Object1</option>\n<option value="obj2.pk">Object2</option>\n...\n</select>\nそして、:
\n# to_field_name provided\nfield2 = forms.ModelChoiceField(queryset=..., to_field_name="name")\n上記によって、下記が得られます:
\n<select id="id_field2" name="field2">\n<option value="obj1.name">Object1</option>\n<option value="obj2.name">Object2</option>\n...\n</select>\nRadioSelect ウィジェットを使用する場合、このオプションのブール引数は空の選択肢を作成するかどうかを決定します。デフォルトでは、blank は False で、空の選択肢は作成されません。
ModelChoiceField には、以下の属性もあります:
queryset からフィールド選択肢を生成するために使用されるイテレータクラス。デフォルトでは、ModelChoiceIterator です。
モデルの __str__() メソッドは、フィールドの選択肢で使用するためにオブジェクトの文字列表現を生成するために呼び出されます。カスタマイズした表現を提供するには、ModelChoiceField をサブクラス化して label_from_instance をオーバーライドします。このメソッドはモデルオブジェクトを受け取り、それを表すのに適した文字列を返すべきです。例えば：
from django.forms import ModelChoiceField\n\n\nclass MyModelChoiceField(ModelChoiceField):\n def label_from_instance(self, obj):\n return "My Object #%i" % obj.id\nModelMultipleChoiceFieldLink to this heading#デフォルトのウィジェット: SelectMultiple
空の値: 空の QuerySet (self.queryset.none())
正規化後の値: モデルインスタンスの QuerySet になります。
与えられた値のリスト内のすべてのIDがクエリセット内に存在することを検証します。
エラーメッセージのキー: required、 invalid_list、 invalid_choice、 invalid_pk_value
invalid_choice メッセージには %(value)s が含まれる可能性があり、invalid_pk_value メッセージには %(pk)s が含まれる可能性があります。これらは適切な値に置き換えられます。
一つまたは複数のモデルオブジェクトを選択できるようにし、多対多のリレーションシップを表すのに適しています。ModelChoiceField と同様に, label_from_instance を使用してオブジェクトの表現をカスタマイズできます。
引数が1つ必要です:
\nModelChoiceField.queryset と同じです。
1 つの省略可能な引数を取ります:
\nModelMultipleChoiceField には次の属性もあります:
ModelChoiceField.iterator と同じです。
デフォルトでは、ModelChoiceField と ModelMultipleChoiceField は、ModelChoiceIterator を使用して、フィールドの choices を生成します。
ModelChoiceIterator をイテレートすると、1つ目の value 要素として ModelChoiceIteratorValue インスタンスを含む2値タプルの選択肢が生成されます。 ModelChoiceIteratorValue は、選択値をラップし、カスタムウィジェットの実装で使用できる元のモデルインスタンスへの参照を保持します。たとえば、 <option> 要素に data-* attributes を追加するのに使用できます。
例として、以下のモデルを考えてみましょう:
\nfrom django.db import models\n\n\nclass Topping(models.Model):\n name = models.CharField(max_length=100)\n price = models.DecimalField(decimal_places=2, max_digits=6)\n\n def __str__(self):\n return self.name\n\n\nclass Pizza(models.Model):\n topping = models.ForeignKey(Topping, on_delete=models.CASCADE)\nSelect ウィジェットのサブクラスを使用して、各 <option> 要素の HTML 属性 data-price として Topping.price の値を含めることができます。
from django import forms\n\n\nclass ToppingSelect(forms.Select):\n def create_option(\n self, name, value, label, selected, index, subindex=None, attrs=None\n ):\n option = super().create_option(\n name, value, label, selected, index, subindex, attrs\n )\n if value:\n option["attrs"]["data-price"] = value.instance.price\n return option\n\n\nclass PizzaForm(forms.ModelForm):\n class Meta:\n model = Pizza\n fields = ["topping"]\n widgets = {"topping": ToppingSelect}\nこれにより、Pizza.topping 選択肢は以下のようにレンダリングされます:
<select id="id_topping" name="topping" required>\n<option value="" selected>---------</option>\n<option value="1" data-price="1.50">mushrooms</option>\n<option value="2" data-price="1.25">onions</option>\n<option value="3" data-price="1.75">peppers</option>\n<option value="4" data-price="2.00">pineapple</option>\n</select>\nより高度な使い方をする場合は、 ModelChoiceIterator をサブクラスにして、得られる2値タプルの選択肢をカスタマイズできます。
ModelChoiceIteratorLink to this heading#ModelChoiceField と ModelMultipleChoiceField の iterator 属性に割り当てられたデフォルトのクラスです。クエリセットから 2 タプルの選択肢を返すイテレータです。
引数が1つ必要です:
\nModelChoiceField または ModelMultipleChoiceField のインスタンスをイテレートして選択肢を生成します。
ModelChoiceIterator には、以下のメソッドがあります:
ChoiceField.choices で使用される (value, label) フォーマットの 2値タプルの選択肢を生成します。最初の value 要素は ModelChoiceIteratorValue インスタンスです。
ModelChoiceIteratorValueLink to this heading#2 つの引数が必要です:
\n選択肢の値です。HTMLの <option> 要素の value 属性のレンダリングに使用されます。
クエリセットのモデルインスタンス。このインスタンスはカスタム ChoiceWidget.create_option() の実装でアクセスし、レンダリングされるHTMLを調整できます。
ModelChoiceIteratorValue には次のメソッドがあります:
value を HTML でレンダリングするための文字列として返します。
組み込みの Field クラスが要件を満たさない場合は、カスタムの Field クラスを作成できます。これには、 django.forms.Field のサブクラスを作成します。唯一の要件は、 clean() メソッドを実装し、 __init__() メソッドが上述の基本的な引数 (required, label, initial, widget, help_text) を受け入れることです。
get_bound_field() をオーバーライドすることで、フィールドへのアクセス方法をカスタマイズすることもできます。