フォーム API¶

このドキュメントについて

このドキュメントでは、Django のフォーム API の詳細について説明します。このドキュメントを読む前にフォームについての概要を読むことをおすすめします。

バインドされた (bound) フォームとバインドされていない (unbound) フォーム¶

Form のインスタンスには、データセットに バインドされている (bound な) ものと バインドされていない (unbound な) ものがあります。

データセットに バインドされた Form インスタンスであれば、そのデータをバリデーションしたり、HTMLとしてフォームをレンダリングし、HTMLにデータを表示したりすることができます。
データセットに バインドされていない Form インスタンスでは、（検証するデータがないので）データをバリデーションすることはできませんが、空のフォームをHTMLとしてレンダリングできます。

class Form[ソース]¶

バインドされていない Form のインスタンスを作成するには、クラスの初期化を行います。

>>> f = ContactForm()

フォームにデータをバインドするには、辞書型のデータを Form クラスのコンストラクタの最初のパラメータとして渡します。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> f = ContactForm(data)

この辞書では、キーは Form クラスの属性に対応するフィールド名を、値には検証したいデータを指定します。これらは通常文字列ですが、必ずしも文字列型でなくてもかまいません。後ほど解説しますが、渡すデータの型は、 Field に依存します。

Form.is_bound¶

実行時にバインドされたフォームインスタンスと、されていないフォームインスタンスを区別する必要があるときは、フォームの is_bound 属性の値を確認してください。

>>> f = ContactForm()
>>> f.is_bound
False
>>> f = ContactForm({"subject": "hello"})
>>> f.is_bound
True

空の辞書を渡すと、データが空の バインドされた フォームが作成されることに注意してください。

>>> f = ContactForm({})
>>> f.is_bound
True

Form インスタンス内のデータを変更する方法はありません。一度作成された Form インスタンスのデータは、その有無に関わらず変更不可能であると考えてください。もし Form インスタンスにバインドされたデータを変更したい場合や、バインドされていない Form インスタンスをデータにバインドしたい場合は、別の Form インスタンスを作成してください。

フォームをデータの検証に使用する¶

Form.clean()¶

相互に関連のあるフィールドに対して独自のバリデーションを追加する必要がある場合、Form 上で clean() を実装してください。具体的な使用方法は互いに依存するフィールドをクリーニングして検証するを参照してください。

Form.is_valid()¶

Form オブジェクトの主なタスクは、データの検証です。バインドされた Form インスタンスでは、 is_valid() メソッドを呼び出して検証を実行し、データが有効であるかどうかを示すブール値を返します。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> f = ContactForm(data)
>>> f.is_valid()
True

Let's try with some invalid data. In this case, subject is blank (an error, because all fields are required by default) and contact_email is not a valid email address:

>>> data = {
...     "subject": "",
...     "message": "Hi there",
...     "contact_email": "invalid email address",
...     "urgent": True,
... }
>>> f = ContactForm(data)
>>> f.is_valid()
False

Form.errors¶

errors 属性にアクセスして、エラーメッセージの辞書を取得します。

>>> f.errors
{'subject': ['This field is required.'],
 'contact_email': ['Enter a valid email address.']}

この辞書では、キーはフィールド名であり、値はエラーメッセージを表す文字列のリストです。エラーメッセージがリストに格納されているのは、1つのフィールドに複数のエラーメッセージが出力される場合があるからです。

is_valid() を呼び出す前にも、 errors にアクセスできます。フォームのデータは、最初に is_valid() を呼び出すか、 errors にアクセスした時点で検証されます。

バリデーションのルーチンは、errors や call is_valid() を何度呼び出したとしても、最初の一度だけ呼び出されます。これは、バリデーションが副作用を持っている場合、その副作用は一度しか発生しないということを意味します。

Form.errors.as_data()¶

フィールドとオリジナルの ValidationError インスタンスをマッピングする dict を返します。

>>> f.errors.as_data()
{'subject': [ValidationError(['This field is required.'])],
 'contact_email': [ValidationError(['Enter a valid email address.'])]}

Use this method anytime you need to identify an error by its code. This enables things like rewriting the error's message or writing custom logic in a view when a given error is present. It can also be used to serialize the errors in a custom format (e.g. XML); for instance, as_json() relies on as_data().

as_data() の必要性は、後方互換性に起因します。以前は ValidationError インスタンスは レンダリングされた エラーメッセージが Form.errors ディクショナリに追加されると同時に消失していました。できれば Form.errors が ValidationError インスタンスを保持し、as_ プレフィクスを伴うメソッドがエラーをレンダリングできるのが理想でしたが、Form.errors 内のレンダリングされたエラーメッセージを受け取る可能性があるコードを壊さないために、逆の実装にしなくてはなりませんでした。

Form.errors.as_json(escape_html=False)¶

Returns a string with the errors serialized as JSON.

>>> f.errors.as_json()
'{"subject": [{"message": "This field is required.", "code": "required"}],
 "contact_email": [{"message": "Enter a valid email address.", "code": "invalid"}]}'

デフォルトでは、as_json() は出力をエスケープしません。フォームビューへのAJAXリクエストなど、クライアントがレスポンスを解釈しエラーをページに挿入する場合には、クロスサイトスクリプティング攻撃の可能性を避けるために、クライアント側で結果をエスケープする必要があります。これはJavaScriptで、 element.textContent = errorText 、またはjQueryの $(el).text(errorText) (.html() 関数ではなく) を使用することで実行できます。

何らかの理由でクライアントサイドのエスケープを使いたくない場合は、 escape_html=True を設定すればエラーメッセージがエスケープされ、HTMLで直接使用できるようになります。

Form.errors.get_json_data(escape_html=False)¶

Returns the errors as a dictionary suitable for serializing to JSON. Form.errors.as_json() returns serialized JSON, while this returns the error data before it's serialized.

The escape_html parameter behaves as described in Form.errors.as_json().

Form.add_error(field, error)¶

このメソッドは、Form.clean() メソッド内またはフォーム全体の外部から特定のフィールドにエラーを追加することを可能にします。たとえば、ビューから追加することもできます。

field 引数にはエラーを追加したいフィールド名を指定します。この値が None の場合、 Form.non_field_errors() によって返されるようなフィールドによらないエラーとして扱われます。

フォームエラーを定義するときのベストプラクティスとして、 error 引数は文字列もしくは、できれば ValidationError のインスタンスを指定します。フォームエラーの定義時のベストプラクティスについては、 ValidationError を発生させるを参照してください。

Form.add_error() は cleaned_data からフィールドを自動的に削除してしまうことに注意してください。

Form.has_error(field, code=None)¶

このメソッドは指定したフィールドが特定の code のエラーを持つか否かを真偽値で返します。code が None の場合、そのフィールドにエラーが一つもない場合に True を返します。

フィールドによらないエラー (non-field errors) の有無を確認したい場合は、field 引数に NON_FIELD_ERRORS を渡します。

Form.non_field_errors()¶

このメソッドは、特定のフィールドに関連付けられていない Form.errors からのエラーリストを返します。これには、Form.clean() で発生した ValidationError や、Form.add_error(None, "...") を使用して追加されたエラーが含まれます。

バインドされていないフォームの動作¶

フォームにデータがない場合、フォームの検証は意味をなしません。一応記載しておくと、バインドされていないフォームでは次のような結果になります。

