{"title":"フォーム フィールド","version":"6.0","locale":"ja","docname":"ref/forms/fields","url":"/ja/6.0/ref/forms/fields/","canonical":"https://djangodocs.dev/ja/6.0/ref/forms/fields/","summary":"Form クラスを作成時の一番重要な部分は、form のフィールド (field) の定義です。各フィールドにはカスタムの検証ロジックがあり、他にいくつかのフックもあります。","html":"

フォーム フィールドLink to this heading#

\n
\n
\nclass FieldLink to this definition#
\n
\n\n

Form クラスを作成時の一番重要な部分は、form のフィールド (field) の定義です。各フィールドにはカスタムの検証ロジックがあり、他にいくつかのフックもあります。

\n
\n
\nField.clean(value)Link to this definition#
\n
\n\n

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

\n
Python console
>>> 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
\n
\n

field のコアとなる引数Link to this heading#

\n

各 Field クラスのコンストラクタは少なくとも以下の引数を受け付けます。Field クラスによっては追加のフィールド固有の引数も取れることがありますが、以下に説明する引数は 常に 取ることができます。

\n
\n

requiredLink to this heading#

\n
\n
\nField.requiredLink to this definition#
\n
\n\n

デフォルトでは、各 Field クラスは値が必須であると想定しているため、空の値 (None もしくは空文字列 ("")) を渡すと、clean() は ValidationError 例外を発生させます。

\n
Python console
>>> 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(0)\n'0'\n>>> f.clean(True)\n'True'\n>>> f.clean(False)\n'False'\n
\n

フィールドが必須で ない ことを指定するには、Field コンストラクタに required=False を渡します:

\n
Python console
>>> 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'\n
\n

Field に required=False が設定されていて、clean() に空の値を渡した場合、clean() は ValidationError を発生させる代わりに、 正規化された 空の値を返します。CharField の場合、これは empty_value を返し、デフォルトでは空の文字列となります。他の Field クラスでは、None になることもあります。(これはフィールドによって異なります。)

\n

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

\n
\n
\n

labelLink to this heading#

\n
\n
\nField.labelLink to this definition#
\n
\n\n

label 属性は、フィールドに対する "人が読みやすい" ラベルを指定します。このラベルは Field が Form 内で表示されるときに使用されます。

\n

As explained in フォームをHTMLとしてアウトプットする, the default label for a\nField is generated from the field name by converting all underscores to\nspaces and upper-casing the first letter. Specify a string for label if\nthat default behavior doesn't result in an adequate label. Use an empty string\n("") to hide the label.

\n

以下は、2 つのフィールドに対して label を実装する Form の完全な例です。出力を簡略化するために、 auto_id=False を指定しています:

\n
Python console
>>> 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>\n
\n
\n
\n

label_suffixLink to this heading#

\n
\n
\nField.label_suffixLink to this definition#
\n
\n\n

label_suffix 引数を使用すると、フォームの label_suffix をフィールドごとに上書きできます。

\n
Python console
>>> 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>\n
\n
\n
\n

initialLink to this heading#

\n
\n
\nField.initialLink to this definition#
\n
\n\n

initial 属性は、Field が結びつけられていない Form で表示されるときに使われる初期値を指定します。

\n

動的に初期値を指定する方法は、Form.initial パラメータを参照してください。

\n

これの使用例は、あるフィールドが特定の値で初期化された「空」のフォームを表示したい場合です。例えば:

\n
Python console
>>> from django import forms\n>>> class CommentForm(forms.Form):\n...     name = forms.CharField(initial="Your name")\n...     url = forms.URLField(initial="https://")\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="https://" required></div>\n<div>Comment:<input type="text" name="comment" required></div>\n
\n

初期値の辞書をフォームの表示時にデータとして渡すだけでよいのでは？と考えるかもしれません。しかし、それを行うとバリデーションがトリガーされ、HTML出力にはバリデーションエラーが含まれます。

\n
Python console
>>> class CommentForm(forms.Form):\n...     name = forms.CharField()\n...     url = forms.URLField()\n...     comment = forms.CharField()\n...\n>>> default_data = {"name": "Your name", "url": "https://"}\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="https://" 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
\n

これが、initial 値が未結合フォームにのみ表示される理由です。結合フォームの場合、HTML 出力は結合データを使用します。

\n

また、initial 値は、特定のフィールドの値が指定されていない場合に、バリデーション内で "デフォルト" データとして使用されません。initial 値は、初期フォーム表示のためのみに意図されています。

\n
Python console
>>> class CommentForm(forms.Form):\n...     name = forms.CharField(initial="Your name")\n...     url = forms.URLField(initial="https://")\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* fallback to using the initial values.\n>>> f.errors\n{'url': ['This field is required.'], 'name': ['This field is required.']}\n
\n

定数の代わりに、任意の呼び出し可能オブジェクトを渡すこともできます:

\n
Python console
>>> 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
\n

呼び出し可能オブジェクトは、定義される時ではなく、未バインドの形式が表示される時にのみ評価されます。

\n
\n
\n

widgetLink to this heading#

\n
\n
\nField.widgetLink to this definition#
\n
\n\n

widget 引数は、Field をレンダリングするときに使う Widget クラスを指定します。詳しくは ウィジェット を参照してください。

\n
\n
\n

help_textLink to this heading#

\n
\n
\nField.help_textLink to this definition#
\n
\n\n

help_text 引数は、Field を説明するテキストを指定します。help_text を指定した場合、容易な Form メソッド (たとえば as_ul()) で Field がレンダリングされるときに、Field の隣に表示されます。

\n

モデルフィールドの help_text と同じく、値は自動的に生成されるフォーム内で HTML 用にエスケープされません。

\n

以下は、2つのフィールドに help_text を実装した Form の完全な例です。出力を単純化するために auto_id=False を指定しています:

\n
Python console
>>> 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...     contact_email = forms.EmailField(help_text="Your email (so we can reply).")\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>Contact email:<div class="helptext">Your email (so we can reply).</div><input type="email" name="contact_email" maxlength="320" required></div>\n
\n

フィールドにヘルプテキストがある場合、それは aria-describedby HTML 属性を使用して入力と関連付けられます。ウィジェットが <fieldset> 内でレンダリングされる場合は、この属性が <fieldset> 要素に追加され、そうでない場合はウィジェットの <input> 要素に追加されます。

\n
Python console
>>> 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
\n

カスタム aria-describedby 属性を追加する際には、使用している場合は help_text 要素の id も希望する順序で含めることを確認してください。スクリーンリーダーのユーザーにとって、説明は aria-describedby 内の出現順に読み上げられます。

\n
Python console
>>> 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>\n
\n
\n
\n

error_messagesLink to this heading#

\n
\n
\nField.error_messagesLink to this definition#
\n
\n\n

error_messages 引数を使用すると、フィールドが出すデフォルトのメッセージを上書きできます。上書きしたいエラーメッセージに一致するキーを持つ辞書を渡してください。例えば、これはデフォルトのエラーメッセージです：

\n
Python console
>>> from django import forms\n>>> generic = forms.CharField()\n>>> generic.clean("")\nTraceback (most recent call last):\n  ...\nValidationError: ['This field is required.']\n
\n

そしてこれがカスタムエラーメッセージです:

\n
Python console
>>> 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
\n

以下の built-in Field classes セクションでは、各 Field が使用するエラーメッセージのキーを定義しています。

\n
\n
\n

validatorsLink to this heading#

\n
\n
\nField.validatorsLink to this definition#
\n
\n\n

validators 引数は、フィールドに対するバリデーション関数のリストを指定します。

\n

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

\n
\n
\n

localizeLink to this heading#

\n
\n
\nField.localizeLink to this definition#
\n
\n\n

localize 引数は、form データの入力とレンダリングした出力のローカライズを有効にします。

\n

詳細については、フォーマットのローカライズに関するドキュメント を参照してください。

\n
\n
\n

disabledLink to this heading#

\n
\n
\nField.disabledLink to this definition#
\n
\n\n

disabled はブール値の引数を取ります。 True にセットされた場合、フォームのフィールドを disabled HTML 属性を使って無効化し、ユーザーが編集できないようにします。たとえユーザーが勝手にフィールドの値を書き換えてサーバーに送信したとしても、フォームの初期データを使い、書き換えられたデータは無視します。

\n
\n
\n

template_nameLink to this heading#

\n
\n
\nField.template_nameLink to this definition#
\n
\n\n

template_name 引数は、フィールドが as_field_group() でレンダリングされるときにカスタムテンプレートを使用できるようにします。デフォルトの値は "django/forms/field.html" に設定されています。この属性をオーバーライドするか、デフォルトテンプレートをオーバーライドすることで、フィールドごとに変更できます。詳細は、 組み込みのフィールドテンプレートをオーバーライドする も参照してください。

\n
\n
\n

bound_field_classLink to this heading#

\n
\n
\nField.bound_field_classLink to this definition#
\n
\n\n\n

bound_field_class 属性を使用すれば、 Form.bound_field_class をフィールドごとにオーバーライドすることができます。

\n
\n
\n
\n

フィールドのデータの変更チェックLink to this heading#

\n
\n

has_changed()Link to this heading#

\n
\n
\nField.has_changed()Link to this definition#
\n
\n\n

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

\n

See the Form.has_changed documentation for more information.

\n
\n
\n
\n

ビルトインの Field クラスLink to this heading#

\n

当然ながら、forms ライブラリには共通のバリデーションニーズを代表する一連の Field クラスが含まれています。このセクションでは、各ビルトインフィールドについて説明します。

\n

各フィールドについて、widget を指定しない場合に使用されるデフォルトウィジェットを説明します。また、空の値を提供した場合に返される値も指定します（これがどういう意味かについては required セクションを参照してください）。

\n
\n

BooleanFieldLink to this heading#

\n
\n
\nclass BooleanField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: CheckboxInput

    • \n

  • 空の値: False

    • \n

  • 正規化後の値: Pythonの True または False になります。

    • \n

  • フィールドが required=True を持つ場合、値が True (例えば、チェックボックスがチェックされている)であることを確認します。

    • \n

  • エラーメッセージのキー: required

    • \n
\n\n
\n\n
\n
\n

CharFieldLink to this heading#

\n
\n
\nclass CharField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: empty_value として与えたもの

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • max_length と min_length が与えられた場合は、MaxLengthValidator と MinLengthValidator を使用します。それ以外の場合は、すべての入力が有効です。

    • \n

  • エラーメッセージキー: required, max_length, min_length

    • \n
\n

次のオプション引数がバリデーションに使用されます:

\n
\n
\nmax_lengthLink to this definition#
\n
\n\n
\n
\nmin_lengthLink to this definition#
\n

これらの引数が提供された場合、文字列が与えられた長さ以下か以上であることを保証します。

\n
\n\n
\n
\nstripLink to this definition#
\n

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

\n
\n\n
\n
\nempty_valueLink to this definition#
\n

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

\n
\n\n
\n\n
\n
\n

ChoiceFieldLink to this heading#

\n
\n
\nclass ChoiceField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Select

    • \n

  • 空の値: '' (空の文字列)

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • 指定された値が選択肢のリスト内に存在することを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice

    • \n
\n

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

\n

1つの追加引数を受け取ります:

\n
\n
\nchoicesLink to this definition#
\n

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

\n
\n\n\n
\n\n
\n
\n

DateFieldLink to this heading#

\n
\n
\nclass DateField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: DateInput

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の datetime.date オブジェクトになります。

    • \n

  • 与えられた値が datetime.date、datetime.datetime または特定の日付の表示形式のどれかに当てはまるか検証します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

1 つの省略可能な引数を取ります:

\n
\n
\ninput_formatsLink to this definition#
\n

文字列を有効な datetime.date オブジェクトに変換しようとする際に使用されるフォーマットのイテラブル。

\n
\n\n

input_formats 引数が指定されていない場合、デフォルトの入力形式は有効なロケール形式の DATE_INPUT_FORMATS キーから取得されるか、ローカライズが無効になっている場合は DATE_INPUT_FORMATS から取得されます。また、 表示形式のローカライズ も参照してください。

\n
\n\n
\n
\n

DateTimeFieldLink to this heading#

\n
\n
\nclass DateTimeField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: DateTimeInput

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の datetime.datetime オブジェクトになります。

    • \n

  • 与えられた値が datetime.datetime、datetime.date または特定の日時の表示形式の文字列のどれかに当てはまるか検証します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

1 つの省略可能な引数を取ります:

\n
\n
\ninput_formatsLink to this definition#
\n

ISO 8601 形式に加えて、文字列を有効な datetime.datetime オブジェクトに変換しようと試みる際に使用される形式のイテラブル。

\n
\n\n

このフィールドは常に、ISO 8601形式の日付や parse_datetime() で認識される類似の形式の文字列を受け付けます。いくつかの例を挙げます:

\n
    \n

  • '2006-10-25 14:30:59'

    • \n

  • '2006-10-25T14:30:59'

    • \n

  • '2006-10-25 14:30'

    • \n

  • '2006-10-25T14:30'

    • \n

  • '2006-10-25T14:30Z'

    • \n

  • '2006-10-25T14:30+02:00'

    • \n

  • '2006-10-25'

    • \n
\n

input_formats 引数が提供されない場合、デフォルトの入力フォーマットはアクティブなロケールフォーマットの DATETIME_INPUT_FORMATS と DATE_INPUT_FORMATS キーから取得されます。もしくは、ローカライズが無効の場合は DATETIME_INPUT_FORMATS と DATE_INPUT_FORMATS から取得されます。また、表示形式のローカライズについては 表示形式のローカライズ も参照してください。

\n
\n\n
\n
\n

DecimalFieldLink to this heading#

\n
\n
\nclass DecimalField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の decimal になります。

    • \n

  • 指定された値が10進数であることを検証します。 max_value と min_value が提供されている場合は MaxValueValidator および MinValueValidator を使用します。 step_size が提供されている場合は StepValueValidator を使用します。先頭及び末尾の空白は無視されます。

    • \n

  • エラーメッセージのキー: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size 。

    • \n
\n

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

\n

5つのオプション引数を受け取ります:

\n
\n
\nmax_valueLink to this definition#
\n
\n\n
\n
\nmin_valueLink to this definition#
\n

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

\n
\n\n
\n
\nmax_digitsLink to this definition#
\n

値で許容される桁数の最大値 (小数点より前と小数点より後の桁数を合わせ、先頭のゼロは除く)。

\n
\n\n
\n
\ndecimal_placesLink to this definition#
\n

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

\n
\n\n
\n
\nstep_sizeLink to this definition#
\n

有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。

\n
\n\n
\n\n
\n
\n

DurationFieldLink to this heading#

\n
\n
\nclass DurationField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の timedelta になります。

    • \n

  • 指定された値が timedelta に変換できる文字列であることを検証します。値は datetime.timedelta.min と datetime.timedelta.max の間でなければなりません。

    • \n

  • エラーメッセージのキー: required、invalid、overflow 。

    • \n
\n

parse_duration() が理解できるどんな形式でも受け入れます。

\n
\n\n
\n
\n

EmailFieldLink to this heading#

\n
\n
\nclass EmailField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: EmailInput

    • \n

  • 空の値: empty_value として指定したものです。

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • EmailValidator を使用して、与えられた値が有効なメールアドレスであることを、比較的複雑な正規表現を使用してバリデーションします。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

オプション引数として max_length、min_length、empty_value があり、CharField と同じように機能します。 max_length 引数のデフォルト値は320です( RFC 3696 Section 3 を参照)。

\n
\n\n
\n
\n

FileFieldLink to this heading#

\n
\n
\nclass FileField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: ClearableFileInput

    • \n

  • 空の値: None

    • \n

  • ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした UploadedFile オブジェクトに正規化されます。

    • \n

  • フォームに空でないファイルデータがバインドされていることをバリデーションできます。

    • \n

  • エラーメッセージのキー: required, invalid, missing, empty, max_length

    • \n
\n

バリデーションのためのオプション引数には max_length と allow_empty_file があります。もしこれらが指定された場合、ファイル名は与えられた長さ以下でなければならず、ファイルの内容が空でもバリデーションは成功します。

\n

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

\n

フォーム内で FileField を使用する時は、ファイルのデータをフォームにバインド することも必要です。

\n

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

\n
\n\n
\n
\n

FilePathFieldLink to this heading#

\n
\n
\nclass FilePathField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Select

    • \n

  • 空の値: '' (空の文字列)

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • 選択された選択肢が選択肢のリストに存在することを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice

    • \n
\n

このフィールドは、特定のディレクトリ内のファイルから選択することを可能にします。5つの追加引数を受け取りますが、path のみが必須です:

\n
\n
\npathLink to this definition#
\n

リストアップしたいディレクトリの絶対パス。このディレクトリは存在していなければなりません。

\n
\n\n
\n
\nrecursiveLink to this definition#
\n

False (デフォルト) の場合、path の直接の内容のみが選択肢として提示されます。True の場合、ディレクトリは再帰的に降りていき、すべての子孫が選択肢としてリストアップされます。

\n
\n\n
\n
\nmatchLink to this definition#
\n

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

\n
\n\n
\n
\nallow_filesLink to this definition#
\n

Optional. Either True or False. Default is True. Specifies\nwhether files in the specified location should be included. Either this\nor allow_folders must be True.

\n
\n\n
\n
\nallow_foldersLink to this definition#
\n

Optional. Either True or False. Default is False. Specifies\nwhether folders in the specified location should be included. Either\nthis or allow_files must be True.

\n
\n\n
\n\n
\n
\n

FloatFieldLink to this heading#

\n
\n
\nclass FloatField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の float になります。

    • \n

  • 指定された値が float であることを検証します。 max_value と min_value が提供されている場合は MaxValueValidator と MinValueValidator を使用します。step_size が提供されている場合は StepValueValidator を使用します。Python の float() 関数と同様、先頭と末尾の空白は許可されます。

    • \n

  • エラーメッセージのキー: required、invalid、max_value、min_value、step_size 。

    • \n
\n

オプションで3つの引数を取ります:

\n
\n
\nmax_valueLink to this definition#
\n
\n\n
\n
\nmin_valueLink to this definition#
\n

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

\n
\n\n
\n
\nstep_sizeLink to this definition#
\n

有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。

\n
\n\n
\n\n
\n
\n

GenericIPAddressFieldLink to this heading#

\n
\n
\nclass GenericIPAddressField(**kwargs)Link to this definition#
\n

IPv4 または IPv6 アドレスのいずれかを持つフィールドです。

\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: '' (空の文字列)

    • \n

  • 正規化後の値: 文字列。以下の説明に従って、IPv6 アドレスは正規化されます。

    • \n

  • 与えられた値が有効な IP アドレスを表しているか検証します。

    • \n

  • エラーメッセージキー: required, invalid, max_length

    • \n
\n

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 と正規化されます。そして、すべての文字は小文字に変換されます。

\n

オプションで3つの引数を取ります:

\n
\n
\nprotocolLink to this definition#
\n

有効な入力を指定したプロトコルに限定します。指定できる値は、 both (デフォルト)、 IPv4 または IPv6 です。大文字・小文字は無視されます。

\n
\n\n
\n
\nunpack_ipv4Link to this definition#
\n

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

\n
\n\n
\n
\nmax_lengthLink to this definition#
\n

デフォルトは 39 で、CharField に対する場合と同様の動作をします。

\n
\n\n
\n\n
\n
\n

ImageFieldLink to this heading#

\n
\n
\nclass ImageField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: ClearableFileInput

    • \n

  • 空の値: None

    • \n

  • ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした UploadedFile オブジェクトに正規化されます。

    • \n

  • ファイルデータがフォームにバインドされたことを検証します。また、 FileExtensionValidator を使用して、ファイルの拡張子が Pillow でサポートされているかを検証します。

    • \n

  • エラーメッセージのキー: required, invalid, missing, empty, invalid_image

    • \n
\n

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

\n

フォームで ImageField を使用する場合、フォームにファイルデータをバインドする 必要も覚えておいてください。

\n

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

\n
Python console
>>> 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
\n

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

\n
\n\n
\n
\n

IntegerFieldLink to this heading#

\n
\n
\nclass IntegerField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Field.localize が False のとき NumberInput、True のとき TextInput.

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の整数になります。

    • \n

  • 与えられた値が整数であることを検証します。max_value と min_value が提供されている場合は MaxValueValidator と MinValueValidator を使用します。step_size が提供されている場合は StepValueValidator を使用します。Python の int() 関数と同様、先頭と末尾の空白は許可されます。

    • \n

  • エラーメッセージキー: required, invalid, max_value, min_value, step_size

    • \n
\n

max_value、min_value、および step_size のエラーメッセージには、%(limit_value)s が含まれることがあり、これは適切な制限値に置き換えられます。

\n

バリデーションのために、3つのオプション引数を受け取ります:

\n
\n
\nmax_valueLink to this definition#
\n
\n\n
\n
\nmin_valueLink to this definition#
\n

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

\n
\n\n
\n
\nstep_sizeLink to this definition#
\n

有効な入力を step_size の整数倍に制限します。もし min_value も指定されている場合、その値をオフセットとして加算し、ステップサイズが一致しているかを判断します。

\n
\n\n
\n\n
\n
\n

JSONFieldLink to this heading#

\n
\n
\nclass JSONField(encoder=None, decoder=None, **kwargs)Link to this definition#
\n

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

\n
    \n

  • デフォルトのウィジェット: Textarea

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: JSONField.decoder に依存して、JSON 値の Python 表現 (通常は dict、list、または None) に正規化されます。

    • \n

  • 与えられた値が有効な JSON であることを検証します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

次の2つの省略可能な引数を取ります:

\n
\n
\nencoderLink to this definition#
\n

A json.JSONEncoder subclass to serialize data types not\nsupported by the standard JSON serializer (e.g. datetime.datetime\nor UUID). For example, you can use the\nDjangoJSONEncoder class.

\n

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

\n
\n\n
\n
\ndecoderLink to this definition#
\n

A json.JSONDecoder subclass to deserialize the input. Your\ndeserialization may need to account for the fact that you can't be\ncertain of the input type. For example, you run the risk of returning a\ndatetime that was actually a string that just happened to be in the\nsame format chosen for datetimes.

\n

The decoder can be used to validate the input. If\njson.JSONDecodeError is raised during the deserialization,\na ValidationError will be raised.

\n

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

\n
\n\n\n\n
\n\n
\n
\n

MultipleChoiceFieldLink to this heading#

\n
\n
\nclass MultipleChoiceField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: SelectMultiple

    • \n

  • 空の値: [] (空のリスト)

    • \n

  • 正規化後の値: 文字列のリストになります。

    • \n

  • 与えられた値のリストの各値が、選択肢のリストに存在することを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice, invalid_list

    • \n
\n

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

\n

ChoiceField のために、1つの追加の必須引数 choices を取ります。

\n
\n\n
\n
\n

NullBooleanFieldLink to this heading#

\n
\n
\nclass NullBooleanField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: NullBooleanSelect

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Pythonの True、False、または None になります。

    • \n

  • 何も検証しません（つまり、ValidationError を決して発生させません）。

    • \n
\n

NullBooleanField は、ウィジェットの choices を指定することで、 Select や RadioSelect などのウィジェットで使用できます。

\n
Code
NullBooleanField(\n    widget=Select(\n        choices=[\n            ("", "Unknown"),\n            (True, "Yes"),\n            (False, "No"),\n        ]\n    )\n)\n
\n
\n\n
\n
\n

RegexFieldLink to this heading#

\n
\n
\nclass RegexField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: empty_value として指定したものです。

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • RegexValidator を使用して、与えられた値が特定の正規表現と一致するかどうかを検証します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

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

\n
\n
\nregexLink to this definition#
\n

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

\n
\n\n

max_length、min_length、strip、および empty_value も受け取ります。これらは CharField と全く同じように機能します。

\n
\n
\nstripLink to this definition#
\n

デフォルトは False です。有効にした場合、正規表現バリデーションの前にストリップ処理が適用されます。

\n
\n\n
\n\n
\n
\n

SlugFieldLink to this heading#

\n
\n
\nclass SlugField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: empty_value として与えたもの

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • validate_slug または validate_unicode_slug を使用して、与えられた値が文字、数字、アンダースコア、ハイフンのみを含むかを検証します。

    • \n

  • エラーメッセージ: required、invalid

    • \n
\n

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

\n

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

\n
\n
\nallow_unicodeLink to this definition#
\n

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

\n
\n\n
\n
\nempty_valueLink to this definition#
\n

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

\n
\n\n
\n\n
\n
\n

TimeFieldLink to this heading#

\n
\n
\nclass TimeField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TimeInput

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の datetime.time オブジェクトになります。

    • \n

  • 与えられた値が datetime.time か、特定の時間形式でフォーマットされた文字列であることを検証します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

1 つの省略可能な引数を取ります:

\n
\n
\ninput_formatsLink to this definition#
\n

文字列を有効な datetime.time オブジェクトに変換するために試みる形式のイテラブル。

\n
\n\n

input_formats 引数が指定されていない場合、デフォルトの入力形式は、アクティブなロケール形式の TIME_INPUT_FORMATS キーから取得されるか、ローカライズが無効の場合は TIME_INPUT_FORMATS から取得されます。詳細は、表示形式のローカライズ を参照してください。

\n
\n\n
\n
\n

TypedChoiceFieldLink to this heading#

\n
\n
\nclass TypedChoiceField(**kwargs)Link to this definition#
\n

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

\n
    \n

  • デフォルトのウィジェット: Select

    • \n

  • 空の値: empty_value として与えたもの

    • \n

  • 正規化後の値: coerce 引数で指定された型になります。

    • \n

  • 指定された値が選択肢のリストに存在し、強制変換できることを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice

    • \n
\n

追加の引数を取ります:

\n
\n
\ncoerceLink to this definition#
\n

1つの引数を受け取り、強制された値を返す関数です。例には組み込みの int、float、bool、その他の型が含まれます。デフォルトは恒等関数です。強制は入力バリデーションの後に行われるため、choices に存在しない値への強制が可能です。

\n
\n\n
\n
\nempty_valueLink to this definition#
\n

"空" を表すために使用する値です。デフォルトは空文字列です。 None もここでよく使用される選択肢の一つです。この値は、 coerce 引数で与えられた関数によって強制されないことに注意してください。それに応じて選択してください。

\n
\n\n
\n\n
\n
\n

TypedMultipleChoiceFieldLink to this heading#

\n
\n
\nclass TypedMultipleChoiceField(**kwargs)Link to this definition#
\n

MultipleChoiceField と同様ですが、 TypedMultipleChoiceField は coerce と empty_value という2つの追加の引数を受け取ります。

\n
    \n

  • デフォルトのウィジェット: SelectMultiple

    • \n

  • 空の値: empty_value として渡したもの

    • \n

  • 正規化後の値: coerce 引数によって提供される型の値のリストになります。

    • \n

  • 指定された値が選択肢のリスト内に存在し、強制変換できることを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice

    • \n
\n

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

\n

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

\n
\n\n
\n
\n

URLFieldLink to this heading#

\n
\n
\nclass URLField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: URLInput

    • \n

  • 空の値: empty_value として指定したものです。

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • 与えられた値が有効なURLであることを検証するために URLValidator を使用します。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

オプション引数 max_length、min_length、empty_value は CharField での動作と全く同じように機能し、さらにもう一つの引数があります:

\n
\n
\nassume_schemeLink to this definition#
\n

The scheme assumed for URLs provided without one. Defaults to\n"https". For example, if assume_scheme is "https" and the\nprovided value is "example.com", the normalized value will be\n"https://example.com".

\n
\n\n
\n\n
\n
\n

UUIDFieldLink to this heading#

\n
\n
\nclass UUIDField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: UUID オブジェクトに正規化されます。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

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

\n
\n\n
\n
\n
\n

少し複雑な組み込み Field クラスLink to this heading#

\n
\n

ComboFieldLink to this heading#

\n
\n
\nclass ComboField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: '' (空の文字列)

    • \n

  • 正規化後の値: 文字列になります。

    • \n

  • ComboField に引数として指定された各フィールドに対して、与えられた値をバリデーションします。

    • \n

  • エラーメッセージのキー: required、invalid

    • \n
\n

1つの必須の追加引数を受け取ります:

\n
\n
\nfieldsLink to this definition#
\n

フィールドの値を検証するために使用すべきフィールドのリスト(渡した順序で検証されます)。

\n
Python console
>>> 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).']\n
\n
\n\n
\n\n
\n
\n

