---
title: "フォーム フィールド"
version: 6.0
locale: ja
source: https://docs.djangoproject.com/ja/6.0/ref/forms/fields/
canonical: https://djangodocs.dev/ja/6.0/ref/forms/fields/
---
# フォーム フィールド

#### `class Field`

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

#### `Field.clean(value)`

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

```pycon
>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("foo@example.com")
'foo@example.com'
>>> f.clean("invalid email address")
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']
```

## field のコアとなる引数

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

### `required`

#### `Field.required`

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

```pycon
>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
```

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

```pycon
>>> f = forms.CharField(required=False)
>>> f.clean("foo")
'foo'
>>> f.clean("")
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
```

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

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

### `label`

#### `Field.label`

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

As explained in [フォームをHTMLとしてアウトプットする](/ja/6.0/ref/forms/api/#ref-forms-api-outputting-html), the default label for a
`Field` is generated from the field name by converting all underscores to
spaces and upper-casing the first letter. Specify a string for `label` if
that default behavior doesn't result in an adequate label. Use an empty string
(`""`) to hide the label.

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

```pycon
>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label="Your name")
...     url = forms.URLField(label="Your website", required=False)
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>
```

### `label_suffix`

#### `Field.label_suffix`

`label_suffix` 引数を使用すると、フォームの [`label_suffix`](/ja/6.0/ref/forms/api/#django.forms.Form.label_suffix) をフィールドごとに上書きできます。

```pycon
>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")
...
>>> f = ContactForm(label_suffix="?")
>>> print(f)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>
```

### `initial`

#### `Field.initial`

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

動的に初期値を指定する方法は、[`Form.initial`](/ja/6.0/ref/forms/api/#django.forms.Form.initial) パラメータを参照してください。

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

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

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

```pycon
>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
...
>>> default_data = {"name": "Your name", "url": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
  <input type="text" name="name" value="Your name" required>
</div>
<div>Url:
  <ul class="errorlist"><li>Enter a valid URL.</li></ul>
  <input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
  <ul class="errorlist"><li>This field is required.</li></ul>
  <input type="text" name="comment" required aria-invalid="true">
</div>
```

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

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

```pycon
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}
```

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

```pycon
>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
...
>>> print(DateForm())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>
```

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

### `widget`

#### `Field.widget`

`widget` 引数は、`Field` をレンダリングするときに使う `Widget` クラスを指定します。詳しくは [ウィジェット](/ja/6.0/ref/forms/widgets/) を参照してください。

### `help_text`

#### `Field.help_text`

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

モデルフィールドの [`help_text`](/ja/6.0/ref/models/fields/#django.db.models.Field.help_text) と同じく、値は自動的に生成されるフォーム内で HTML 用にエスケープされません。

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

```pycon
>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text="100 characters max.")
...     message = forms.CharField()
...     contact_email = forms.EmailField(help_text="Your email (so we can reply).")
...
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Contact email:<div class="helptext">Your email (so we can reply).</div><input type="email" name="contact_email" maxlength="320" required></div>
```

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

```pycon
>>> from django import forms
>>> class UserForm(forms.Form):
...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>
```

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

```pycon
>>> class UserForm(forms.Form):
...     username = forms.CharField(
...         max_length=255,
...         help_text="e.g., user@example.com",
...         widget=forms.TextInput(
...             attrs={"aria-describedby": "custom-description id_username_helptext"},
...         ),
...     )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>
```

### `error_messages`

#### `Field.error_messages`

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

```pycon
>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']
```

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

```pycon
>>> name = forms.CharField(error_messages={"required": "Please enter your name"})
>>> name.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']
```

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

### `validators`

#### `Field.validators`

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

詳しくは [バリデータのドキュメント](/ja/6.0/ref/validators/) を参照してください。

### `localize`

#### `Field.localize`

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

詳細については、[フォーマットのローカライズに関するドキュメント](/ja/6.0/topics/i18n/formatting/) を参照してください。

### `disabled`

#### `Field.disabled`

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

### `template_name`

#### `Field.template_name`

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

### `bound_field_class`

#### `Field.bound_field_class`

> **New in Django 5.2**

`bound_field_class` 属性を使用すれば、 [`Form.bound_field_class`](/ja/6.0/ref/forms/api/#django.forms.Form.bound_field_class) をフィールドごとにオーバーライドすることができます。

## フィールドのデータの変更チェック

### `has_changed()`

#### `Field.has_changed()`

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

See the [`Form.has_changed`](/ja/6.0/ref/forms/api/#django.forms.Form.has_changed) documentation for more information.

## ビルトインの `Field` クラス

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

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

### `BooleanField`

#### `class BooleanField(**kwargs)`

- デフォルトのウィジェット: [`CheckboxInput`](/ja/6.0/ref/forms/widgets/#django.forms.CheckboxInput)
- 空の値: `False`
- 正規化後の値: Pythonの `True` または `False` になります。
- フィールドが `required=True` を持つ場合、値が `True` (例えば、チェックボックスがチェックされている)であることを確認します。
- エラーメッセージのキー: `required`

> **Note**
>
> すべての `Field` のサブクラスはデフォルトで `required=True` ですので、ここでのバリデーション条件は重要です。フォームに True または False のどちらかであるブール値 (たとえば、チェックありまたはチェックなしのチェックボックス) を含めたい場合は、 `BooleanField` を作成する際に `required=False` を渡すことを忘れないでください。

### `CharField`

#### `class CharField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: [`empty_value`](#django.forms.CharField.empty_value) として与えたもの
- 正規化後の値: 文字列になります。
- `max_length` と `min_length` が与えられた場合は、[`MaxLengthValidator`](/ja/6.0/ref/validators/#django.core.validators.MaxLengthValidator) と [`MinLengthValidator`](/ja/6.0/ref/validators/#django.core.validators.MinLengthValidator) を使用します。それ以外の場合は、すべての入力が有効です。
- エラーメッセージキー: `required`, `max_length`, `min_length`

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

#### `max_length`

#### `min_length`

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

#### `strip`

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

#### `empty_value`

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

### `ChoiceField`

#### `class ChoiceField(**kwargs)`

- デフォルトのウィジェット: [`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select)
- 空の値: `''` (空の文字列)
- 正規化後の値: 文字列になります。
- 指定された値が選択肢のリスト内に存在することを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`

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

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

#### `choices`

このフィールドの選択肢として使用する2値タプルの [iterable](https://docs.python.org/3/glossary.html#term-iterable) 、 [列挙型](/ja/6.0/ref/models/fields/#field-choices-enum-types) 、またはそのようなイテラブルを返す呼び出し可能オブジェクトのいずれか。この引数は、モデルフィールドの `choices` 引数と同じ形式を受け入れます。詳細については、 [モデルフィールドのリファレンスドキュメント](/ja/6.0/ref/models/fields/#field-choices) を参照してください。引数が呼び出し可能オブジェクトの場合、フィールドのフォームが初期化されるたび、およびレンダリング中に評価されます。デフォルトは空のリストです。

> **選択肢 (Choice) 型**
>
> このフィールドは選択肢を文字列に正規化するため、整数やブール値など、他のデータ型で選択肢が必要な場合は、代わりに [`TypedChoiceField`](#django.forms.TypedChoiceField) を使用することを検討してください。

### `DateField`

#### `class DateField(**kwargs)`

- デフォルトのウィジェット: [`DateInput`](/ja/6.0/ref/forms/widgets/#django.forms.DateInput)
- 空の値: `None`
- 正規化後の値: Python の `datetime.date` オブジェクトになります。
- 与えられた値が `datetime.date`、`datetime.datetime` または特定の日付の表示形式のどれかに当てはまるか検証します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `input_formats`

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

`input_formats` 引数が指定されていない場合、デフォルトの入力形式は有効なロケール形式の `DATE_INPUT_FORMATS` キーから取得されるか、ローカライズが無効になっている場合は [`DATE_INPUT_FORMATS`](/ja/6.0/ref/settings/#std-setting-DATE_INPUT_FORMATS) から取得されます。また、 [表示形式のローカライズ](/ja/6.0/topics/i18n/formatting/) も参照してください。

### `DateTimeField`

#### `class DateTimeField(**kwargs)`

- デフォルトのウィジェット: [`DateTimeInput`](/ja/6.0/ref/forms/widgets/#django.forms.DateTimeInput)
- 空の値: `None`
- 正規化後の値: Python の `datetime.datetime` オブジェクトになります。
- 与えられた値が `datetime.datetime`、`datetime.date` または特定の日時の表示形式の文字列のどれかに当てはまるか検証します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `input_formats`

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

このフィールドは常に、ISO 8601形式の日付や [`parse_datetime()`](/ja/6.0/ref/utils/#django.utils.dateparse.parse_datetime) で認識される類似の形式の文字列を受け付けます。いくつかの例を挙げます:

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

`input_formats` 引数が提供されない場合、デフォルトの入力フォーマットはアクティブなロケールフォーマットの `DATETIME_INPUT_FORMATS` と `DATE_INPUT_FORMATS` キーから取得されます。もしくは、ローカライズが無効の場合は [`DATETIME_INPUT_FORMATS`](/ja/6.0/ref/settings/#std-setting-DATETIME_INPUT_FORMATS) と [`DATE_INPUT_FORMATS`](/ja/6.0/ref/settings/#std-setting-DATE_INPUT_FORMATS) から取得されます。また、表示形式のローカライズについては [表示形式のローカライズ](/ja/6.0/topics/i18n/formatting/) も参照してください。

### `DecimalField`

#### `class DecimalField(**kwargs)`

- デフォルトのウィジェット: [`Field.localize`](#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.0/ref/forms/widgets/#django.forms.NumberInput)、`True` のとき [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput).
- 空の値: `None`
- 正規化後の値: Python の `decimal` になります。
- 指定された値が10進数であることを検証します。 `max_value` と `min_value` が提供されている場合は [`MaxValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MaxValueValidator) および [`MinValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MinValueValidator) を使用します。 `step_size` が提供されている場合は [`StepValueValidator`](/ja/6.0/ref/validators/#django.core.validators.StepValueValidator) を使用します。先頭及び末尾の空白は無視されます。
- エラーメッセージのキー: `required`, `invalid`, `max_value`, `min_value`, `max_digits`, `max_decimal_places`, `max_whole_digits`, `step_size` 。

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

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

#### `max_value`

#### `min_value`

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

#### `max_digits`

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

#### `decimal_places`

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

#### `step_size`

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

### `DurationField`

#### `class DurationField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `None`
- 正規化後の値: Python の [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) になります。
- 指定された値が `timedelta` に変換できる文字列であることを検証します。値は [`datetime.timedelta.min`](https://docs.python.org/3/library/datetime.html#datetime.timedelta.min) と [`datetime.timedelta.max`](https://docs.python.org/3/library/datetime.html#datetime.timedelta.max) の間でなければなりません。
- エラーメッセージのキー: `required`、`invalid`、`overflow` 。

[`parse_duration()`](/ja/6.0/ref/utils/#django.utils.dateparse.parse_duration) が理解できるどんな形式でも受け入れます。

### `EmailField`

#### `class EmailField(**kwargs)`

- デフォルトのウィジェット: [`EmailInput`](/ja/6.0/ref/forms/widgets/#django.forms.EmailInput)
- 空の値: `empty_value` として指定したものです。
- 正規化後の値: 文字列になります。
- [`EmailValidator`](/ja/6.0/ref/validators/#django.core.validators.EmailValidator) を使用して、与えられた値が有効なメールアドレスであることを、比較的複雑な正規表現を使用してバリデーションします。
- エラーメッセージのキー: `required`、`invalid`

オプション引数として `max_length`、`min_length`、`empty_value` があり、[`CharField`](#django.forms.CharField) と同じように機能します。 `max_length` 引数のデフォルト値は320です( [**RFC 3696 Section 3**](https://datatracker.ietf.org/doc/html/rfc3696.html#section-3) を参照)。

### `FileField`

#### `class FileField(**kwargs)`

- デフォルトのウィジェット: [`ClearableFileInput`](/ja/6.0/ref/forms/widgets/#django.forms.ClearableFileInput)
- 空の値: `None`
- ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした `UploadedFile` オブジェクトに正規化されます。
- フォームに空でないファイルデータがバインドされていることをバリデーションできます。
- エラーメッセージのキー: `required`, `invalid`, `missing`, `empty`, `max_length`

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

`UploadedFile` オブジェクトについて詳しく知るには、 [ファイルのアップロードのドキュメント](/ja/6.0/topics/http/file-uploads/) を読んでください。

フォーム内で `FileField` を使用する時は、[ファイルのデータをフォームにバインド](/ja/6.0/ref/forms/api/#binding-uploaded-files) することも必要です。

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

### `FilePathField`

#### `class FilePathField(**kwargs)`

- デフォルトのウィジェット: [`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select)
- 空の値: `''` (空の文字列)
- 正規化後の値: 文字列になります。
- 選択された選択肢が選択肢のリストに存在することを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`

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

#### `path`

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

#### `recursive`

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

#### `match`

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

#### `allow_files`

Optional. Either `True` or `False`. Default is `True`. Specifies
whether files in the specified location should be included. Either this
or [`allow_folders`](#django.forms.FilePathField.allow_folders) must be `True`.

#### `allow_folders`

Optional. Either `True` or `False`. Default is `False`. Specifies
whether folders in the specified location should be included. Either
this or [`allow_files`](#django.forms.FilePathField.allow_files) must be `True`.

### `FloatField`

#### `class FloatField(**kwargs)`

- デフォルトのウィジェット: [`Field.localize`](#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.0/ref/forms/widgets/#django.forms.NumberInput)、`True` のとき [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput).
- 空の値: `None`
- 正規化後の値: Python の float になります。
- 指定された値が float であることを検証します。 `max_value` と `min_value` が提供されている場合は [`MaxValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MaxValueValidator) と [`MinValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MinValueValidator) を使用します。`step_size` が提供されている場合は [`StepValueValidator`](/ja/6.0/ref/validators/#django.core.validators.StepValueValidator) を使用します。Python の `float()` 関数と同様、先頭と末尾の空白は許可されます。
- エラーメッセージのキー: `required`、`invalid`、`max_value`、`min_value`、`step_size` 。

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

#### `max_value`

#### `min_value`

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

#### `step_size`

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

### `GenericIPAddressField`

#### `class GenericIPAddressField(**kwargs)`

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

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `''` (空の文字列)
- 正規化後の値: 文字列。以下の説明に従って、IPv6 アドレスは正規化されます。
- 与えられた値が有効な IP アドレスを表しているか検証します。
- エラーメッセージキー: `required`, `invalid`, `max_length`

IPv6 アドレスは、 [**RFC 4291 Section 2.2**](https://datatracker.ietf.org/doc/html/rfc4291.html#section-2.2) section 2.2 (同セクションの paragraph 3 で提案された IPv4 のフォーマットの使用を含む) にしたがって、 `::ffff:192.0.2.0` のように正規化します。たとえば、 `2001:0::0:01` は `2001::1` と正規化され、 `::ffff:0a0a:0a0a` は `::ffff:10.10.10.10` と正規化されます。そして、すべての文字は小文字に変換されます。

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

#### `protocol`

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

#### `unpack_ipv4`

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

#### `max_length`

デフォルトは 39 で、[`CharField`](#django.forms.CharField) に対する場合と同様の動作をします。

### `ImageField`

#### `class ImageField(**kwargs)`

- デフォルトのウィジェット: [`ClearableFileInput`](/ja/6.0/ref/forms/widgets/#django.forms.ClearableFileInput)
- 空の値: `None`
- ファイルコンテンツとファイル名を1つのオブジェクトにラッピングした `UploadedFile` オブジェクトに正規化されます。
- ファイルデータがフォームにバインドされたことを検証します。また、 [`FileExtensionValidator`](/ja/6.0/ref/validators/#django.core.validators.FileExtensionValidator) を使用して、ファイルの拡張子が Pillow でサポートされているかを検証します。
- エラーメッセージのキー: `required`, `invalid`, `missing`, `empty`, `invalid_image`

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

フォームで `ImageField` を使用する場合、[フォームにファイルデータをバインドする](/ja/6.0/ref/forms/api/#binding-uploaded-files) 必要も覚えておいてください。

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

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

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

### `IntegerField`

#### `class IntegerField(**kwargs)`

- デフォルトのウィジェット: [`Field.localize`](#django.forms.Field.localize) が `False` のとき [`NumberInput`](/ja/6.0/ref/forms/widgets/#django.forms.NumberInput)、`True` のとき [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput).
- 空の値: `None`
- 正規化後の値: Python の整数になります。
- 与えられた値が整数であることを検証します。`max_value` と `min_value` が提供されている場合は [`MaxValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MaxValueValidator) と [`MinValueValidator`](/ja/6.0/ref/validators/#django.core.validators.MinValueValidator) を使用します。`step_size` が提供されている場合は [`StepValueValidator`](/ja/6.0/ref/validators/#django.core.validators.StepValueValidator) を使用します。Python の `int()` 関数と同様、先頭と末尾の空白は許可されます。
- エラーメッセージキー: `required`, `invalid`, `max_value`, `min_value`, `step_size`

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

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

#### `max_value`

#### `min_value`

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

#### `step_size`

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

### `JSONField`

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

[`JSONField`](/ja/6.0/ref/models/fields/#django.db.models.JSONField) 用の、JSON エンコードされたデータを受け入れるフィールドです。

- デフォルトのウィジェット: [`Textarea`](/ja/6.0/ref/forms/widgets/#django.forms.Textarea)
- 空の値: `None`
- 正規化後の値: [`JSONField.decoder`](#django.forms.JSONField.decoder) に依存して、JSON 値の Python 表現 (通常は `dict`、`list`、または `None`) に正規化されます。
- 与えられた値が有効な JSON であることを検証します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `encoder`

A [`json.JSONEncoder`](https://docs.python.org/3/library/json.html#json.JSONEncoder) subclass to serialize data types not
supported by the standard JSON serializer (e.g. `datetime.datetime`
or [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)). For example, you can use the
[`DjangoJSONEncoder`](/ja/6.0/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder) class.

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

#### `decoder`

A [`json.JSONDecoder`](https://docs.python.org/3/library/json.html#json.JSONDecoder) subclass to deserialize the input. Your
deserialization may need to account for the fact that you can't be
certain of the input type. For example, you run the risk of returning a
`datetime` that was actually a string that just happened to be in the
same format chosen for `datetime`s.

The `decoder` can be used to validate the input. If
[`json.JSONDecodeError`](https://docs.python.org/3/library/json.html#json.JSONDecodeError) is raised during the deserialization,
a `ValidationError` will be raised.

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

> **Note**
>
> [`ModelForm`](/ja/6.0/topics/forms/modelforms/#django.forms.ModelForm) を使用する場合、[`JSONField`](/ja/6.0/ref/models/fields/#django.db.models.JSONField) からの `encoder` と `decoder` が使用されます。

> **ユーザーフレンドリーなフォーム**
>
> `JSONField` は多くの場合、ユーザーフレンドリーとは言えません。しかし、クライアントサイドのウィジェットからサーバーに送信するためのデータをフォーマットする便利な方法です。

### `MultipleChoiceField`

#### `class MultipleChoiceField(**kwargs)`

- デフォルトのウィジェット: [`SelectMultiple`](/ja/6.0/ref/forms/widgets/#django.forms.SelectMultiple)
- 空の値: `[]` (空のリスト)
- 正規化後の値: 文字列のリストになります。
- 与えられた値のリストの各値が、選択肢のリストに存在することを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`, `invalid_list`

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

[`ChoiceField`](#django.forms.ChoiceField) のために、1つの追加の必須引数 `choices` を取ります。

### `NullBooleanField`

#### `class NullBooleanField(**kwargs)`

- デフォルトのウィジェット: [`NullBooleanSelect`](/ja/6.0/ref/forms/widgets/#django.forms.NullBooleanSelect)
- 空の値: `None`
- 正規化後の値: Pythonの `True`、`False`、または `None` になります。
- 何も検証しません（つまり、`ValidationError` を決して発生させません）。

`NullBooleanField` は、ウィジェットの `choices` を指定することで、 [`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select) や [`RadioSelect`](/ja/6.0/ref/forms/widgets/#django.forms.RadioSelect) などのウィジェットで使用できます。

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

### `RegexField`

#### `class RegexField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `empty_value` として指定したものです。
- 正規化後の値: 文字列になります。
- [`RegexValidator`](/ja/6.0/ref/validators/#django.core.validators.RegexValidator) を使用して、与えられた値が特定の正規表現と一致するかどうかを検証します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `regex`

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

`max_length`、`min_length`、`strip`、および `empty_value` も受け取ります。これらは [`CharField`](#django.forms.CharField) と全く同じように機能します。

#### `strip`

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

### `SlugField`

#### `class SlugField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: [`empty_value`](#django.forms.SlugField.empty_value) として与えたもの
- 正規化後の値: 文字列になります。
- [`validate_slug`](/ja/6.0/ref/validators/#django.core.validators.validate_slug) または [`validate_unicode_slug`](/ja/6.0/ref/validators/#django.core.validators.validate_unicode_slug) を使用して、与えられた値が文字、数字、アンダースコア、ハイフンのみを含むかを検証します。
- エラーメッセージ: `required`、`invalid`

このフィールドは、フォームでモデルの [`SlugField`](/ja/6.0/ref/models/fields/#django.db.models.SlugField) を表現するために使用することを意図しています。

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

#### `allow_unicode`

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

#### `empty_value`

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

### `TimeField`

#### `class TimeField(**kwargs)`

- デフォルトのウィジェット: [`TimeInput`](/ja/6.0/ref/forms/widgets/#django.forms.TimeInput)
- 空の値: `None`
- 正規化後の値: Python の `datetime.time` オブジェクトになります。
- 与えられた値が `datetime.time` か、特定の時間形式でフォーマットされた文字列であることを検証します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `input_formats`

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

`input_formats` 引数が指定されていない場合、デフォルトの入力形式は、アクティブなロケール形式の `TIME_INPUT_FORMATS` キーから取得されるか、ローカライズが無効の場合は [`TIME_INPUT_FORMATS`](/ja/6.0/ref/settings/#std-setting-TIME_INPUT_FORMATS) から取得されます。詳細は、[表示形式のローカライズ](/ja/6.0/topics/i18n/formatting/) を参照してください。

### `TypedChoiceField`

#### `class TypedChoiceField(**kwargs)`

[`ChoiceField`](#django.forms.ChoiceField) と同様ですが、 [`TypedChoiceField`](#django.forms.TypedChoiceField) は2つの追加引数、 [`coerce`](#django.forms.TypedChoiceField.coerce) と [`empty_value`](#django.forms.TypedChoiceField.empty_value) を取ります。

- デフォルトのウィジェット: [`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select)
- 空の値: [`empty_value`](#django.forms.TypedChoiceField.empty_value) として与えたもの
- 正規化後の値: [`coerce`](#django.forms.TypedChoiceField.coerce) 引数で指定された型になります。
- 指定された値が選択肢のリストに存在し、強制変換できることを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`

追加の引数を取ります:

#### `coerce`

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

#### `empty_value`

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

### `TypedMultipleChoiceField`

#### `class TypedMultipleChoiceField(**kwargs)`

[`MultipleChoiceField`](#django.forms.MultipleChoiceField) と同様ですが、 [`TypedMultipleChoiceField`](#django.forms.TypedMultipleChoiceField) は `coerce` と `empty_value` という2つの追加の引数を受け取ります。

- デフォルトのウィジェット: [`SelectMultiple`](/ja/6.0/ref/forms/widgets/#django.forms.SelectMultiple)
- 空の値: `empty_value` として渡したもの
- 正規化後の値: `coerce` 引数によって提供される型の値のリストになります。
- 指定された値が選択肢のリスト内に存在し、強制変換できることを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`

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

[`TypedChoiceField`](#django.forms.TypedChoiceField) と同様に、2つの追加引数 `coerce` と `empty_value` を取ります。

### `URLField`

#### `class URLField(**kwargs)`

- デフォルトのウィジェット: [`URLInput`](/ja/6.0/ref/forms/widgets/#django.forms.URLInput)
- 空の値: `empty_value` として指定したものです。
- 正規化後の値: 文字列になります。
- 与えられた値が有効なURLであることを検証するために [`URLValidator`](/ja/6.0/ref/validators/#django.core.validators.URLValidator) を使用します。
- エラーメッセージのキー: `required`、`invalid`

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

#### `assume_scheme`

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

### `UUIDField`

#### `class UUIDField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `None`
- 正規化後の値: [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID) オブジェクトに正規化されます。
- エラーメッセージのキー: `required`、`invalid`

このフィールドは、 [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID) コンストラクタの `hex` 引数として受け入れられる任意の文字列形式を受け付けます。

## 少し複雑な組み込み `Field` クラス

### `ComboField`

#### `class ComboField(**kwargs)`

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `''` (空の文字列)
- 正規化後の値: 文字列になります。
- `ComboField` に引数として指定された各フィールドに対して、与えられた値をバリデーションします。
- エラーメッセージのキー: `required`、`invalid`

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

#### `fields`

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

```pycon
>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean("test@example.com")
'test@example.com'
>>> f.clean("longemailaddress@example.com")
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
```

### `MultiValueField`

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

- デフォルトのウィジェット: [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput)
- 空の値: `''` (空の文字列)
- 正規化後の値: サブクラスの `compress` メソッドによって返される型になります。
- 指定された引数としての `MultiValueField` に各フィールドに対して与えられた値を検証します。
- エラーメッセージキー: `required`, `invalid`, `incomplete`

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

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

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

#### `fields`

A tuple of fields whose values are cleaned and subsequently combined
into a single value. Each value of the field is cleaned by the
corresponding field in `fields` -- the first value is cleaned by the
first field, the second value is cleaned by the second field, etc.
Once all fields are cleaned, the list of clean values is combined into
a single value by [`compress()`](#django.forms.MultiValueField.compress).

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

#### `require_all_fields`

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

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

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

```
from django.core.validators import RegexValidator

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

#### `widget`

[`django.forms.MultiWidget`](/ja/6.0/ref/forms/widgets/#django.forms.MultiWidget) のサブクラスでなければなりません。デフォルト値は [`TextInput`](/ja/6.0/ref/forms/widgets/#django.forms.TextInput) ですが、この場合にはあまり役に立たないかもしれません。

#### `compress(data_list)`

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

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

### `SplitDateTimeField`

#### `class SplitDateTimeField(**kwargs)`

- デフォルトのウィジェット: [`SplitDateTimeWidget`](/ja/6.0/ref/forms/widgets/#django.forms.SplitDateTimeWidget)
- 空の値: `None`
- 正規化後の値: Python の `datetime.datetime` オブジェクトになります。
- 指定された値が `datetime.datetime` または特定の日時形式でフォーマットされた文字列であることを検証します。
- エラーメッセージのキー: `required`, `invalid`, `invalid_date`, `invalid_time`

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

#### `input_date_formats`

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

`input_date_formats` 引数が提供されない場合、[`DateField`](#django.forms.DateField) のデフォルトの入力フォーマットが使用されます。

#### `input_time_formats`

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

`input_time_formats` 引数が提供されない場合、[`TimeField`](#django.forms.TimeField) のデフォルト入力フォーマットが使用されます。

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

Two fields are available for representing relationships between
models: [`ModelChoiceField`](#django.forms.ModelChoiceField) and
[`ModelMultipleChoiceField`](#django.forms.ModelMultipleChoiceField). Both of these fields require a
single `queryset` parameter that is used to create the choices for
the field. Upon form validation, these fields will place either one
model object (in the case of `ModelChoiceField`) or multiple model
objects (in the case of `ModelMultipleChoiceField`) into the
`cleaned_data` dictionary of the form.

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

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

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

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

### `ModelChoiceField`

#### `class ModelChoiceField(**kwargs)`

- デフォルトのウィジェット: [`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select)
- 空の値: `None`
- 正規化後の値: model インスタンスに正規化されます。
- 指定された id がクエリセット内に存在することを検証します。
- エラーメッセージのキー: `required`, `invalid_choice`

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

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

引数が1つ必要です:

#### `queryset`

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

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

#### `empty_label`

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

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

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

`ModelChoiceField` が必須でデフォルトの初期値を持っている場合や、`widget` が [`RadioSelect`](/ja/6.0/ref/forms/widgets/#django.forms.RadioSelect) に設定されており [`blank`](#django.forms.ModelChoiceField.blank) 引数が `False` の場合には、 `empty_label` の値に関係なく空の選択肢は作成されません。

#### `to_field_name`

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

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

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

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

そして、:

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

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

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

#### `blank`

[`RadioSelect`](/ja/6.0/ref/forms/widgets/#django.forms.RadioSelect) ウィジェットを使用する場合、このオプションのブール引数は空の選択肢を作成するかどうかを決定します。デフォルトでは、`blank` は `False` で、空の選択肢は作成されません。

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

#### `iterator`

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

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

```
from django.forms import ModelChoiceField

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

### `ModelMultipleChoiceField`

#### `class ModelMultipleChoiceField(**kwargs)`

- デフォルトのウィジェット: [`SelectMultiple`](/ja/6.0/ref/forms/widgets/#django.forms.SelectMultiple)
- 空の値: 空の `QuerySet` (`self.queryset.none()`)
- 正規化後の値: モデルインスタンスの `QuerySet` になります。
- 与えられた値のリスト内のすべてのIDがクエリセット内に存在することを検証します。
- エラーメッセージのキー: `required`、 `invalid_list`、 `invalid_choice`、 `invalid_pk_value`

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

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

引数が1つ必要です:

#### `queryset`

[`ModelChoiceField.queryset`](#django.forms.ModelChoiceField.queryset) と同じです。

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

#### `to_field_name`

[`ModelChoiceField.to_field_name`](#django.forms.ModelChoiceField.to_field_name) と同じです。

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

#### `iterator`

[`ModelChoiceField.iterator`](#django.forms.ModelChoiceField.iterator) と同じです。

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

デフォルトでは、[`ModelChoiceField`](#django.forms.ModelChoiceField) と [`ModelMultipleChoiceField`](#django.forms.ModelMultipleChoiceField) は、[`ModelChoiceIterator`](#django.forms.ModelChoiceIterator) を使用して、フィールドの `choices` を生成します。

`ModelChoiceIterator` をイテレートすると、1つ目の `value` 要素として [`ModelChoiceIteratorValue`](#django.forms.ModelChoiceIteratorValue) インスタンスを含む2値タプルの選択肢が生成されます。 `ModelChoiceIteratorValue` は、選択値をラップし、カスタムウィジェットの実装で使用できる元のモデルインスタンスへの参照を保持します。たとえば、 `<option>` 要素に [data-\* attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) を追加するのに使用できます。

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

```
from django.db import models

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

    def __str__(self):
        return self.name

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

[`Select`](/ja/6.0/ref/forms/widgets/#django.forms.Select) ウィジェットのサブクラスを使用して、各 `<option>` 要素の HTML 属性 `data-price` として `Topping.price` の値を含めることができます。

```
from django import forms

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

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

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

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

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

#### `ModelChoiceIterator`

#### `class ModelChoiceIterator(field)`

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

引数が1つ必要です:

#### `field`

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

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

#### `__iter__()`

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

#### `ModelChoiceIteratorValue`

#### `class ModelChoiceIteratorValue(value, instance)`

2 つの引数が必要です:

#### `value`

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

#### `instance`

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

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

#### `__str__()`

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

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

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

You can also customize how a field will be accessed by overriding
[`bound_field_class`](#django.forms.Field.bound_field_class) or override
[`Field.get_bound_field()`](#django.forms.Field.get_bound_field) if you need more flexibility when creating
the `BoundField`:

#### `Field.get_bound_field(form, field_name)`

[`Form`](/ja/6.0/ref/forms/api/#django.forms.Form) のインスタンスとフィールド名を引数に取り、対応する [`BoundField`](/ja/6.0/ref/forms/api/#django.forms.BoundField) インスタンスを返します。この返された `BoundField` は、テンプレート内でそのフィールドにアクセスする際に使用されます。

`BoundField` をオーバーライドする例は、 [BoundField のカスタマイズ](/ja/6.0/ref/forms/api/#custom-boundfield) を確認してください。