>>> f = ContactForm()
>>> f.is_valid()
False
>>> f.errors
{}

フォームの初期値¶

Form.initial¶

initial を使うことで、実行時にフォームの初期値を設定できます。たとえば、 username フォームを埋めるのに、現在のセッションの username を使うことができます。

これを実現するには、 Form の初期化時に initial 引数を使用します。この引数には、フィールド名と初期値のマッピングした辞書を指定します。初期値を指定するフィールドだけを含めればよく、フォーム内のすべてのフィールドを含める必要はありません。以下に例を示します。

>>> f = ContactForm(initial={"subject": "Hi there!"})

これらの値はバインドされていないフォームに表示されるだけです。値が入力されなかった場合の、フォールバックされる値として使われることはありません。

Field において initial を定義 した上で Form をインスタンス化するときに initial を指定した場合、後者の initial が優先されます。以下の例では、フィールドレベルとフォームインスタンスレベルの両方で initial が提供され、後者が優先されます。

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="class")
...     url = forms.URLField()
...     comment = forms.CharField()
...
>>> f = CommentForm(initial={"name": "instance"}, auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="instance" required></div>
<div>Url:<input type="url" name="url" required></div>
<div>Comment:<input type="text" name="comment" required></div>

Form.get_initial_for_field(field, field_name)¶

フォームフィールドの初期データを返します。データは、存在する場合は Form.initial から取得し、それ以外の場合は Field.initial を参照します。呼び出し可能な値は評価されます。

It is recommended to use BoundField.initial over get_initial_for_field() because BoundField.initial has a simpler interface. Also, unlike get_initial_for_field(), BoundField.initial caches its values. This is useful especially when dealing with callables whose return values can change (e.g. datetime.now or uuid.uuid4):

>>> import uuid
>>> class UUIDCommentForm(CommentForm):
...     identifier = forms.UUIDField(initial=uuid.uuid4)
...
>>> f = UUIDCommentForm()
>>> f.get_initial_for_field(f.fields["identifier"], "identifier")
UUID('972ca9e4-7bfe-4f5b-af7d-07b3aa306334')
>>> f.get_initial_for_field(f.fields["identifier"], "identifier")
UUID('1b411fab-844e-4dec-bd4f-e9b0495f04d0')
>>> # Using BoundField.initial, for comparison
>>> f["identifier"].initial
UUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')
>>> f["identifier"].initial
UUID('28a09c59-5f00-4ed9-9179-a3b074fa9c30')

どのフォームデータが変更されたかをチェックする¶

Form.has_changed()¶

フォームデータが初期値から変更されたかどうかをチェックしたい場合は、 has_changed() メソッドを使います。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> f = ContactForm(data, initial=data)
>>> f.has_changed()
False

フォームが送信された場合、比較ができるようにフォームを再構築して元のデータを提供します:

>>> f = ContactForm(request.POST, initial=data)
>>> f.has_changed()
True

has_changed() は、 request.POST が initial で提供されたデータと異なる場合、 True を返し、同じであれば False を返します。この結果は、それぞれのフィールドで Field.has_changed() を呼ぶことで計算されます。

Form.changed_data¶

changed_data 属性は、フォームにバインドされたデータ (ふつうは request.POST) の値が initial で提供されたものと異なるとき、そのフィールド名のリストを返します。データが変更されていない場合は、空のリストを返します。

>>> f = ContactForm(request.POST, initial=data)
>>> f.changed_data
['subject', 'message']

フォームからフィールドにアクセスする¶

Form.fields¶

Form インスタンスのフィールドには、その fields 属性からアクセスできます。

>>> for row in f.fields.values():
...     print(row)
...
<django.forms.fields.CharField object at 0x7ffaac632510>
<django.forms.fields.URLField object at 0x7ffaac632f90>
<django.forms.fields.CharField object at 0x7ffaac3aa050>
>>> f.fields["name"]
<django.forms.fields.CharField object at 0x7ffaac6324d0>

フィールドと BoundField 、 Form インスタンスを変更することで、フォーム内でのフィールドの表示方法を変更できます。

>>> f.as_div().split("</div>")[0]
'<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'
>>> f["subject"].label = "Topic"
>>> f.as_div().split("</div>")[0]
'<div><label for="id_subject">Topic:</label><input type="text" name="subject" maxlength="100" required id="id_subject">'

base_fields 属性を変更しないように注意してください。この変更は、同じPythonプロセス内のすべての後続の ContactForm インスタンスに影響を与えます。

>>> f.base_fields["subject"].label_suffix = "?"
>>> another_f = ContactForm(auto_id=False)
>>> another_f.as_div().split("</div>")[0]
'<div><label for="id_subject">Subject?</label><input type="text" name="subject" maxlength="100" required id="id_subject">'

"clean" なデータにアクセスする¶

Form.cleaned_data¶

Form クラスの各フィールドは、データの検証だけでなく、それを「クリーニング」する – すなわち、データを一貫した形式に正規化する役割も担っています。これは素晴らしい機能で、各フィールドにおいて、様々な形式で入力されるデータから、常に整合性のある出力を得ることができます。

たとえば、 DateField はインプットを Python の datetime.date オブジェクトに正規化します。たとえ '1994-07-15' という形式の文字列で渡そうが、 datetime.date オブジェクトを渡そうが、他の様々な形式で渡そうが、それが検証にパスする限り DateField はいつも datetime.date オブジェクトに正規化します。

Form インスタンスを作成し、データをセットして検証した後は、cleaned_data 属性を介してクリーンなデータにアクセスできます。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> f = ContactForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data
{'subject': 'hello', 'message': 'Hi there', 'contact_email': 'foo@example.com', 'urgent': True}

CharField や EmailField といったテキストベースのフィールドは、入力を文字列に正規化します。暗黙的な文字エンコードの動作については、後のドキュメントでカバーします。

もしデータが検証に合格 しなかった 場合、 cleaned_data の辞書には有効なフィールドのみが含まれます。

>>> data = {
...     "subject": "",
...     "message": "Hi there",
...     "contact_email": "invalid email address",
...     "urgent": True,
... }
>>> f = ContactForm(data)
>>> f.is_valid()
False
>>> f.cleaned_data
{'message': 'Hi there', 'urgent': True}

たとえ Form を定義する際に追加のデータを渡しても、 cleaned_data には Form で定義されたフィールドのキーのみが含まれます。この例では ContactForm のコンストラクタに追加のフィールドを渡していますが、 cleaned_data にはフォームのフィールドのみが含まれます。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
...     "extra_field_1": "foo",
...     "extra_field_2": "bar",
...     "extra_field_3": "baz",
... }
>>> f = ContactForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data  # Doesn't contain extra_field_1, etc.
{'subject': 'hello', 'message': 'Hi there', 'contact_email': 'foo@example.com', 'urgent': True}

When the Form is valid, cleaned_data will include a key and value for all its fields, even if the data didn't include a value for some optional fields. In this example, the data dictionary doesn't include a value for the nickname field, but cleaned_data includes it, with an empty value:

>>> from django import forms
>>> class OptionalPersonForm(forms.Form):
...     first_name = forms.CharField()
...     last_name = forms.CharField()
...     nickname = forms.CharField(required=False)
...
>>> data = {"first_name": "John", "last_name": "Lennon"}
>>> f = OptionalPersonForm(data)
>>> f.is_valid()
True
>>> f.cleaned_data
{'first_name': 'John', 'last_name': 'Lennon', 'nickname': ''}

In this above example, the cleaned_data value for nickname is set to an empty string, because nickname is CharField, and CharFields treat empty values as an empty string. Each field type knows what its "blank" value is -- e.g., for DateField, it's None instead of the empty string. For full details on each field's behavior in this case, see the "Empty value" note for each field in the ビルトインの Field クラス section below.

特定のいくつかの (フォーム名に基づく) フォームフィールドまたは (さまざまなフィールドの組み合わせを考えて) フォーム全体に対してのバリデーションを行うコードを書くこともできます。これについての詳細は、フォームとフィールドのバリデーションを見てください。

フォームをHTMLとしてアウトプットする¶

Form オブジェクトの2番目のタスクは、自身をHTMLとしてレンダリングすることです。それを行うには print します。

>>> f = ContactForm()
>>> print(f)
<div><label for="id_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_subject"></div>
<div><label for="id_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_message"></textarea></div>
<div><label for="id_contact_email">Contact email:</label><input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></div>
<div><label for="id_urgent">Urgent:</label><input type="checkbox" name="urgent" id="id_urgent"></div>

フォームがデータにバインドされている場合、HTMLの出力にはそのデータが適切に含まれます。たとえば、フィールドが <input type="text"> で表される場合、データは value 属性に含まれます。フィールドが <input type="checkbox"> で表される場合、HTMLには必要に応じて checked が含まれます。

>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> f = ContactForm(data)
>>> print(f)
<div><label for="id_subject">Subject:</label><input type="text" name="subject" value="hello" maxlength="100" required id="id_subject"></div>
<div><label for="id_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_message">Hi there</textarea></div>
<div><label for="id_contact_email">Contact email:</label><input type="email" name="contact_email" value="foo@example.com" maxlength="320" required id="id_contact_email"></div>
<div><label for="id_urgent">Urgent:</label><input type="checkbox" name="urgent" id="id_urgent" checked></div>

このデフォルトの出力は、各フィールドを <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 クラスの属性名から直接とられます。
The text label for each field -- e.g. 'Subject:', 'Message:' and 'Contact email:' is generated from the field name by converting all underscores to spaces and upper-casing the first letter. Again, note these are merely sensible defaults; you can also specify labels manually.
それぞれのテキストラベルは HTML <label> タグで囲まれており、 id を通して適切なフォームフィールドを指しています。id は、フィールド名に 'id_' を前置することで生成されます。id 属性と <label> タグは、ベストプラクティスに従ってデフォルトでアウトプットにインクルードされますが、この挙動も変更できます。
出力はHTML5の構文を使用し、 <!DOCTYPE html> をターゲットにしています。例えば、 checked='checked' のXHTMLスタイルではなく checked のようなブール属性を使用します。

フォームを print するときは <div> がデフォルトの出力スタイルですが、独自のフォームテンプレートを使用して、出力をカスタマイズできます。このテンプレートは、サイト全体、フォームごと、またはインスタンスごとに設定できます。詳細は、再利用可能なフォームテンプレートを参照してください。

デフォルトのレンダリング¶

フォームを print するときのデフォルトのレンダリングでは、次のメソッドと属性が使用されます。

`template_name`¶

Form.template_name¶

フォームを文字列に変換するときにレンダリングされるテンプレートの名前です。例えば、 print(form) やテンプレート内の {{ form }} などで使用されます。

デフォルトでは、レンダラーの form_template_name の値を返すプロパティです。特定のフォームクラスに対してそれを上書きするために、文字列型のテンプレート名として設定できます。

`render()`¶