MultiValueFieldLink to this heading#

\n
\n
\nclass MultiValueField(fields=(), **kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: TextInput

    • \n

  • 空の値: '' (空の文字列)

    • \n

  • 正規化後の値: サブクラスの compress メソッドによって返される型になります。

    • \n

  • 指定された引数としての MultiValueField に各フィールドに対して与えられた値を検証します。

    • \n

  • エラーメッセージキー: required, invalid, incomplete

    • \n
\n

複数のフィールドのロジックを集計し、単一の値を生成します。

\n

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

\n

1つの必須の追加引数を受け取ります:

\n
\n
\nfieldsLink to this definition#
\n

A tuple of fields whose values are cleaned and subsequently combined\ninto a single value. Each value of the field is cleaned by the\ncorresponding field in fields -- the first value is cleaned by the\nfirst field, the second value is cleaned by the second field, etc.\nOnce all fields are cleaned, the list of clean values is combined into\na single value by compress().

\n
\n\n

オプションの引数もいくつか受け取ります:

\n
\n
\nrequire_all_fieldsLink to this definition#
\n

デフォルトは True で、フィールドに値が指定されていない場合は required バリデーションエラーが発生します。

\n

Field.required 属性を False に設定すると、個々のフィールドをオプションフィールドにすることができます。必須フィールドに値が与えられない場合、incomplete というバリデーションエラーが発生します。

\n

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

\n
Code
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        )\n
\n
\n\n
\n
\nwidgetLink to this definition#
\n

