Form のインスタンスには、データセットに バインドされている (bound な) ものと バインドされていない (unbound な) ものがあります。
データセットに バインドされた Form インスタンスであれば、そのデータをバリデーションしたり、HTMLとしてフォームをレンダリングし、HTMLにデータを表示したりすることができます。
データセットに バインドされていない Form インスタンスでは、（検証するデータがないので）データをバリデーションすることはできませんが、空のフォームをHTMLとしてレンダリングできます。
バインドされていない Form のインスタンスを作成するには、クラスの初期化を行います。
>>> f = ContactForm()\nフォームにデータをバインドするには、辞書型のデータを Form クラスのコンストラクタの最初のパラメータとして渡します。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\nこの辞書では、キーは Form クラスの属性に対応するフィールド名を、値には検証したいデータを指定します。これらは通常文字列ですが、必ずしも文字列型でなくてもかまいません。後ほど解説しますが、渡すデータの型は、 Field に依存します。
実行時にバインドされたフォームインスタンスと、されていないフォームインスタンスを区別する必要があるときは、フォームの is_bound 属性の値を確認してください。
>>> f = ContactForm()\n>>> f.is_bound\nFalse\n>>> f = ContactForm({"subject": "hello"})\n>>> f.is_bound\nTrue\n空の辞書を渡すと、データが空の バインドされた フォームが作成されることに注意してください。
\n>>> f = ContactForm({})\n>>> f.is_bound\nTrue\nForm インスタンス内のデータを変更する方法はありません。 一度作成された Form インスタンスのデータは、その有無に関わらず変更不可能であると考えてください。もし Form インスタンスにバインドされたデータを変更したい場合や、バインドされていない Form インスタンスをデータにバインドしたい場合は、別の Form インスタンスを作成してください。
相互に関連のあるフィールドに対して独自のバリデーションを追加する必要がある場合、Form 上で clean() を実装してください。具体的な使用方法は 互いに依存するフィールドをクリーニングして検証する を参照してください。
Form オブジェクトの主なタスクは、データの検証です。バインドされた Form インスタンスでは、 is_valid() メソッドを呼び出して検証を実行し、データが有効であるかどうかを示すブール値を返します。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\nまずは無効なデータで試してみましょう。以下のケースでは、 subject は空白で（デフォルトではすべてのフィールドが必須なのでエラーになります）、 sender が有効なメールアドレスではありません。
>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "sender": "invalid email address",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\nerrors 属性にアクセスして、エラーメッセージの辞書を取得します。
>>> f.errors\n{'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}\nこの辞書では、キーはフィールド名であり、値はエラーメッセージを表す文字列のリストです。エラーメッセージがリストに格納されているのは、1つのフィールドに複数のエラーメッセージが出力される場合があるからです。
\nis_valid() を呼び出す前にも、 errors にアクセスできます。フォームのデータは、最初に is_valid() を呼び出すか、 errors にアクセスした時点で検証されます。
バリデーションのルーチンは、errors や call is_valid() を何度呼び出したとしても、最初の一度だけ呼び出されます。これは、バリデーションが副作用を持っている場合、その副作用は一度しか発生しないということを意味します。
フィールドとオリジナルの ValidationError インスタンスをマッピングする dict を返します。
>>> f.errors.as_data()\n{'sender': [ValidationError(['Enter a valid email address.'])],\n'subject': [ValidationError(['This field is required.'])]}\ncode によりエラーを特定する必要があるときはこのメソッドを使用してください。これによって、エラーメッセージの上書きや、エラーが存在するときのビューでの独自のロジックが作成できるようになります。独自のフォーマット (たとえば XML) でシリアライズするためにも使えます。たとえば、as_json() は as_data() を利用しています。
as_data() の必要性は、後方互換性に起因します。以前は ValidationError インスタンスは レンダリングされた エラーメッセージが Form.errors ディクショナリに追加されると同時に消失していました。できれば Form.errors が ValidationError インスタンスを保持し、as_ プレフィクスを伴うメソッドがエラーをレンダリングできるのが理想でしたが、Form.errors 内のレンダリングされたエラーメッセージを受け取る可能性があるコードを壊さないために、逆の実装にしなくてはなりませんでした。
エラーをJSONとしてシリアライズしたものを返します。
\n>>> f.errors.as_json()\n{"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],\n"subject": [{"message": "This field is required.", "code": "required"}]}\nデフォルトでは、as_json() は出力をエスケープしません。フォームビューへのAJAXリクエストなど、クライアントがレスポンスを解釈しエラーをページに挿入する場合には、クロスサイトスクリプティング攻撃の可能性を避けるために、クライアント側で結果をエスケープする必要があります。これはJavaScriptで、 element.textContent = errorText 、またはjQueryの $(el).text(errorText) (.html() 関数ではなく) を使用することで実行できます。
何らかの理由でクライアントサイドのエスケープを使いたくない場合は、 escape_html=True を設定すればエラーメッセージがエスケープされ、HTMLで直接使用できるようになります。
JSON にシリアライズできる形式のエラーを辞書として返します。 Form.errors.as_json() はシリアライズされた JSON を返しますが、これはシリアライズされる前のエラーデータを返します。
escape_html パラメータは、 Form.errors.as_json() で説明されているように動作します。
このメソッドは、Form.clean() メソッド内またはフォーム全体の外部から特定のフィールドにエラーを追加することを可能にします。たとえば、ビューから追加することもできます。
field 引数にはエラーを追加したいフィールド名を指定します。この値が None の場合、 Form.non_field_errors() によって返されるようなフィールドによらないエラーとして扱われます。
フォームエラーを定義するときのベストプラクティスとして、 error 引数は文字列もしくは、できれば ValidationError のインスタンスを指定します。フォームエラーの定義時のベストプラクティスについては、 ValidationError を発生させる を参照してください。
Form.add_error() は cleaned_data からフィールドを自動的に削除してしまうことに注意してください。
このメソッドは指定したフィールドが特定の code のエラーを持つか否かを真偽値で返します。code が None の場合、そのフィールドにエラーが一つもない場合に True を返します。
フィールドによらないエラー (non-field errors) の有無を確認したい場合は、field 引数に NON_FIELD_ERRORS を渡します。
このメソッドは、特定のフィールドに関連付けられていない Form.errors からのエラーリストを返します。これには、Form.clean() で発生した ValidationError や、Form.add_error(None, "...") を使用して追加されたエラーが含まれます。
フォームにデータがない場合、フォームの検証は意味をなしません。一応記載しておくと、バインドされていないフォームでは次のような結果になります。
\n>>> f = ContactForm()\n>>> f.is_valid()\nFalse\n>>> f.errors\n{}\ninitial を使うことで、実行時にフォームの初期値を設定できます。たとえば、 username フォームを埋めるのに、現在のセッションの username を使うことができます。
これを実現するには、 Form の初期化時に initial 引数を使用します。この引数には、フィールド名と初期値のマッピングした辞書を指定します。初期値を指定するフィールドだけを含めればよく、フォーム内のすべてのフィールドを含める必要はありません。以下に例を示します。
>>> f = ContactForm(initial={"subject": "Hi there!"})\nこれらの値はバインドされていないフォームに表示されるだけです。値が入力されなかった場合の、フォールバックされる値として使われることはありません。
\nField において initial を定義 した上で Form をインスタンス化するときに initial を指定した場合、後者の initial が優先されます。以下の例では、フィールドレベルとフォームインスタンスレベルの両方で initial が提供され、後者が優先されます。
>>> from django import forms\n>>> class CommentForm(forms.Form):\n... name = forms.CharField(initial="class")\n... url = forms.URLField()\n... comment = forms.CharField()\n...\n>>> f = CommentForm(initial={"name": "instance"}, auto_id=False)\n>>> print(f)\n<div>Name:<input type="text" name="name" value="instance" required></div>\n<div>Url:<input type="url" name="url" required></div>\n<div>Comment:<input type="text" name="comment" required></div>\nフォームフィールドの初期データを返します。データは、存在する場合は Form.initial から取得し、それ以外の場合は Field.initial を参照します。呼び出し可能な値は評価されます。
BoundField.initial はよりシンプルなインターフェースを持っているため、get_initial_for_field() よりも BoundField.initial の使用が推奨されます。また、get_initial_for_field() とは異なり、BoundField.initial はその値をキャッシュします。これは、戻り値が変わる可能性がある呼び出し可能オブジェクト (例: datetime.now や uuid.uuid4) を扱う場合に特に便利です。
>>> import uuid\n>>> class UUIDCommentForm(CommentForm):\n... identifier = forms.UUIDField(initial=uuid.uuid4)\n...\n>>> f = UUIDCommentForm()\n>>> f.get_initial_for_field(f.fields["identifier"], "identifier")\nUUID('972ca9e4-7bfe-4f5b-af7d-07b3aa306334')\n>>> f.get_initial_for_field(f.fields["identifier"], "identifier")\nUUID('1b411fab-844e-4dec-bd4f-e9b0495f04d0')\n>>> # Using BoundField.initial, for comparison\n>>> f["identifier"].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\n>>> f["identifier"].initial\nUUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')\nフォームデータが初期値から変更されたかどうかをチェックしたい場合は、 has_changed() メソッドを使います。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data, initial=data)\n>>> f.has_changed()\nFalse\nフォームが送信された場合、比較ができるようにフォームを再構築して元のデータを提供します:
\n>>> f = ContactForm(request.POST, initial=data)\n>>> f.has_changed()\nhas_changed() は、 request.POST が initial で提供されたデータと異なる場合、 True を返し、同じであれば False を返します。この結果は、それぞれのフィールドで Field.has_changed() を呼ぶことで計算されます。
changed_data 属性は、フォームにバインドされたデータ (ふつうは request.POST) の値が initial で提供されたものと異なるとき、そのフィールド名のリストを返します。データが変更されていない場合は、空のリストを返します。
>>> f = ContactForm(request.POST, initial=data)\n>>> if f.has_changed():\n... print("The following fields changed: %s" % ", ".join(f.changed_data))\n...\n>>> f.changed_data\n['subject', 'message']\nForm インスタンスのフィールドには、その fields 属性からアクセスできます。
>>> for row in f.fields.values():\n... print(row)\n...\n<django.forms.fields.CharField object at 0x7ffaac632510>\n<django.forms.fields.URLField object at 0x7ffaac632f90>\n<django.forms.fields.CharField object at 0x7ffaac3aa050>\n>>> f.fields["name"]\n<django.forms.fields.CharField object at 0x7ffaac6324d0>\nフィールドと BoundField 、 Form インスタンスを変更することで、フォーム内でのフィールドの表示方法を変更できます。
>>> f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\n>>> f["subject"].label = "Topic"\n>>> f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Topic:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\nbase_fields 属性を変更しないように注意してください。この変更は、同じPythonプロセス内のすべての後続の ContactForm インスタンスに影響を与えます。
>>> f.base_fields["subject"].label_suffix = "?"\n>>> another_f = CommentForm(auto_id=False)\n>>> f.as_div().split("</div>")[0]\n'<div><label for="id_subject">Subject?</label><input type="text" name="subject" maxlength="100" required id="id_subject">'\nForm クラスの各フィールドは、データの検証だけでなく、それを「クリーニング」する – すなわち、データを一貫した形式に正規化する役割も担っています。これは素晴らしい機能で、各フィールドにおいて、様々な形式で入力されるデータから、常に整合性のある出力を得ることができます。
たとえば、 DateField はインプットを Python の datetime.date オブジェクトに正規化します。たとえ '1994-07-15' という形式の文字列で渡そうが、 datetime.date オブジェクトを渡そうが、他の様々な形式で渡そうが、それが検証にパスする限り DateField はいつも datetime.date オブジェクトに正規化します。
Form インスタンスを作成し、データをセットして検証した後は、cleaned_data 属性を介してクリーンなデータにアクセスできます。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}\nCharField や EmailField といったテキストベースのフィールドは、入力を文字列に正規化します。暗黙的な文字エンコードの動作については、後のドキュメントでカバーします。
もしデータが検証に合格 しなかった 場合、 cleaned_data の辞書には有効なフィールドのみが含まれます。
>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "sender": "invalid email address",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nFalse\n>>> f.cleaned_data\n{'cc_myself': True, 'message': 'Hi there'}\nたとえ Form を定義する際に追加のデータを渡しても、 cleaned_data には Form で定義されたフィールドのキー のみ が含まれます。この例では ContactForm のコンストラクタに追加のフィールドを渡していますが、 cleaned_data にはフォームのフィールドのみが含まれます。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... "extra_field_1": "foo",\n... "extra_field_2": "bar",\n... "extra_field_3": "baz",\n... }\n>>> f = ContactForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data # Doesn't contain extra_field_1, etc.\n{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}\nForm の検証に合格した場合、 任意入力のフィールドのデータが一部含まれていなかったとしても、 すべての フィールドのキーと値が含まれています。この例では、渡したデータに nick_name フィールドの値は含まれていませんが、 cleaned_data には空の値が含まれています。
>>> from django import forms\n>>> class OptionalPersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n... nick_name = forms.CharField(required=False)\n...\n>>> data = {"first_name": "John", "last_name": "Lennon"}\n>>> f = OptionalPersonForm(data)\n>>> f.is_valid()\nTrue\n>>> f.cleaned_data\n{'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}\n上の例では、 cleaned_data 中の nick_name の値には空の文字列がセットされています。これは、 nick_name が CharField であり、 CharField は空の値を空の文字列として扱うからです。それぞれのフィールドタイプは、それぞれの 空の 値が何であるか知っています -- たとえば、 DateField では空の文字列の代わりに None です。それぞれのフィールドの挙動の完全な詳細は、あとの "Built-in Field classes" セクションにある "Empty value" ノートを見てください。
特定のいくつかの (フォーム名に基づく) フォームフィールドまたは (さまざまなフィールドの組み合わせを考えて) フォーム全体に対してのバリデーションを行うコードを書くこともできます。これについての詳細は、 フォームとフィールドのバリデーション を見てください。
\nForm オブジェクトの2番目のタスクは、自身をHTMLとしてレンダリングすることです。それを行うには print します。
>>> f = ContactForm()\n>>> print(f)\n<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject"></div>\n<div><label for="id_message">Message:</label><input type="text" name="message" required id="id_message"></div>\n<div><label for="id_sender">Sender:</label><input type="email" name="sender" required id="id_sender"></div>\n<div><label for="id_cc_myself">Cc myself:</label><input type="checkbox" name="cc_myself" id="id_cc_myself"></div>\nフォームがデータにバインドされている場合、HTMLの出力にはそのデータが適切に含まれます。たとえば、フィールドが <input type="text"> で表される場合、データは value 属性に含まれます。フィールドが <input type="checkbox"> で表される場合、HTMLには必要に応じて checked が含まれます。
>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data)\n>>> print(f)\n<div><label for="id_subject">Subject:</label><input type="text" name="subject" value="hello" maxlength="100" required id="id_subject"></div>\n<div><label for="id_message">Message:</label><input type="text" name="message" value="Hi there" required id="id_message"></div>\n<div><label for="id_sender">Sender:</label><input type="email" name="sender" value="foo@example.com" required id="id_sender"></div>\n<div><label for="id_cc_myself">Cc myself:</label><input type="checkbox" name="cc_myself" id="id_cc_myself" checked></div>\nこのデフォルトの出力は、各フィールドを <div> で囲みます。以下の点に注意してください。
柔軟性のために、出力には <form> と </form> のタグや <input type="submit"> のタグは含まれていません。これらは各自で追加するようにしてください。
それぞれのフィールドタイプはデフォルトの HTML 表現を持っています。 CharField は <input type="text"> で、 EmailField は <input type="email"> で表現され、BooleanField(null=False) は <input type="checkbox"> で表現されます。これらは単なる実用的なデフォルトであり、あるフィールドにどの HTML を使うかは、すぐ後で説明するウィジェットを使って指定できます。
HTML のそれぞれのタグの name は、 ContactForm クラスの属性名から直接とられます。
それぞれのフィールドのテキストラベル、たとえば 'Subject:', 'Message:' , 'Cc myself:' は、フィールド名のアンダースコアをスペースに変換し、頭文字を大文字に変換して生成されます。これらもまた単なる実用的なデフォルトです; 手動でラベルを指定することもできます。
それぞれのテキストラベルは HTML <label> タグで囲まれており、 id を通して適切なフォームフィールドを指しています。id は、フィールド名に 'id_' を前置することで生成されます。id 属性と <label> タグは、ベストプラクティスに従ってデフォルトでアウトプットにインクルードされますが、この挙動も変更できます。
出力はHTML5の構文を使用し、 <!DOCTYPE html> をターゲットにしています。例えば、 checked='checked' のXHTMLスタイルではなく checked のようなブール属性を使用します。
フォームを print するときは <div> がデフォルトの出力スタイルですが、独自のフォームテンプレートを使用して、出力をカスタマイズできます。このテンプレートは、サイト全体、フォームごと、またはインスタンスごとに設定できます。詳細は、 再利用可能なフォームテンプレート を参照してください。
フォームを print するときのデフォルトのレンダリングでは、次のメソッドと属性が使用されます。
template_nameLink to this heading#フォームを文字列に変換するときにレンダリングされるテンプレートの名前です。例えば、 print(form) やテンプレート内の {{ form }} などで使用されます。
デフォルトでは、レンダラーの form_template_name の値を返すプロパティです。特定のフォームクラスに対してそれを上書きするために、文字列型のテンプレート名として設定できます。
render()Link to this heading#renderメソッドは、 __str__ だけでなく、 Form.as_div() 、 Form.as_table() 、 Form.as_p() 、および Form.as_ul() メソッドによって呼び出されます。すべての引数はオプションであり、デフォルトは次のとおりです。
template_name: Form.template_name
context: Form.get_context() が返す値
renderer: Form.default_renderer が返す値
template_name を渡すことで、単一の呼び出しに使用されるテンプレートをカスタマイズできます。
get_context()Link to this heading#テンプレートをレンダリングするためのコンテキストを返します。
\n利用可能なコンテキストは次のとおりです。
\nform: バインドされたフォーム。
fields: 隠されたフィールドを除く、すべてのバインドされたフィールド。
hidden_fields: すべての隠されたバインドフィールド。
errors: フォームの非フィールド関連または非表示フィールド関連の全エラー。
template_name_labelLink to this heading#テンプレートは、 BoundField.label_tag()/legend_tag() を呼び出す際に使用されるフィールドの <label> をレンダリングするために使用されます。この属性をオーバーライドするか、デフォルトのテンプレートをオーバーライドすることで、フォームごとに変更できます。詳細については、 組み込みのフォームテンプレートをオーバーライドする も参照してください。
フォームの出力スタイルを変更する推奨されるアプローチは、サイト全体、フォームごと、またはインスタンスごとにカスタムフォームテンプレートを設定することです。例については、 再利用可能なフォームテンプレート を参照してください。
\n以下のヘルパー関数は後方互換性のために提供され、特定の template_name 値を渡す Form.render() へのプロキシです。
各ヘルパーは、適切なテンプレート名を指定する属性とフォームメソッドをペアにします。
\nas_div()Link to this heading#as_div() に使用されるテンプレート。デフォルト: 'django/forms/div.html'。
as_div() はフォームを一連の <div> 要素としてレンダリングし、各 <div> には以下のように一つのフィールドを含みます
>>> f = ContactForm()\n>>> f.as_div()\n… これは次のようなHTMLを生成します:
\n<div>\n<label for="id_subject">Subject:</label>\n<input type="text" name="subject" maxlength="100" required id="id_subject">\n</div>\n<div>\n<label for="id_message">Message:</label>\n<input type="text" name="message" required id="id_message">\n</div>\n<div>\n<label for="id_sender">Sender:</label>\n<input type="email" name="sender" required id="id_sender">\n</div>\n<div>\n<label for="id_cc_myself">Cc myself:</label>\n<input type="checkbox" name="cc_myself" id="id_cc_myself">\n</div>\nas_p()Link to this heading#as_p() に使われるテンプレート。デフォルト: 'django/forms/p.html' 。
as_p() は、フォームを一連の <p> タグとしてレンダリングし、各 <p> は1つのフィールドを含みます。
>>> f = ContactForm()\n>>> f.as_p()\n'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p>\\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p>\\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required></p>\\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>'\n>>> print(f.as_p())\n<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></p>\n<p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>\nas_ul()Link to this heading#as_ul() によって使用されるテンプレート。デフォルト: 'django/forms/ul.html' 。
as_ul() は、フォームを一連の <li> タグとしてレンダリングし、各 <li> には一つのフィールドが含まれます。柔軟性のために、<ul> に任意のHTML属性を指定できるように、 <ul> や </ul> は含まれ ません 。
>>> f = ContactForm()\n>>> f.as_ul()\n'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li>\\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li>\\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li>\\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>'\n>>> print(f.as_ul())\n<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself"></li>\nas_table()Link to this heading#as_table() によって使用されるテンプレート。デフォルト: 'django/forms/table.html' 。
as_table() はフォームを HTML の <table> としてレンダリングします:
>>> f = ContactForm()\n>>> f.as_table()\n'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>\\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>\\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>\\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>'\n>>> print(f)\n<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself"></td></tr>\n必須フォームやエラーのあるフォームの行を装飾するのはとても一般的です。たとえば、必須フォームの行は太字にしたり、エラーであれば赤色にしたくなることもあるでしょう。
\nForm クラスには、必須フォームやエラーのあるフォームに class 属性を追加するためのいくつかのフックを用意しています。具体的には、 Form.error_css_class 属性や Form.required_css_class 属性をセットします:
from django import forms\n\n\nclass ContactForm(forms.Form):\n error_css_class = "error"\n required_css_class = "required"\n\n # ... and the rest of your fields here\nそれを行ったら、必要に応じて行には "error" および/または "required" のクラスが与えられます。HTMLは以下のようになるでしょう:
>>> f = ContactForm(data)\n>>> print(f)\n<div class="required"><label for="id_subject" class="required">Subject:</label> ...\n<div class="required"><label for="id_message" class="required">Message:</label> ...\n<div class="required"><label for="id_sender" class="required">Sender:</label> ...\n<div><label for="id_cc_myself">Cc myself:</label> ...\n>>> f["subject"].label_tag()\n<label class="required" for="id_subject">Subject:</label>\n>>> f["subject"].legend_tag()\n<legend class="required" for="id_subject">Subject:</legend>\n>>> f["subject"].label_tag(attrs={"class": "foo"})\n<label for="id_subject" class="foo required">Subject:</label>\n>>> f["subject"].legend_tag(attrs={"class": "foo"})\n<legend for="id_subject" class="foo required">Subject:</legend>\nフォームの renderer を指定します。デフォルトは None で、 FORM_RENDERER 設定で指定されたデフォルトのレンダラーを使用することを意味します。
これはクラスの属性としてフォーム定義の際に設定するもしくは、Form.__init__() に renderer 引数を使うことで設定します。たとえば:
from django import forms\n\n\nclass MyForm(forms.Form):\n default_renderer = MyRenderer()\nもしくは:
\nform = MyForm(renderer=MyRenderer())\nas_p(), as_ul(), as_table() ショートカットでは、フィールドはフォームクラスで定義した順序で表示されます。たとえば、 ContactForm の例では、フィールドは subject, message, sender, cc_myself の順で定義されます。 HTML アウトプットの順序を変更するには、クラスの中で定義する順序を変えます。
順序のカスタマイズには、ほかにもいくつかの方法があります:
\nデフォルトでは Form.field_order=None で、これはフォームクラスでフィールドを定義した順番を保持します。field_order がフィールド名のリストである場合、指定されたリストに従ってフィールドが順序付けられ、残りのフィールドはデフォルトの順序に従って追加されます。リスト内の未知のフィールド名は無視されます。これにより、サブクラスでフィールドを None に設定して無効にしても、順序を再定義する必要がなくなります。
Form に Form.field_order 引数を使うことで、フィールドの順序をオーバーライドすることもできます。 Form の中で field_order が定義されていて、 かつ Form をインスタンス化する際に field_order をインクルードする場合、後者の field_order が優先されます。
また、 order_fields() に field_order と同様のフィールド名のリストを用いて、いつでもフィールドの順序を変更できます。
バインドされた Form オブジェクトをレンダリングすると、まだ実行されていない場合はフォームのバリデーションが自動的に実行され、HTML出力にはバリデーションエラーがフィールドの近くに <ul class="errorlist"> として含まれます。エラーメッセージの具体的な配置は使用している出力方法に依存します。
>>> data = {\n... "subject": "",\n... "message": "Hi there",\n... "sender": "invalid email address",\n... "cc_myself": True,\n... }\n>>> f = ContactForm(data, auto_id=False)\n>>> print(f)\n<div>Subject:\n <ul class="errorlist"><li>This field is required.</li></ul>\n <input type="text" name="subject" maxlength="100" required aria-invalid="true">\n</div>\n<div>Message:\n <textarea name="message" cols="40" rows="10" required>Hi there</textarea>\n</div>\n<div>Sender:\n <ul class="errorlist"><li>Enter a valid email address.</li></ul>\n <input type="email" name="sender" value="invalid email address" required aria-invalid="true">\n</div>\n<div>Cc myself:\n <input type="checkbox" name="cc_myself" checked>\n</div>\nデフォルトでは、フォームはバリデーションエラーを整形するために django.forms.utils.ErrorList を使用します。ErrorList はリストのようなオブジェクトであり、initlist はエラーのリストです。さらに、このクラスは以下の属性とメソッドを持っています。
エラーリストをレンダリングする際に使用されるCSSクラス。指定されたクラスは、デフォルトの errorlist クラスに追加されます。
ErrorList に使用する レンダラー を指定します。デフォルトでは None であり、これは FORM_RENDERER 設定で指定されたデフォルトのレンダラーを使用することを意味します。
__str__ や render() を呼び出した際に使用されるテンプレートの名前です。デフォルトでは、これは 'django/forms/errors/list/default.html' であり、'ul.html' テンプレートのプロキシとなります。
as_text() を呼び出す際に使用されるテンプレートの名前です。デフォルトでは、これは 'django/forms/errors/list/text.html' です。このテンプレートは、エラーを箇条書きのリストとしてレンダリングします。
as_ul() を呼び出すときに使用されるテンプレートの名前です。デフォルトではこれは 'django/forms/errors/list/ul.html' です。このテンプレートは、 error_class で定義された CSS クラスを持つ包括的な <ul> で <li> タグ内のエラーをレンダリングします。
テンプレート内のエラーのレンダリング用のコンテキストを返します。
\n利用可能なコンテキストは次のとおりです。
\nerrors: エラーのリスト。
error_class: CSSクラスの文字列。
renderメソッドは、 __str__ と as_ul() メソッドの両方から呼び出されます。
すべての引数はオプションで、デフォルト値は以下の通りです:
\ntemplate_name: template_name が返す値
context: get_context() が返す値
renderer: renderer が返す値
エラーリストを template_name_text で定義されたテンプレートを使用してレンダリングします。
template_name_ul で定義されたテンプレートを使用してエラーリストをレンダリングします。
エラーのレンダリングをカスタマイズしたい場合は、template_name 属性をオーバーライドするか、あるいはデフォルトテンプレートをオーバーライドすることによって達成できます。詳しくは 組み込みのフォームテンプレートをオーバーライドする も参照してください。
as_p(), as_ul(), as_table() メソッドはショートカットです -- フォームオブジェクトを表示する唯一の方法ではありません。
Form インスタンスのひとつのフィールドを HTML として表示したり、その属性にアクセスするのに使います。
このオブジェクトの __str__() メソッドは、このフィールドの HTML を表示します。
単一の BoundField を取得するには、フィールド名をキーとしてフォームに対して辞書参照構文を使用します。
>>> form = ContactForm()\n>>> print(form["subject"])\n<input id="id_subject" type="text" name="subject" maxlength="100" required>\n全ての BoundField オブジェクトを取得するには、フォームをイテレートします:
>>> form = ContactForm()\n>>> for boundfield in form:\n... print(boundfield)\n...\n<input id="id_subject" type="text" name="subject" maxlength="100" required>\n<input type="text" name="message" id="id_message" required>\n<input type="email" name="sender" id="id_sender" required>\n<input type="checkbox" name="cc_myself" id="id_cc_myself">\nフィールド固有の出力は、フォームオブジェクトの auto_id 設定を反映します:
>>> f = ContactForm(auto_id=False)\n>>> print(f["message"])\n<input type="text" name="message" required>\n>>> f = ContactForm(auto_id="id_%s")\n>>> print(f["message"])\n<input type="text" name="message" id="id_message" required>\nBoundField の属性一覧Link to this heading#この BoundField の HTML ID 属性。 Form.auto_id が False であれば、空の文字列を返します。
このプロパティは、ウィジェットの value_from_datadict() メソッドによって抽出された、この BoundField のデータを返します。もしデータが与えられていない場合は、 None を返します。
>>> unbound_form = ContactForm()\n>>> print(unbound_form["subject"].data)\nNone\n>>> bound_form = ContactForm(data={"subject": "My Subject"})\n>>> print(bound_form["subject"].data)\nMy Subject\nプリント時に HTML の <ul class="errorlist"> として表示される リストのようなオブジェクト です:
>>> data = {"subject": "hi", "message": "", "sender": "", "cc_myself": ""}\n>>> f = ContactForm(data, auto_id=False)\n>>> print(f["message"])\n<input type="text" name="message" required aria-invalid="true">\n>>> f["message"].errors\n['This field is required.']\n>>> print(f["message"].errors)\n<ul class="errorlist"><li>This field is required.</li></ul>\n>>> f["subject"].errors\n[]\n>>> print(f["subject"].errors)\n\n>>> str(f["subject"].errors)\n''\nエラーを含むフィールドをレンダリングする際、そのフィールドのウィジェットに aria-invalid="true" が設定され、スクリーンリーダーユーザーにエラーが存在することを示します。
この BoundField がラップしているフォームクラスの Field インスタンス。
この BoundField がバインドされている Form インスタンス。
フィールドの help_text 。
ウィジェットのHTMLの name 属性で使用される名前です。これは prefix の形式を考慮します。
このプロパティを使用して、このフィールドのIDをレンダリングします。例えば、(label_tag()/legend_tag() がこれを行ってくれるにも関わらず、) テンプレートで手動で <label> を構築している場合は:
<label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}\nデフォルトでは、これはフィールドの名前に id_ を前につけたものになります(上の例では "id_my_field")。フィールドのウィジェットの attrs を設定することで、IDを変更できます。例えば、以下のようにフィールドを宣言します:
my_field = forms.CharField(widget=forms.TextInput(attrs={"id": "myFIELD"}))\nそして、上記のテンプレートを使用すると、以下のように表示されます:
\n<label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" required>\nBoundField.initial を使用して、フォームフィールドの初期データを取得します。データは、存在する場合は Form.initial から、そうでなければ Field.initial から取得されます。呼び出し可能オブジェクトの値は評価されます。より多くの例については、 フォームの初期値 を参照してください。
BoundField.initial はその返り値をキャッシュします。これは、返り値が変わる可能性がある呼び出し可能オブジェクト(例: datetime.now や uuid.uuid4 など)を扱う際に特に便利です。
>>> from datetime import datetime\n>>> class DatedCommentForm(CommentForm):\n... created = forms.DateTimeField(initial=datetime.now)\n...\n>>> f = DatedCommentForm()\n>>> f["created"].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\n>>> f["created"].initial\ndatetime.datetime(2021, 7, 27, 9, 5, 54)\nget_initial_for_field() よりも BoundField.initial を使うことをお勧めします。
この BoundField のウィジェットが非表示の場合、 True を返します。
フィールドの label 。これは label_tag()/legend_tag() で使用されます。
このフィールドのフォーム上での名前:
\n>>> f = ContactForm()\n>>> print(f["subject"].name)\nsubject\n>>> print(f["message"].name)\nmessage\nBoundField.as_field_group() でレンダリングされるテンプレートの名前。
指定されていれば template_name の値を、そうでなければ field_template_name の値を返すプロパティ。
この BoundField ウィジェットの use_fieldset 属性の値を返します。
ラップされたフィールドのウィジェットのクラス名を小文字にして、末尾の input や widget を削除したものを返します。これは、ウィジェットのタイプに依存するレイアウトを持つフォームを構築する際に使用できます。例えば：
{% for field in form %}\n {% if field.widget_type == 'checkbox' %}\n # render one way\n {% else %}\n # render another way\n {% endif %}\n{% endfor %}\nBoundField のメソッドLink to this heading#フィールドを BoundField.render() を使用してデフォルト値でレンダリングし、設定されている場合はテンプレートの template_name 、そうでなければ field_template_name を使用して、BoundField をラベル、ヘルプテキスト、エラーとともにレンダリングします。
これを <input type="hidden"> として表現するためのHTMLの文字列を返します。
**kwargs は as_widget() に渡されます。
このメソッドは主に内部で使用されます。代わりにウィジェットを使用すべきです。
\n渡されたウィジェットをレンダリングして、attrs として渡された任意のHTML属性を追加してフィールドをレンダリングします。ウィジェットが指定されていない場合、フィールドのデフォルトウィジェットが使用されます。
only_initial は Django の内部で使用されるものであり、明示的に設定すべきではありません。
Djangoのレンダリングショートカットを利用すると、必須のフォームフィールドやエラーを含むフィールドを示すためのCSSクラスが使用されます。フォームを手動でレンダリングする場合は、 css_classes メソッドを使用してこれらのCSSクラスにアクセスできます。
>>> f = ContactForm(data={"message": ""})\n>>> f["message"].css_classes()\n'required'\nエラークラスと必須クラスが必要な場合に加えて、追加のクラスを提供したい場合は、引数としてそのクラスを提供できます:
\n>>> f = ContactForm(data={"message": ""})\n>>> f["message"].css_classes("foo bar")\n'foo bar required'\nレンダリングするためのテンプレートコンテキストを返します。利用可能なコンテキストは、バインドされたフィールドのインスタンスである field です。
フォームフィールドのラベルタグを、 Form.template_name_label で指定されたテンプレートを使用してレンダリングします。
利用可能なコンテキストは次のとおりです。
\nfield: この BoundField のインスタンス。
contents: デフォルトでは BoundField.label と Form.label_suffix (または設定されている場合は Field.label_suffix) の結合された文字列です。これは contents と label_suffix 引数によって上書きできます。
attrs: for、Form.required_css_class、および id を含む dict 。id はフィールドのウィジェット attrs または BoundField.auto_id によって生成されます。追加の属性は attrs 引数によって提供できます。
use_tag: ラベルに id がある場合は True、そうでない場合は False の真偽値です。False の場合、デフォルトテンプレートは tag を省略します。
tag: タグをカスタマイズするオプションの文字列で、デフォルトは label です。
フォームフィールドのラベルタグを別々にレンダリングするには、その label_tag() メソッドを呼び出します:
>>> f = ContactForm(data={"message": ""})\n>>> print(f["message"].label_tag())\n<label for="id_message">Message:</label>\nレンダリングをカスタマイズしたい場合は、 Form.template_name_label 属性をオーバーライドするか、一般的にはデフォルトのテンプレートをオーバーライドしてください。詳細は、 組み込みのフォームテンプレートをオーバーライドする も参照してください。
tag='legend' を指定して label_tag() を呼び出すと、ラベルを <legend> タグでレンダリングします。これは、 <label> よりも <legend> が適しているラジオボタンや複数のチェックボックスウィジェットをレンダリングする際に便利です。
renderメソッドは as_field_group によって呼び出されます。すべての引数はオプションであり、デフォルト値は次のとおりです。
template_name: BoundField.template_name
context: BoundField.get_context() が返す値
renderer: Form.default_renderer が返す値
template_name を渡すことで、単一の呼び出しに使用されるテンプレートをカスタマイズできます。
このメソッドを使用すると、Widget によってレンダリングされるフィールドの生の値をレンダリングできます:
>>> initial = {"subject": "welcome"}\n>>> unbound_form = ContactForm(initial=initial)\n>>> bound_form = ContactForm(data={"subject": "hi"}, initial=initial)\n>>> print(unbound_form["subject"].value())\nwelcome\n>>> print(bound_form["subject"].value())\nhi\nBoundField のカスタマイズLink to this heading#テンプレートでフォームフィールドに関する追加情報にアクセスする必要があり、 Field のサブクラスを使用するだけでは不十分な場合は、 BoundField のカスタマイズも検討してください。
カスタムフォームフィールドは get_bound_field() をオーバーライドできます:
Form のインスタンスとフィールドの名前を受け取ります。テンプレートでフィールドにアクセスする際に使用される返り値は、ほとんどの場合、 BoundField のサブクラスのインスタンスになります。
たとえば GPSCoordinatesField を持っていて、テンプレート内で座標に関する追加情報にアクセスしたい場合、以下のように実装できます:
class GPSCoordinatesBoundField(BoundField):\n @property\n def country(self):\n """\n Return the country the coordinates lie in or None if it can't be\n determined.\n """\n value = self.value()\n if value:\n return get_country_from_coordinates(value)\n else:\n return None\n\n\nclass GPSCoordinatesField(Field):\n def get_bound_field(self, form, field_name):\n return GPSCoordinatesBoundField(form, self, field_name)\nこれで、テンプレート内で {{ form.coordinates.country }} を使って国にアクセスできるようになりました。
FileField と ImageField フィールドを持つフォームを扱うのは、通常のフォームよりも少し複雑です。
まず、ファイルをアップロードするには、<form> 要素が enctype を "multipart/form-data" として正しく定義していることを確認する必要があります:
<form enctype="multipart/form-data" method="post" action="/foo/">\n次に、フォームを使用する際には、ファイルデータをバインドする必要があります。ファイルデータは通常のフォームデータとは別に扱われるため、フォームに FileField や ImageField が含まれている場合、フォームをバインドする際に第2引数を指定する必要があります。したがって、 ImageField を mugshot という名前で ContactForm に追加した場合、mugshot イメージを含むファイルデータをバインドする必要があります:
# Bound form with an image field\n>>> from django.core.files.uploadedfile import SimpleUploadedFile\n>>> data = {\n... "subject": "hello",\n... "message": "Hi there",\n... "sender": "foo@example.com",\n... "cc_myself": True,\n... }\n>>> file_data = {"mugshot": SimpleUploadedFile("face.jpg", b"file data")}\n>>> f = ContactFormWithMugshot(data, file_data)\n実際には、通常、（フォームデータのソースとして request.POST を使用するのと同様に、）ファイルデータのソースとして request.FILES を指定します:
# Bound form with an image field, data from the request\n>>> f = ContactFormWithMugshot(request.POST, request.FILES)\nバインドされていないフォームを作成する方法は、いつも通りです。フォームデータ と ファイルデータの両方を省略します。
\n# Unbound form with an image field\n>>> f = ContactFormWithMugshot()\n再利用可能なビューやテンプレートを書いている場合、フォームがマルチパートフォームかどうかを事前に知ることができないかもしれません。 is_multipart() メソッドは、フォームの送信にマルチパートエンコーディングが必要かどうかを教えてくれます:
>>> f = ContactFormWithMugshot()\n>>> f.is_multipart()\nTrue\nテンプレートでの使い方の例です:
\n{% if form.is_multipart %}\n <form enctype="multipart/form-data" method="post" action="/foo/">\n{% else %}\n <form method="post" action="/foo/">\n{% endif %}\n{{ form }}\n</form>\n複数の Form クラスがフィールドを共有している場合、サブクラス化を利用して冗長性を排除できます。
カスタム Form クラスをサブクラス化すると、親クラスのすべてのフィールドが含まれ、その後にサブクラスで定義したフィールドが続きます。
この例では、ContactFormWithPriority は ContactForm の全てのフィールドに加え、追加のフィールド priority を含んでいます。ContactForm のフィールドが最初に配置されます:
>>> class ContactFormWithPriority(ContactForm):\n... priority = forms.CharField()\n...\n>>> f = ContactFormWithPriority(auto_id=False)\n>>> print(f)\n<div>Subject:<input type="text" name="subject" maxlength="100" required></div>\n<div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div>\n<div>Sender:<input type="email" name="sender" required></div>\n<div>Cc myself:<input type="checkbox" name="cc_myself"></div>\n<div>Priority:<input type="text" name="priority" required></div>\n複数のフォームをサブクラス化し、フォームをミックスインとして扱うことができます。この例では、BeatleForm が PersonForm と InstrumentForm （この順番で）の両方をサブクラス化し、そのフィールドリストは親クラスのフィールドを含んでいます:
>>> from django import forms\n>>> class PersonForm(forms.Form):\n... first_name = forms.CharField()\n... last_name = forms.CharField()\n...\n>>> class InstrumentForm(forms.Form):\n... instrument = forms.CharField()\n...\n>>> class BeatleForm(InstrumentForm, PersonForm):\n... haircut_type = forms.CharField()\n...\n>>> b = BeatleForm(auto_id=False)\n>>> print(b)\n<div>First name:<input type="text" name="first_name" required></div>\n<div>Last name:<input type="text" name="last_name" required></div>\n<div>Instrument:<input type="text" name="instrument" required></div>\n<div>Haircut type:<input type="text" name="haircut_type" required></div>\n親クラスから継承された Field を、サブクラスでフィールドの名前を None に設定することで、宣言的にフィールドを削除できます。たとえば次のようにします:
>>> from django import forms\n\n>>> class ParentForm(forms.Form):\n... name = forms.CharField()\n... age = forms.IntegerField()\n...\n\n>>> class ChildForm(ParentForm):\n... name = None\n...\n\n>>> list(ChildForm().fields)\n['age']\n1 つの <form> タグの中に複数の Django フォームを配置できます。各 Form に独自の名前空間を与えるには、prefix キーワード引数を使用します。
>>> mother = PersonForm(prefix="mother")\n>>> father = PersonForm(prefix="father")\n>>> print(mother)\n<div><label for="id_mother-first_name">First name:</label><input type="text" name="mother-first_name" required id="id_mother-first_name"></div>\n<div><label for="id_mother-last_name">Last name:</label><input type="text" name="mother-last_name" required id="id_mother-last_name"></div>\n>>> print(father)\n<div><label for="id_father-first_name">First name:</label><input type="text" name="father-first_name" required id="id_father-first_name"></div>\n<div><label for="id_father-last_name">Last name:</label><input type="text" name="father-last_name" required id="id_father-last_name"></div>\nプレフィックスは、フォームクラスにも指定できます：
\n>>> class PersonForm(forms.Form):\n... ...\n... prefix = "person"\n...\n