Form.render(template_name=None, context=None, renderer=None)¶

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()`¶

Form.get_context()¶

テンプレートをレンダリングするためのコンテキストを返します。

利用可能なコンテキストは次のとおりです。

form: バインドされたフォーム。
fields: 隠されたフィールドを除く、すべてのバインドされたフィールド。
hidden_fields: すべての隠されたバインドフィールド。
errors: フォームの非フィールド関連または非表示フィールド関連の全エラー。

`template_name_label`¶

Form.template_name_label¶

テンプレートは、 BoundField.label_tag()/legend_tag() を呼び出す際に使用されるフィールドの <label> をレンダリングするために使用されます。この属性をオーバーライドするか、デフォルトのテンプレートをオーバーライドすることで、フォームごとに変更できます。詳細については、組み込みのフォームテンプレートをオーバーライドするも参照してください。

出力スタイル¶

フォームの出力スタイルを変更する推奨されるアプローチは、サイト全体、フォームごと、またはインスタンスごとにカスタムフォームテンプレートを設定することです。例については、再利用可能なフォームテンプレートを参照してください。

以下のヘルパー関数は後方互換性のために提供され、特定の template_name 値を渡す Form.render() へのプロキシです。

注釈

フレームワークが提供するテンプレートと出力スタイルのうち、デフォルトの as_div() は as_p(), as_table(), as_ul() バージョンよりも推奨されます。なぜなら、このテンプレートは <fieldset> と <legend> を実装しており、関連する入力をグループ化し、スクリーンリーダーユーザがナビゲートしやすいからです。

各ヘルパーは、適切なテンプレート名を指定する属性とフォームメソッドをペアにします。

`as_div()`¶

Form.template_name_div¶

as_div() に使用されるテンプレート。デフォルト: 'django/forms/div.html'。

Form.as_div()¶

as_div() はフォームを一連の <div> 要素としてレンダリングし、各 <div> には以下のように一つのフィールドを含みます

>>> f = ContactForm()
>>> f.as_div()

... gives HTML like:

<div>
<label for="id_subject">Subject:</label>
<input type="text" name="subject" maxlength="100" required id="id_subject">
</div>
<div>
<label for="id_message">Message:</label>
<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>
</div>
<div>
<label for="id_contact_email">Contact email:</label>
<input type="email" name="contact_email" required id="id_contact_email">
</div>
<div>
<label for="id_urgent">Urgent:</label>
<input type="checkbox" name="urgent" id="id_urgent">
</div>

`as_p()`¶

Form.template_name_p¶

as_p() に使われるテンプレート。デフォルト: 'django/forms/p.html' 。

Form.as_p()¶

as_p() は、フォームを一連の <p> タグとしてレンダリングし、各 <p> は1つのフィールドを含みます。

>>> f = ContactForm()
>>> f.as_p()

... gives HTML like:

<p><label for="id_subject">Subject:</label> <input type="text" name="subject" maxlength="100" required id="id_subject"></p>
<p><label for="id_message">Message:</label> <textarea name="message" cols="40" rows="10" required id="id_message"></textarea></p>
<p><label for="id_contact_email">Contact email:</label> <input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></p>
<p><label for="id_urgent">Urgent:</label> <input type="checkbox" name="urgent" id="id_urgent"></p>

`as_ul()`¶

Form.template_name_ul¶

as_ul() によって使用されるテンプレート。デフォルト: 'django/forms/ul.html' 。

Form.as_ul()¶

as_ul() は、フォームを一連の <li> タグとしてレンダリングし、各 <li> には一つのフィールドが含まれます。柔軟性のために、<ul> に任意のHTML属性を指定できるように、 <ul> や </ul> は含まれ ません 。

>>> f = ContactForm()
>>> f.as_ul()

... gives HTML like:

<li><label for="id_subject">Subject:</label> <input type="text" name="subject" maxlength="100" required id="id_subject"></li>
<li><label for="id_message">Message:</label> <textarea name="message" cols="40" rows="10" required id="id_message"></textarea></li>
<li><label for="id_contact_email">Contact email:</label> <input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></li>
<li><label for="id_urgent">Urgent:</label> <input type="checkbox" name="urgent" id="id_urgent"></li>

`as_table()`¶

Form.template_name_table¶

as_table() によって使用されるテンプレート。デフォルト: 'django/forms/table.html' 。

Form.as_table()¶

as_table() はフォームを HTML の <table> としてレンダリングします:

>>> f = ContactForm()
>>> f.as_table()

... gives HTML like:

<tr><th><label for="id_subject">Subject:</label></th><td><input type="text" name="subject" maxlength="100" required id="id_subject"></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><textarea name="message" cols="40" rows="10" required id="id_message"></textarea></td></tr>
<tr><th><label for="id_contact_email">Contact email:</label></th><td><input type="email" name="contact_email" maxlength="320" required id="id_contact_email"></td></tr>
<tr><th><label for="id_urgent">Urgent:</label></th><td><input type="checkbox" name="urgent" id="id_urgent"></td></tr>

必須フォームとエラーのあるフォームのスタイリング¶

Form.error_css_class¶

Form.required_css_class¶

必須フォームやエラーのあるフォームの行を装飾するのはとても一般的です。たとえば、必須フォームの行は太字にしたり、エラーであれば赤色にしたくなることもあるでしょう。

Form クラスには、必須フォームやエラーのあるフォームに class 属性を追加するためのいくつかのフックを用意しています。具体的には、 Form.error_css_class 属性や Form.required_css_class 属性をセットします:

from django import forms


class ContactForm(forms.Form):
    error_css_class = "error"
    required_css_class = "required"

    # ... and the rest of your fields here

それを行ったら、必要に応じて行には "error" および/または "required" のクラスが与えられます。HTMLは以下のようになるでしょう:

>>> f = ContactForm(data)
>>> print(f)
<div class="required"><label for="id_subject" class="required">Subject:</label> ...
<div class="required"><label for="id_message" class="required">Message:</label> ...
<div class="required"><label for="id_contact_email" class="required">Contact email:</label> ...
<div><label for="id_urgent">Urgent:</label> ...
>>> f["subject"].label_tag()
<label class="required" for="id_subject">Subject:</label>
>>> f["subject"].legend_tag()
<legend class="required" for="id_subject">Subject:</legend>
>>> f["subject"].label_tag(attrs={"class": "foo"})
<label for="id_subject" class="foo required">Subject:</label>
>>> f["subject"].legend_tag(attrs={"class": "foo"})
<legend for="id_subject" class="foo required">Subject:</legend>

カスタム BoundField を使用すれば、さらにフォーム行のレンダリングをカスタマイズすることができます。

フォーム要素の HTML `id` 属性と `<label>` タグを設定する¶

Form.auto_id¶

デフォルトでは、フォームをレンダリングするメソッドは次のものを含みます:

フォーム要素に対する HTML id 属性。
ラベルの前後に、フォームに対応する <label> タグ。 HTML の <label> タグは、どのラベルテキストがどのフォーム要素と関係しているかを指定します。この小さな修飾によって、補助的なデバイスでフォームにアクセスするのが便利になります。いつも <label> タグを使うようにするとよいでしょう。

The id attribute values are generated by prepending id_ to the form field names. This behavior is configurable, though, if you want to change the id convention or remove HTML id attributes and <label> tags entirely.

id とラベルの挙動を制御するには、 auto_id 引数を使います。この引数は、 True か False か文字列でなければなりません。

auto_id が False の場合、フォームの出力には <label> タグや id 属性が含まれなくなります。

>>> f = ContactForm(auto_id=False)
>>> print(f)
<div>Subject:<input type="text" name="subject" maxlength="100" required></div>
<div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div>
<div>Contact email:<input type="email" name="contact_email" required></div>
<div>Urgent:<input type="checkbox" name="urgent"></div>

auto_id が True に設定されている場合、フォームの出力には <label> タグが含まれ、各フォームフィールドの id としてフィールド名を使用します。

>>> f = ContactForm(auto_id=True)
>>> print(f)
<div><label for="subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="subject"></div>
<div><label for="message">Message:</label><textarea name="message" cols="40" rows="10" required id="message"></textarea></div>
<div><label for="contact_email">Contact email:</label><input type="email" name="contact_email" required id="contact_email"></div>
<div><label for="urgent">Urgent:</label><input type="checkbox" name="urgent" id="urgent"></div>

auto_id が '%s' 形式の文字を含む文字列に設定されている場合、フォームの出力には <label> タグが含まれ、フォーマット文字列に基づいて id 属性が生成されます。例えば、フォーマット文字列が 'field_%s' の場合、subject という名前のフィールドは 'field_subject' という id 値を取得します。例を続けます:

>>> f = ContactForm(auto_id="id_for_%s")
>>> print(f)
<div><label for="id_for_subject">Subject:</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div>
<div><label for="id_for_message">Message:</label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div>
<div><label for="id_for_contact_email">Contact email:</label><input type="email" name="contact_email" required id="id_for_contact_email"></div>
<div><label for="id_for_urgent">Urgent:</label><input type="checkbox" name="urgent" id="id_for_urgent"></div>

もし、 auto_id が (%s を含まない文字列のような) それ以外の真の値にセットされた場合、ライブラリは auto_id が True の場合と同様に動作します。

デフォルトでは、 auto_id は文字列 'id_%s' がセットされています。

Form.label_suffix¶

フォームをレンダリングする際、すべてのラベル名の後ろにつけられる翻訳可能な文字列の接尾語 (英語ではコロン (:) がデフォルト) です。

その文字をカスタマイズしたり、完全に省略したりすることも、label_suffix パラメータを使用して可能です。

>>> f = ContactForm(auto_id="id_for_%s", label_suffix="")
>>> print(f)
<div><label for="id_for_subject">Subject</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div>
<div><label for="id_for_message">Message</label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div>
<div><label for="id_for_contact_email">Contact email</label><input type="email" name="contact_email" required id="id_for_contact_email"></div>
<div><label for="id_for_urgent">Urgent</label><input type="checkbox" name="urgent" id="id_for_urgent"></div>
>>> f = ContactForm(auto_id="id_for_%s", label_suffix=" ->")
>>> print(f)
<div><label for="id_for_subject">Subject -&gt;</label><input type="text" name="subject" maxlength="100" required id="id_for_subject"></div>
<div><label for="id_for_message">Message -&gt;</label><textarea name="message" cols="40" rows="10" required id="id_for_message"></textarea></div>
<div><label for="id_for_contact_email">Contact email -&gt;</label><input type="email" name="contact_email" required id="id_for_contact_email"></div>
<div><label for="id_for_urgent">Urgent -&gt;</label><input type="checkbox" name="urgent" id="id_for_urgent"></div>

接尾文字列は、ラベルの最後の文字が句読文字 (英語では、 ., !, ?, :) でない場合に限ってつけられます。

フィールドはそれ自身の label_suffix を定義することもできます。これは Form.label_suffix よりも優先されます。また、 label_suffix パラメータを label_tag() / legend_tag() に使用することで、実行時に接尾辞を上書きすることもできます。

Form.use_required_attribute¶

True (デフォルト値) に設定した場合、必須フォームフィールドは HTMLの required 属性を伴います。

Formsets は、フォームセットにフォームを追加または削除したときのブラウザの誤検証を避けるため、 use_required_attribute=False としてフォームをインスタンス化します。

フォームウィジェットのレンダリングを設定する¶

Form.default_renderer¶

Specifies the renderer to use for the form. Defaults to None which means to use the default renderer specified by the FORM_RENDERER setting.

これはクラスの属性としてフォーム定義の際に設定するもしくは、Form.__init__() に renderer 引数を使うことで設定します。たとえば:

from django import forms


class MyForm(forms.Form):
    default_renderer = MyRenderer()

もしくは:

form = MyForm(renderer=MyRenderer())

フィールドの順序に関する記述¶

In the as_p(), as_ul() and as_table() shortcuts, the fields are displayed in the order in which you define them in your form class. For example, in the ContactForm example, the fields are defined in the order subject, message, contact_email, urgent. To reorder the HTML output, change the order in which those fields are listed in the class.

順序のカスタマイズには、ほかにもいくつかの方法があります:

Form.field_order¶

デフォルトでは Form.field_order=None で、これはフォームクラスでフィールドを定義した順番を保持します。field_order がフィールド名のリストである場合、指定されたリストに従ってフィールドが順序付けられ、残りのフィールドはデフォルトの順序に従って追加されます。リスト内の未知のフィールド名は無視されます。これにより、サブクラスでフィールドを None に設定して無効にしても、順序を再定義する必要がなくなります。

Form に Form.field_order 引数を使うことで、フィールドの順序をオーバーライドすることもできます。 Form の中で field_order が定義されていて、かつ Form をインスタンス化する際に field_order をインクルードする場合、後者の field_order が優先されます。

Form.order_fields(field_order)¶

また、 order_fields() に field_order と同様のフィールド名のリストを用いて、いつでもフィールドの順序を変更できます。

エラーの表示方法¶

バインドされた Form オブジェクトをレンダリングするとき、まだバリデーションが実行されていなければ、自動的にフォームのバリデーションが実行されます。HTML 出力には、バリデーションエラーが <ul class="errorlist"> のような形式で含まれます。

以下の例で確認してみます。

>>> data = {
...     "subject": "",
...     "message": "Hi there",
...     "contact_email": "invalid email address",
...     "urgent": True,
... }
>>> ContactForm(data).as_div()

... gives HTML like:

<div>
  <label for="id_subject">Subject:</label>
  <ul class="errorlist" id="id_subject_error"><li>This field is required.</li></ul>
  <input type="text" name="subject" maxlength="100" required aria-invalid="true" aria-describedby="id_subject_error" id="id_subject">
</div>
<div>
  <label for="id_message">Message:</label>
  <textarea name="message" cols="40" rows="10" required id="id_message">Hi there</textarea>
</div>
<div>
  <label for="id_contact_email">Contact email:</label>
  <ul class="errorlist" id="id_contact_email_error"><li>Enter a valid email address.</li></ul>
  <input type="email" name="contact_email" value="invalid email address" maxlength="320" required aria-invalid="true" aria-describedby="id_contact_email_error" id="id_contact_email">
</div>
<div>
    <label for="id_urgent">Urgent:</label>
    <input type="checkbox" name="urgent" id="id_urgent" checked>
</div>

Django のデフォルトのフォームテンプレートでは、フィールドに auto_id が設定されていて、かつカスタムの aria-describedby が指定されていない場合、バリデーションエラーを該当する入力要素と関連付けるために aria-describedby HTML 属性が使用されます。ウィジェット定義時にカスタムの aria-describedby を指定すると、デフォルト値が上書きされます。

ウィジェットが <fieldset> 内でレンダリングされる場合は、 aria-describedby はその要素に追加されます。そうでない場合は、aria-describedby はウィジェット自体の HTML 要素（ <input> など）に追加されます。

Changed in Django 5.2:

入力とエラーを関連づけるために aria-describedby が追加されました。

エラーリストのフォーマットをカスタムする¶

class ErrorList(initlist=None, error_class=None, renderer=None, field_id=None)[ソース]¶

デフォルトでは、フォームはバリデーションエラーを整形するために django.forms.utils.ErrorList を使用します。ErrorList はリストのようなオブジェクトであり、initlist はエラーのリストです。さらに、このクラスは以下の属性とメソッドを持っています。

Changed in Django 5.2:

field_id 引数が追加されました。

error_class¶: エラーリストをレンダリングする際に使用されるCSSクラス。指定されたクラスは、デフォルトの errorlist クラスに追加されます。

renderer¶: Specifies the renderer to use for ErrorList. Defaults to None which means to use the default renderer specified by the FORM_RENDERER setting.

field_id¶: New in Django 5.2.

エラーが関連するフィールドに対応する id を指定します。これにより、エラーテンプレート内で HTML の id 属性を付与でき、エラーとフィールドを関連付けるのに役立ちます。デフォルトのテンプレートでは、 id="{{ field_id }}_error" の形式が使用され、値は :meth:.`Form.add_error` によって、そのフィールドの auto_id をもとに自動的に提供されます。

template_name¶: __str__ や render() を呼び出した際に使用されるテンプレートの名前です。デフォルトでは、これは 'django/forms/errors/list/default.html' であり、'ul.html' テンプレートのプロキシとなります。

template_name_text¶: as_text() を呼び出す際に使用されるテンプレートの名前です。デフォルトでは、これは 'django/forms/errors/list/text.html' です。このテンプレートは、エラーを箇条書きのリストとしてレンダリングします。

template_name_ul¶: as_ul() を呼び出すときに使用されるテンプレートの名前です。デフォルトではこれは 'django/forms/errors/list/ul.html' です。このテンプレートは、 error_class で定義された CSS クラスを持つ包括的な <ul> で <li> タグ内のエラーをレンダリングします。

get_context()[ソース]¶

テンプレート内のエラーのレンダリング用のコンテキストを返します。

利用可能なコンテキストは次のとおりです。

errors: エラーのリスト。
error_class: CSSクラスの文字列。

render(template_name=None, context=None, renderer=None)¶

renderメソッドは、 __str__ と as_ul() メソッドの両方から呼び出されます。

すべての引数はオプションで、デフォルト値は以下の通りです:

template_name: template_name が返す値
context: get_context() が返す値
renderer: renderer が返す値

as_text()¶: エラーリストを template_name_text で定義されたテンプレートを使用してレンダリングします。

as_ul()¶: template_name_ul で定義されたテンプレートを使用してエラーリストをレンダリングします。

エラーのレンダリングをカスタマイズしたい場合は、template_name 属性をオーバーライドするか、あるいはデフォルトテンプレートをオーバーライドすることによって達成できます。詳しくは組み込みのフォームテンプレートをオーバーライドするも参照してください。

さらに詳細なアウトプット¶

as_p(), as_ul(), as_table() メソッドはショートカットです -- フォームオブジェクトを表示する唯一の方法ではありません。

class BoundField[ソース]¶

Form インスタンスのひとつのフィールドを HTML として表示したり、その属性にアクセスするのに使います。

このオブジェクトの __str__() メソッドは、このフィールドの HTML を表示します。

フォームまたはフィールドごとに異なる BoundField クラスを指定したい場合は、それぞれ Form.bound_field_class 、 Field.bound_field_class を使用することができます。

BoundField をオーバーライドする例は、 BoundField のカスタマイズを確認してください。

単一の BoundField を取得するには、フィールド名をキーとしてフォームに対して辞書参照構文を使用します。

>>> form = ContactForm()
>>> print(form["subject"])
<input type="text" name="subject" maxlength="100" required id="id_subject">

全ての BoundField オブジェクトを取得するには、フォームをイテレートします:

>>> form = ContactForm()
>>> for boundfield in form:
...     print(boundfield)
...
<input type="text" name="subject" maxlength="100" required id="id_subject">
<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>
<input type="email" name="contact_email" maxlength="320" required id="id_contact_email">
<input type="checkbox" name="urgent" id="id_urgent">

フィールド固有の出力は、フォームオブジェクトの auto_id 設定を反映します:

>>> f = ContactForm(auto_id=False)
>>> print(f["message"])
<textarea name="message" cols="40" rows="10" required></textarea>
>>> f = ContactForm(auto_id="id_%s")
>>> print(f["message"])
<textarea name="message" cols="40" rows="10" required id="id_message"></textarea>

`BoundField` の属性一覧¶

BoundField.aria_describedby[ソース]¶: New in Django 5.2.

フィールドをそのヘルプテキストやエラーメッセージと関連付けるための aria-describedby 参照を返します。ただし、Widget.attrs に aria-describedby がすでに設定されている場合は、ユーザー定義の属性を保持するために None を返します。

BoundField.auto_id[ソース]¶: この BoundField の HTML ID 属性。 Form.auto_id が False であれば、空の文字列を返します。

BoundField.data[ソース]¶

このプロパティは、ウィジェットの value_from_datadict() メソッドによって抽出された、この BoundField のデータを返します。もしデータが与えられていない場合は、 None を返します。

>>> unbound_form = ContactForm()
>>> print(unbound_form["subject"].data)
None
>>> bound_form = ContactForm(data={"subject": "My Subject"})
>>> print(bound_form["subject"].data)
My Subject

BoundField.errors[ソース]¶

プリント時に HTML の <ul class="errorlist"> として表示されるリストのようなオブジェクトです:

>>> data = {"subject": "hi", "message": "", "contact_email": "", "urgent": ""}
>>> f = ContactForm(data, auto_id=False)
>>> print(f["message"])
<input type="text" name="message" required aria-invalid="true">
>>> f["message"].errors
['This field is required.']
>>> print(f["message"].errors)
<ul class="errorlist"><li>This field is required.</li></ul>
>>> f["subject"].errors
[]
>>> print(f["subject"].errors)

>>> str(f["subject"].errors)
''

エラーを含むフィールドをレンダリングする際、そのフィールドのウィジェットに aria-invalid="true" が設定され、スクリーンリーダーユーザーにエラーが存在することを示します。

BoundField.field¶: この BoundField がラップしているフォームクラスの Field インスタンス。

BoundField.form¶: この BoundField がバインドされている Form インスタンス。

BoundField.help_text¶: フィールドの help_text 。

BoundField.html_name¶: ウィジェットのHTMLの name 属性で使用される名前です。これは prefix の形式を考慮します。

BoundField.id_for_label[ソース]¶

このプロパティを使用して、このフィールドのIDをレンダリングします。例えば、(label_tag()/legend_tag() がこれを行ってくれるにも関わらず、) テンプレートで手動で <label> を構築している場合は:

<label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}

デフォルトでは、これはフィールドの名前に id_ を前につけたものになります(上の例では "id_my_field")。フィールドのウィジェットの attrs を設定することで、IDを変更できます。例えば、以下のようにフィールドを宣言します:

my_field = forms.CharField(widget=forms.TextInput(attrs={"id": "myFIELD"}))

そして、上記のテンプレートを使用すると、以下のように表示されます:

<label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" required>

BoundField.initial[ソース]¶

BoundField.initial を使用して、フォームフィールドの初期データを取得します。データは、存在する場合は Form.initial から、そうでなければ Field.initial から取得されます。呼び出し可能オブジェクトの値は評価されます。より多くの例については、フォームの初期値を参照してください。

BoundField.initial はその返り値をキャッシュします。これは、返り値が変わる可能性がある呼び出し可能オブジェクト(例: datetime.now や uuid.uuid4 など)を扱う際に特に便利です。

>>> from datetime import datetime
>>> class DatedCommentForm(CommentForm):
...     created = forms.DateTimeField(initial=datetime.now)
...
>>> f = DatedCommentForm()
>>> f["created"].initial
datetime.datetime(2021, 7, 27, 9, 5, 54)
>>> f["created"].initial
datetime.datetime(2021, 7, 27, 9, 5, 54)

Using BoundField.initial is recommended over get_initial_for_field().

BoundField.is_hidden[ソース]¶: この BoundField のウィジェットが非表示の場合、 True を返します。

BoundField.label¶: フィールドの label 。これは label_tag()/legend_tag() で使用されます。

BoundField.name¶

このフィールドのフォーム上での名前:

>>> f = ContactForm()
>>> print(f["subject"].name)
subject
>>> print(f["message"].name)
message

BoundField.template_name[ソース]¶

BoundField.as_field_group() でレンダリングされるテンプレートの名前。

指定されていれば template_name の値を、そうでなければ field_template_name の値を返すプロパティ。

BoundField.use_fieldset[ソース]¶: この BoundField ウィジェットの use_fieldset 属性の値を返します。

BoundField.widget_type[ソース]¶

ラップされたフィールドのウィジェットのクラス名を小文字にして、末尾の input や widget を削除したものを返します。これは、ウィジェットのタイプに依存するレイアウトを持つフォームを構築する際に使用できます。例えば：

{% for field in form %}
    {% if field.widget_type == 'checkbox' %}
        # render one way
    {% else %}
        # render another way
    {% endif %}
{% endfor %}

`BoundField` のメソッド¶

BoundField.as_field_group()¶: フィールドを BoundField.render() を使用してデフォルト値でレンダリングし、設定されている場合はテンプレートの template_name 、そうでなければ field_template_name を使用して、BoundField をラベル、ヘルプテキスト、エラーとともにレンダリングします。

BoundField.as_hidden(attrs=None, **kwargs)[ソース]¶

これを <input type="hidden"> として表現するためのHTMLの文字列を返します。

**kwargs は as_widget() に渡されます。

このメソッドは主に内部で使用されます。代わりにウィジェットを使用すべきです。

BoundField.as_widget(widget=None, attrs=None, only_initial=False)[ソース]¶

Renders the field by rendering the passed widget, adding any HTML attributes passed as attrs. If no widget is specified, then the field's default widget will be used.

only_initial は Django の内部で使用されるものであり、明示的に設定すべきではありません。

BoundField.css_classes(extra_classes=None)[ソース]¶

Djangoのレンダリングショートカットを利用すると、必須のフォームフィールドやエラーを含むフィールドを示すためのCSSクラスが使用されます。フォームを手動でレンダリングする場合は、 css_classes メソッドを使用してこれらのCSSクラスにアクセスできます。

>>> f = ContactForm(data={"message": ""})
>>> f["message"].css_classes()
'required'

エラークラスと必須クラスが必要な場合に加えて、追加のクラスを提供したい場合は、引数としてそのクラスを提供できます:

>>> f = ContactForm(data={"message": ""})
>>> f["message"].css_classes("foo bar")
'foo bar required'

BoundField.get_context()[ソース]¶: レンダリングするためのテンプレートコンテキストを返します。利用可能なコンテキストは、バインドされたフィールドのインスタンスである field です。

BoundField.label_tag(contents=None, attrs=None, label_suffix=None, tag=None)[ソース]¶

フォームフィールドのラベルタグを、 Form.template_name_label で指定されたテンプレートを使用してレンダリングします。

利用可能なコンテキストは次のとおりです。

field: この 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 です。

Tip

テンプレートでは、field は BoundField のインスタンスです。したがって、field.field でアクセスする BoundField.field は、あなたが宣言したフィールド、例えば forms.CharField になります。

フォームフィールドのラベルタグを別々にレンダリングするには、その label_tag() メソッドを呼び出します:

>>> f = ContactForm(data={"message": ""})
>>> print(f["message"].label_tag())
<label for="id_message">Message:</label>

レンダリングをカスタマイズしたい場合は、 Form.template_name_label 属性をオーバーライドするか、一般的にはデフォルトのテンプレートをオーバーライドしてください。詳細は、組み込みのフォームテンプレートをオーバーライドするも参照してください。

BoundField.legend_tag(contents=None, attrs=None, label_suffix=None)[ソース]¶: tag='legend' を指定して label_tag() を呼び出すと、ラベルを <legend> タグでレンダリングします。これは、 <label> よりも <legend> が適しているラジオボタンや複数のチェックボックスウィジェットをレンダリングする際に便利です。

BoundField.render(template_name=None, context=None, renderer=None)¶

renderメソッドは as_field_group によって呼び出されます。すべての引数はオプションであり、デフォルト値は次のとおりです。

template_name: BoundField.template_name
context: BoundField.get_context() が返す値
renderer: Form.default_renderer が返す値

template_name を渡すことで、単一の呼び出しに使用されるテンプレートをカスタマイズできます。

BoundField.value()[ソース]¶

このメソッドを使用すると、Widget によってレンダリングされるフィールドの生の値をレンダリングできます:

>>> initial = {"subject": "welcome"}
>>> unbound_form = ContactForm(initial=initial)
>>> bound_form = ContactForm(data={"subject": "hi"}, initial=initial)
>>> print(unbound_form["subject"].value())
welcome
>>> print(bound_form["subject"].value())
hi

`BoundField` のカスタマイズ¶

Form.bound_field_class¶

New in Django 5.2.

フォームをレンダリングする際に使用するカスタムの BoundField クラスを定義します。これは、プロジェクト全体で設定された :attr:.`BaseRenderer.bound_field_class` (およびカスタムの FORM_RENDERER ) よりも優先されますが、フィールド単位で指定された Field.bound_field_class によって上書きされる可能性があります。

bound_field_class はクラス変数として定義されていない場合でも、 Form または Field のコンストラクタ引数 bound_field_class を使って設定することができます。

For compatibility reasons, a custom form field can still override Field.get_bound_field() to use a custom class, though any of the previous options are preferred.

テンプレート内でフォームフィールドに関する追加情報へアクセスする必要があり、 Field のサブクラス化では不十分な場合は、カスタムの BoundField を使用するとよいでしょう。

例えば GPSCoordinatesField を使用していて、テンプレート内で座標に関する追加情報にアクセスしたい時は、次のように実装します。

class GPSCoordinatesBoundField(BoundField):
    @property
    def country(self):
        """
        Return the country the coordinates lie in or None if it can't be
        determined.
        """
        value = self.value()
        if value:
            return get_country_from_coordinates(value)
        else:
            return None


class GPSCoordinatesField(Field):
    bound_field_class = GPSCoordinatesBoundField

これで、テンプレート内で {{ form.coordinates.country }} を使って国にアクセスできるようになりました。

デフォルトのフォームフィールドのテンプレートレンダリングをカスタマイズしたい場合もあるでしょう。たとえば、 BoundField.label_tag() をオーバーライドして、カスタムクラスを追加することができます。

class StyledLabelBoundField(BoundField):
    def label_tag(self, contents=None, attrs=None, label_suffix=None, tag=None):
        attrs = attrs or {}
        attrs["class"] = "wide"
        return super().label_tag(contents, attrs, label_suffix, tag)


class UserForm(forms.Form):
    bound_field_class = StyledLabelBoundField
    name = CharField()

これは、デフォルトのフォームレンダリングを次のように更新します。

>>> f = UserForm()
>>> print(f["name"].label_tag)
<label for="id_name" class="wide">Name:</label>

すべてのフィールドをラップする外側の HTML 要素に CSS クラスを追加したい場合は、BoundField をオーバーライドして、異なる CSS クラスの集合を返すように設定できます。

class WrappedBoundField(BoundField):
    def css_classes(self, extra_classes=None):
        parent_css_classes = super().css_classes(extra_classes)
        return f"field-class {parent_css_classes}".strip()


class UserForm(forms.Form):
    bound_field_class = WrappedBoundField
    name = CharField()

これにより、以下のようにフォームレンダリングが更新されます。

>>> f = UserForm()
>>> print(f)
<div class="field-class"><label for="id_name">Name:</label><input type="text" name="name" required id="id_name"></div>

あるいは、プロジェクト全体で BoundField クラスを上書きしたい場合は、カスタムの FORM_RENDERER において BaseRenderer.bound_field_class を定義することで実現できます。

mysite/renderers.py¶

from django.forms.renderers import DjangoTemplates

from .forms import CustomBoundField

class CustomRenderer(DjangoTemplates):
    bound_field_class = CustomBoundField

settings.py¶

FORM_RENDERER = "mysite.renderers.CustomRenderer"

アップロードされたファイルをフォームにバインドする¶

FileField と ImageField フィールドを持つフォームを扱うのは、通常のフォームよりも少し複雑です。

まず、ファイルをアップロードするには、<form> 要素が enctype を "multipart/form-data" として正しく定義していることを確認する必要があります:

<form enctype="multipart/form-data" method="post" action="/foo/">

次に、フォームを使用する際には、ファイルデータをバインドする必要があります。ファイルデータは通常のフォームデータとは別に扱われるため、フォームに FileField や ImageField が含まれている場合、フォームをバインドする際に第2引数を指定する必要があります。したがって、 ImageField を mugshot という名前で ContactForm に追加した場合、mugshot イメージを含むファイルデータをバインドする必要があります:

# Bound form with an image field
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> data = {
...     "subject": "hello",
...     "message": "Hi there",
...     "contact_email": "foo@example.com",
...     "urgent": True,
... }
>>> file_data = {"mugshot": SimpleUploadedFile("face.jpg", b"file data")}
>>> f = ContactFormWithMugshot(data, file_data)

実際には、通常、（フォームデータのソースとして request.POST を使用するのと同様に、）ファイルデータのソースとして request.FILES を指定します:

# Bound form with an image field, data from the request
>>> f = ContactFormWithMugshot(request.POST, request.FILES)

バインドされていないフォームを作成する方法は、いつも通りです。フォームデータとファイルデータの両方を省略します。

# Unbound form with an image field
>>> f = ContactFormWithMugshot()

マルチパートフォームのテスト¶

Form.is_multipart()¶

再利用可能なビューやテンプレートを書いている場合、フォームがマルチパートフォームかどうかを事前に知ることができないかもしれません。 is_multipart() メソッドは、フォームの送信にマルチパートエンコーディングが必要かどうかを教えてくれます:

>>> f = ContactFormWithMugshot()
>>> f.is_multipart()
True

テンプレートでの使い方の例です:

{% if form.is_multipart %}
    <form enctype="multipart/form-data" method="post" action="/foo/">
{% else %}
    <form method="post" action="/foo/">
{% endif %}
{{ form }}
</form>

フォームをサブクラス化する¶

複数の Form クラスがフィールドを共有している場合、サブクラス化を利用して冗長性を排除できます。

カスタム Form クラスをサブクラス化すると、親クラスのすべてのフィールドが含まれ、その後にサブクラスで定義したフィールドが続きます。

In this example, ContactFormWithDepartment contains all the fields from ContactForm, plus an additional field, department. The ContactForm fields are ordered first:

>>> class ContactFormWithDepartment(ContactForm):
...     department = forms.CharField()
...
>>> f = ContactFormWithDepartment(auto_id=False)
>>> print(f)
<div>Subject:<input type="text" name="subject" maxlength="100" required></div>
<div>Message:<textarea name="message" cols="40" rows="10" required></textarea></div>
<div>Contact email:<input type="email" name="contact_email" required></div>
<div>Urgent:<input type="checkbox" name="urgent"></div>
<div>Department:<input type="text" name="department" required></div>

複数のフォームをサブクラス化し、フォームをミックスインとして扱うことができます。この例では、BeatleForm が PersonForm と InstrumentForm （この順番で）の両方をサブクラス化し、そのフィールドリストは親クラスのフィールドを含んでいます:

>>> from django import forms
>>> class PersonForm(forms.Form):
...     first_name = forms.CharField()
...     last_name = forms.CharField()
...
>>> class InstrumentForm(forms.Form):
...     instrument = forms.CharField()
...
>>> class BeatleForm(InstrumentForm, PersonForm):
...     haircut_type = forms.CharField()
...
>>> b = BeatleForm(auto_id=False)
>>> print(b)
<div>First name:<input type="text" name="first_name" required></div>
<div>Last name:<input type="text" name="last_name" required></div>
<div>Instrument:<input type="text" name="instrument" required></div>
<div>Haircut type:<input type="text" name="haircut_type" required></div>

親クラスから継承された Field を、サブクラスでフィールドの名前を None に設定することで、宣言的にフィールドを削除できます。たとえば次のようにします:

>>> from django import forms

>>> class ParentForm(forms.Form):
...     name = forms.CharField()
...     age = forms.IntegerField()
...

>>> class ChildForm(ParentForm):
...     name = None
...

>>> list(ChildForm().fields)
['age']

フォームのプレフィックス¶

Form.prefix¶

1 つの <form> タグの中に複数の Django フォームを配置できます。各 Form に独自の名前空間を与えるには、prefix キーワード引数を使用します。

>>> mother = PersonForm(prefix="mother")
>>> father = PersonForm(prefix="father")
>>> print(mother)
<div><label for="id_mother-first_name">First name:</label><input type="text" name="mother-first_name" required id="id_mother-first_name"></div>
<div><label for="id_mother-last_name">Last name:</label><input type="text" name="mother-last_name" required id="id_mother-last_name"></div>
>>> print(father)
<div><label for="id_father-first_name">First name:</label><input type="text" name="father-first_name" required id="id_father-first_name"></div>
<div><label for="id_father-last_name">Last name:</label><input type="text" name="father-last_name" required id="id_father-last_name"></div>

プレフィックスは、フォームクラスにも指定できます：

>>> class PersonForm(forms.Form):
...     ...
...     prefix = "person"
...

Django Developer Survey

フォーム API¶

バインドされた (bound) フォームとバインドされていない (unbound) フォーム¶

フォームをデータの検証に使用する¶

バインドされていないフォームの動作¶

フォームの初期値¶

どのフォームデータが変更されたかをチェックする¶

フォームからフィールドにアクセスする¶

"clean" なデータにアクセスする¶

フォームをHTMLとしてアウトプットする¶

デフォルトのレンダリング¶

`template_name`¶

`render()`¶

`get_context()`¶

`template_name_label`¶

出力スタイル¶

`as_div()`¶

`as_p()`¶

`as_ul()`¶

`as_table()`¶

必須フォームとエラーのあるフォームのスタイリング¶

フォーム要素の HTML `id` 属性と `<label>` タグを設定する¶

フォームウィジェットのレンダリングを設定する¶

フィールドの順序に関する記述¶

エラーの表示方法¶

エラーリストのフォーマットをカスタムする¶

さらに詳細なアウトプット¶

`BoundField` の属性一覧¶

`BoundField` のメソッド¶

`BoundField` のカスタマイズ¶

アップロードされたファイルをフォームにバインドする¶

マルチパートフォームのテスト¶

フォームをサブクラス化する¶

フォームのプレフィックス¶

追加的な情報

Support Django!

コンテンツ

助けを求める

ダウンロード:

Diamond and Platinum Members

Django Developer Survey

フォーム API¶

バインドされた (bound) フォームとバインドされていない (unbound) フォーム¶

フォームをデータの検証に使用する¶

バインドされていないフォームの動作¶

フォームの初期値¶

どのフォームデータが変更されたかをチェックする¶

フォームからフィールドにアクセスする¶

"clean" なデータにアクセスする¶

フォームをHTMLとしてアウトプットする¶

デフォルトのレンダリング¶

template_name¶

render()¶

get_context()¶

template_name_label¶

出力スタイル¶

as_div()¶

as_p()¶

as_ul()¶

as_table()¶

必須フォームとエラーのあるフォームのスタイリング¶

フォーム要素の HTML id 属性と <label> タグを設定する¶

フォームウィジェットのレンダリングを設定する¶

フィールドの順序に関する記述¶

エラーの表示方法¶

エラーリストのフォーマットをカスタムする¶

さらに詳細なアウトプット¶

BoundField の属性一覧¶

BoundField のメソッド¶

BoundField のカスタマイズ¶

アップロードされたファイルをフォームにバインドする¶

マルチパートフォームのテスト¶

フォームをサブクラス化する¶

フォームのプレフィックス¶

追加的な情報

Support Django!

コンテンツ

助けを求める

ダウンロード:

Diamond and Platinum Members

`template_name`¶

`render()`¶

`get_context()`¶

`template_name_label`¶

`as_div()`¶

`as_p()`¶

`as_ul()`¶

`as_table()`¶

フォーム要素の HTML `id` 属性と `<label>` タグを設定する¶

`BoundField` の属性一覧¶

`BoundField` のメソッド¶

`BoundField` のカスタマイズ¶