django.forms.MultiWidget のサブクラスでなければなりません。デフォルト値は TextInput ですが、この場合にはあまり役に立たないかもしれません。

\n
\n\n
\n
\ncompress(data_list)Link to this definition#
\n

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

\n

このメソッドはサブクラスで実装されなければなりません。

\n
\n\n
\n\n
\n
\n

SplitDateTimeFieldLink to this heading#

\n
\n
\nclass SplitDateTimeField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: SplitDateTimeWidget

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: Python の datetime.datetime オブジェクトになります。

    • \n

  • 指定された値が datetime.datetime または特定の日時形式でフォーマットされた文字列であることを検証します。

    • \n

  • エラーメッセージのキー: required, invalid, invalid_date, invalid_time

    • \n
\n

次の2つの省略可能な引数を取ります:

\n
\n
\ninput_date_formatsLink to this definition#
\n

文字列を有効な datetime.date オブジェクトに変換する試行に使う表示形式のリストです。

\n
\n\n

input_date_formats 引数が提供されない場合、DateField のデフォルトの入力フォーマットが使用されます。

\n
\n
\ninput_time_formatsLink to this definition#
\n

文字列を有効な datetime.time オブジェクトに変換しようとする際に使用されるフォーマットのリスト。

\n
\n\n

input_time_formats 引数が提供されない場合、TimeField のデフォルト入力フォーマットが使用されます。

