# Django 5.2.8 ドキュメント

# PostgreSQL 固有のフォームフィールドとウィジェット

これらのフィールドやウィジェットはすべて `django.contrib.postgres.forms` モジュールから利用できます。

## フィールド

### `SimpleArrayField`

class SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None)

  配列にマップされるフィールド。HTMLの `<input>` で表されます。

  base_field

    これは必須の引数です。

    配列のもととなるフォームフィールドを指定します。これは HTML のレンダリングには使われませんが、送信されたデータを処理し、それを検証するために使われます。たとえば:

        >>> from django import forms
        >>> from django.contrib.postgres.forms import SimpleArrayField

        >>> class NumberListForm(forms.Form):
        ...     numbers = SimpleArrayField(forms.IntegerField())
        ...

        >>> form = NumberListForm({"numbers": "1,2,3"})
        >>> form.is_valid()
        True
        >>> form.cleaned_data
        {'numbers': [1, 2, 3]}

        >>> form = NumberListForm({"numbers": "1,2,a"})
        >>> form.is_valid()
        False

  delimiter

    これはオプションの引数で、デフォルトはコンマ `,` です。この値は送信されたデータを分割するために使用されます。多次元データに対して `SimpleArrayField` を連結できます:

        >>> from django import forms
        >>> from django.contrib.postgres.forms import SimpleArrayField

        >>> class GridForm(forms.Form):
        ...     places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter="|")
        ...

        >>> form = GridForm({"places": "1,2|2,1|4,3"})
        >>> form.is_valid()
        True
        >>> form.cleaned_data
        {'places': [[1, 2], [2, 1], [4, 3]]}

    注釈

    フィールドは区切り文字のエスケープをサポートしていないので、区切り文字が元のフィールド内で有効な文字である場合には注意してください。区切り文字は1文字である必要はありません。

  max_length

    これはオプションの引数で、配列が指定された長さを超えていないことを検証します。

  min_length

    これはオプションの引数で、配列が少なくとも指定された長さに達していることを検証します。

  ユーザーフレンドリーなフォーム

  `SimpleArrayField` は、ほとんどの場合、特に使いやすいものではありませんが、クライアントサイドのウィジェットからサーバーに送信するデータをフォーマットする便利な方法です。

### `SplitArrayField`

class SplitArrayField(base_field, size, remove_trailing_nulls=False)

  このフィールドは、ベースとなるフィールドを固定回数複製することで配列を処理します。

  base_field

    これは必須の引数です。繰り返すフォームフィールドを指定します。

  size

    これは、ベースとなるフィールドが使用される固定の回数です。

  remove_trailing_nulls

    デフォルトでは `False` に設定されています。 `False` に設定すると、繰り返されたフィールドのそれぞれの値が保存されます。 `True` に設定すると、末尾の値が空白の場合、その値は結果から取り除かれます。基となるフィールドが `required=True` で、かつ `remove_trailing_nulls` が `True` の場合、末尾にのみ null 値が許され、その値は取り除かれます。

    例:

        SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)

        ["1", "2", "3"]  # -> [1, 2, 3]
        ["1", "2", ""]  # -> ValidationError - third entry required.
        ["1", "", "3"]  # -> ValidationError - second entry required.
        ["", "2", ""]  # -> ValidationError - first and third entries required.

        SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)

        ["1", "2", "3"]  # -> [1, 2, 3]
        ["1", "2", ""]  # -> [1, 2, None]
        ["1", "", "3"]  # -> [1, None, 3]
        ["", "2", ""]  # -> [None, 2, None]

        SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)

        ["1", "2", "3"]  # -> [1, 2, 3]
        ["1", "2", ""]  # -> [1, 2]
        ["1", "", "3"]  # -> ValidationError - second entry required.
        ["", "2", ""]  # -> ValidationError - first entry required.

        SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)

        ["1", "2", "3"]  # -> [1, 2, 3]
        ["1", "2", ""]  # -> [1, 2]
        ["1", "", "3"]  # -> [1, None, 3]
        ["", "2", ""]  # -> [None, 2]

### `HStoreField`

class HStoreField

  `HStoreField` 向けにJSONエンコードされたデータを受け付けるフィールドです。全ての値 (nullを除く) を文字列にキャストします。HTMLの `<textarea>` で表現されます。

  ユーザーフレンドリーなフォーム

  `HStoreField` は、ほとんどの場合、特に使いやすいものではありませんが、クライアントサイドのウィジェットからサーバーに送信するデータをフォーマットする便利な方法です。

  注釈

  与えられたフィールドに対して有効なキーを要求したり、制限したりすることが有用な場合があります。これは `KeysValidator` を使って行うことができます。

### 範囲フィールド

このグループのフィールドは、範囲データを受け取るための同様の機能を共有しています。これらは `MultiValueField` に基づいています。これらのフィールドは、1つの省略された値を境界のない範囲として扱います。また、下限値が上限値より大きくないことを検証します。これらのフィールドは全て `RangeWidget` を使用しています。

#### `IntegerRangeField`

class IntegerRangeField

  `IntegerField` に基づいて、入力を `django.db.backends.postgresql.psycopg_any.NumericRange` に変換します。 `IntegerRangeField` と `BigIntegerRangeField` のデフォルトです。

#### `DecimalRangeField`

class DecimalRangeField

  `DecimalField` に基づいて、その入力を `django.db.backends.postgresql.psycopg_any.NumericRange` に変換します。 `DecimalRangeField` のデフォルトです。

#### `DateTimeRangeField`

class DateTimeRangeField

  `DateTimeField` クラスに基づいて、その入力を `django.db.backends.postgresql.psycopg_any.DateTimeTZRange` に変換します。これは `DateTimeRangeField` のデフォルトです。

#### `DateRangeField`

class DateRangeField

  `DateField` に基づいて、その入力を `django.db.backends.postgresql.psycopg_any.DateRange` に変換します。 これは `DateRangeField` のデフォルトです。

## ウィジェット

### `RangeWidget`

class RangeWidget(base_widget, attrs=None)

  すべての範囲フィールドで使用されるウィジェット。 `MultiWidget` を基にしています。

  `RangeWidget` は1つの必須引数を持ちます:

  base_widget

    `RangeWidget` は、`base_widget` の 2値タプルを構成します。

  decompress(value)

    例えば `DateRangeField` のようなフィールドの "圧縮された" 値を一つ受け取り、下界と上界を表すタプルを返します。