\n
\n\n
\n
\n
\n

リレーションシップを扱うフィールドLink to this heading#

\n

Two fields are available for representing relationships between\nmodels: ModelChoiceField and\nModelMultipleChoiceField. Both of these fields require a\nsingle queryset parameter that is used to create the choices for\nthe field. Upon form validation, these fields will place either one\nmodel object (in the case of ModelChoiceField) or multiple model\nobjects (in the case of ModelMultipleChoiceField) into the\ncleaned_data dictionary of the form.

\n

より複雑な使い方をする場合は、フォームフィールドを宣言する際に queryset=None を指定し、その後フォームの __init__() メソッド内で queryset を設定できます。

\n
Code
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 = ...\n
\n

ModelChoiceField と ModelMultipleChoiceField には、選択肢を生成する際にクエリセットを繰り返すために使用されるクラスを指定する iterator 属性があります。詳細は、 リレーションシップの選択肢をイテレートする を参照してください。

\n
\n

ModelChoiceFieldLink to this heading#

\n
\n
\nclass ModelChoiceField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: Select

    • \n

  • 空の値: None

    • \n

  • 正規化後の値: model インスタンスに正規化されます。

    • \n

  • 指定された id がクエリセット内に存在することを検証します。

    • \n

  • エラーメッセージのキー: required, invalid_choice

    • \n
\n

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

\n

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

\n

引数が1つ必要です:

\n
\n
\nquerysetLink to this definition#
\n

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

\n
\n\n

ModelChoiceField は他にもいくつかのオプション引数を取ります:

\n
\n
\nempty_labelLink to this definition#
\n

デフォルトでは、ModelChoiceField が使用する <select> ウィジェットには、リストの先頭に空の選択肢が表示されます。このラベルのテキスト（デフォルトでは "---------"）を empty_label 属性で変更したり、empty_label を None に設定することで空のラベルを完全に無効にできます:

\n
Code
# A custom empty label\nfield1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")\n\n# No empty label\nfield2 = forms.ModelChoiceField(queryset=..., empty_label=None)\n
\n

ModelChoiceField が必須でデフォルトの初期値を持っている場合や、widget が RadioSelect に設定されており blank 引数が False の場合には、 empty_label の値に関係なく空の選択肢は作成されません。

\n
\n\n
\n
\nto_field_nameLink to this definition#
\n

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

\n
Code
# No custom to_field_name\nfield1 = forms.ModelChoiceField(queryset=...)\n
\n

上記によって、下記が得られます:

\n
Html
<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

そして、:

\n
Code
# to_field_name provided\nfield2 = forms.ModelChoiceField(queryset=..., to_field_name="name")\n
\n

上記によって、下記が得られます:

\n
Html
<select id="id_field2" name="field2">\n<option value="obj1.name">Object1</option>\n<option value="obj2.name">Object2</option>\n...\n</select>\n
\n
\n\n
\n
\nblankLink to this definition#
\n

RadioSelect ウィジェットを使用する場合、このオプションのブール引数は空の選択肢を作成するかどうかを決定します。デフォルトでは、blank は False で、空の選択肢は作成されません。

\n
\n\n

ModelChoiceField には、以下の属性もあります:

\n
\n
\niteratorLink to this definition#
\n

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

\n
\n\n

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

\n
Code
from django.forms import ModelChoiceField\n\n\nclass MyModelChoiceField(ModelChoiceField):\n    def label_from_instance(self, obj):\n        return "My Object #%i" % obj.id\n
\n
\n\n
\n
\n

ModelMultipleChoiceFieldLink to this heading#

\n
\n
\nclass ModelMultipleChoiceField(**kwargs)Link to this definition#
\n
    \n

  • デフォルトのウィジェット: SelectMultiple

    • \n

  • 空の値: 空の QuerySet (self.queryset.none())

    • \n

  • 正規化後の値: モデルインスタンスの QuerySet になります。

    • \n

  • 与えられた値のリスト内のすべてのIDがクエリセット内に存在することを検証します。

    • \n

  • エラーメッセージのキー: required、 invalid_list、 invalid_choice、 invalid_pk_value

    • \n
\n

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

\n

一つまたは複数のモデルオブジェクトを選択できるようにし、多対多のリレーションシップを表すのに適しています。ModelChoiceField と同様に, label_from_instance を使用してオブジェクトの表現をカスタマイズできます。

\n

引数が1つ必要です:

\n
\n
\nquerysetLink to this definition#
\n

ModelChoiceField.queryset と同じです。

\n
\n\n

1 つの省略可能な引数を取ります:

\n
\n
\nto_field_nameLink to this definition#
\n

ModelChoiceField.to_field_name と同じです。

\n
\n\n

ModelMultipleChoiceField には次の属性もあります:

\n
\n
\niteratorLink to this definition#
\n

ModelChoiceField.iterator と同じです。

\n
\n\n
\n\n
\n
\n

リレーションシップの選択肢をイテレートするLink to this heading#

\n

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

\n

ModelChoiceIterator をイテレートすると、1つ目の value 要素として ModelChoiceIteratorValue インスタンスを含む2値タプルの選択肢が生成されます。 ModelChoiceIteratorValue は、選択値をラップし、カスタムウィジェットの実装で使用できる元のモデルインスタンスへの参照を保持します。たとえば、 <option> 要素に data-* attributes を追加するのに使用できます。

\n

例として、以下のモデルを考えてみましょう:

\n
Code
from 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)\n
\n

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

\n
Code
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
\n

これにより、Pizza.topping 選択肢は以下のようにレンダリングされます:

\n
Html
<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
\n

より高度な使い方をする場合は、 ModelChoiceIterator をサブクラスにして、得られる2値タプルの選択肢をカスタマイズできます。

\n
\n

ModelChoiceIteratorLink to this heading#

\n
\n
\nclass ModelChoiceIterator(field)Link to this definition#
\n

ModelChoiceField と ModelMultipleChoiceField の iterator 属性に割り当てられたデフォルトのクラスです。クエリセットから 2 タプルの選択肢を返すイテレータです。

\n

引数が1つ必要です:

\n
\n
\nfieldLink to this definition#
\n

ModelChoiceField または ModelMultipleChoiceField のインスタンスをイテレートして選択肢を生成します。

\n
\n\n

ModelChoiceIterator には、以下のメソッドがあります:

\n
\n
\n__iter__()Link to this definition#
\n

ChoiceField.choices で使用される (value, label) フォーマットの 2値タプルの選択肢を生成します。最初の value 要素は ModelChoiceIteratorValue インスタンスです。

\n
\n\n
\n\n
\n
\n

ModelChoiceIteratorValueLink to this heading#

\n
\n
\nclass ModelChoiceIteratorValue(value, instance)Link to this definition#
\n

2 つの引数が必要です:

\n
\n
\nvalueLink to this definition#
\n

選択肢の値です。HTMLの <option> 要素の value 属性のレンダリングに使用されます。

\n
\n\n
\n
\ninstanceLink to this definition#
\n

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

\n
\n\n

ModelChoiceIteratorValue には次のメソッドがあります:

\n
\n
\n__str__()Link to this definition#
\n

value を HTML でレンダリングするための文字列として返します。

\n
\n\n
\n\n
\n
\n
\n
\n

カスタムフィールドの作成Link to this heading#

\n

組み込みの Field クラスが要件を満たさない場合は、カスタムの Field クラスを作成できます。これには、 django.forms.Field のサブクラスを作成します。唯一の要件は、 clean() メソッドを実装し、 __init__() メソッドが上述の基本的な引数 (required, label, initial, widget, help_text) を受け入れることです。

\n

You can also customize how a field will be accessed by overriding\nbound_field_class or override\nField.get_bound_field() if you need more flexibility when creating\nthe BoundField:

\n
\n
\nField.get_bound_field(form, field_name)Link to this definition#
\n

Form のインスタンスとフィールド名を引数に取り、対応する BoundField インスタンスを返します。この返された BoundField は、テンプレート内でそのフィールドにアクセスする際に使用されます。

\n
\n\n

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

\n
","rootId":"module-django.forms.fields","toc":[{"title":"field のコアとなる引数","anchor":"core-field-arguments","children":[{"title":"required","anchor":"required","children":[]},{"title":"label","anchor":"label","children":[]},{"title":"label_suffix","anchor":"label-suffix","children":[]},{"title":"initial","anchor":"initial","children":[]},{"title":"widget","anchor":"widget","children":[]},{"title":"help_text","anchor":"help-text","children":[]},{"title":"error_messages","anchor":"error-messages","children":[]},{"title":"validators","anchor":"validators","children":[]},{"title":"localize","anchor":"localize","children":[]},{"title":"disabled","anchor":"disabled","children":[]},{"title":"template_name","anchor":"template-name","children":[]},{"title":"bound_field_class","anchor":"bound-field-class","children":[]}]},{"title":"フィールドのデータの変更チェック","anchor":"checking-if-the-field-data-has-changed","children":[{"title":"has_changed()","anchor":"has-changed","children":[]}]},{"title":"ビルトインの Field クラス","anchor":"built-in-field-classes","children":[{"title":"BooleanField","anchor":"booleanfield","children":[]},{"title":"CharField","anchor":"charfield","children":[]},{"title":"ChoiceField","anchor":"choicefield","children":[]},{"title":"DateField","anchor":"datefield","children":[]},{"title":"DateTimeField","anchor":"datetimefield","children":[]},{"title":"DecimalField","anchor":"decimalfield","children":[]},{"title":"DurationField","anchor":"durationfield","children":[]},{"title":"EmailField","anchor":"emailfield","children":[]},{"title":"FileField","anchor":"filefield","children":[]},{"title":"FilePathField","anchor":"filepathfield","children":[]},{"title":"FloatField","anchor":"floatfield","children":[]},{"title":"GenericIPAddressField","anchor":"genericipaddressfield","children":[]},{"title":"ImageField","anchor":"imagefield","children":[]},{"title":"IntegerField","anchor":"integerfield","children":[]},{"title":"JSONField","anchor":"jsonfield","children":[]},{"title":"MultipleChoiceField","anchor":"multiplechoicefield","children":[]},{"title":"NullBooleanField","anchor":"nullbooleanfield","children":[]},{"title":"RegexField","anchor":"regexfield","children":[]},{"title":"SlugField","anchor":"slugfield","children":[]},{"title":"TimeField","anchor":"timefield","children":[]},{"title":"TypedChoiceField","anchor":"typedchoicefield","children":[]},{"title":"TypedMultipleChoiceField","anchor":"typedmultiplechoicefield","children":[]},{"title":"URLField","anchor":"urlfield","children":[]},{"title":"UUIDField","anchor":"uuidfield","children":[]}]},{"title":"少し複雑な組み込み Field クラス","anchor":"slightly-complex-built-in-field-classes","children":[{"title":"ComboField","anchor":"combofield","children":[]},{"title":"MultiValueField","anchor":"multivaluefield","children":[]},{"title":"SplitDateTimeField","anchor":"splitdatetimefield","children":[]}]},{"title":"リレーションシップを扱うフィールド","anchor":"fields-which-handle-relationships","children":[{"title":"ModelChoiceField","anchor":"modelchoicefield","children":[]},{"title":"ModelMultipleChoiceField","anchor":"modelmultiplechoicefield","children":[]},{"title":"リレーションシップの選択肢をイテレートする","anchor":"iterating-relationship-choices","children":[{"title":"ModelChoiceIterator","anchor":"modelchoiceiterator","children":[]},{"title":"ModelChoiceIteratorValue","anchor":"modelchoiceiteratorvalue","children":[]}]}]},{"title":"カスタムフィールドの作成","anchor":"creating-custom-fields","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"API リファレンス","url":"/ja/6.0/ref/"},{"docname":"ref/forms/index","title":"フォーム","url":"/ja/6.0/ref/forms/"}],"prev":{"docname":"ref/forms/api","title":"フォーム API","url":"/ja/6.0/ref/forms/api/"},"next":{"docname":"ref/forms/models","title":"モデルフォーム","url":"/ja/6.0/ref/forms/models/"},"formats":{"html":"/ja/6.0/ref/forms/fields/","markdown":"/ja/6.0/ref/forms/fields.md","json":"/ja/6.0/ref/forms/fields.json"},"source":"https://github.com/django/django/blob/stable/6.0.x/docs/ref/forms/fields.txt","official":"https://docs.djangoproject.com/ja/6.0/ref/forms/fields/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}