# Django 3.2.11.dev 文档

# 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]]}

    注解

    该字段不支持定界符的转义，所以当定界符是底层字段中的有效字符时，要小心。定界符不需要只用一个字符。

  `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`，那么只有在最后才允许有空值，并且空值会被消除。

    一些例子：

        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 编码数据的字段。它将所有的值（除了空值）转换为字符串。它由一个 HTML `<textarea>` 表示。

  用户友好的表单

  `HStoreField` 在大多数情况下对用户不是特别友好，但是它是一种有用的方式来格式化来自客户端部件的数据以提交给服务器。

  注解

  在某些情况下，可能需要要求或限制对某个字段有效的键。这可以使用 `KeysValidator` 来完成。

### `JSONField`

class `JSONField`

  一个接受 JSON 编码数据的字段 `JSONField`。它由一个 HTML `<textarea>` 表示。

  用户友好的表单

  `JSONField` 在大多数情况下并不是特别的用户友好，但是它是一种有用的方式来格式化来自客户端部件的数据以提交给服务器。

  3.1 版后已移除: 使用 `django.forms.JSONField` 代替。

### 范围字段

这组字段在接受范围数据方面都有类似的功能。它们基于 `MultiValueField`。它们将一个省略的值视为一个无边界的范围。它们还验证了下限不大于上限。所有这些字段都使用 `RangeWidget`。

#### `IntegerRangeField`

class `IntegerRangeField`

  基于 `IntegerField` 并将其输入转化为 `NumericRange`。默认为 `IntegerRangeField` 和 `BigIntegerRangeField`。

#### `DecimalRangeField`

class `DecimalRangeField`

  基于 `DecimalField`，并将其输入转化为 `NumericRange`。默认为 `DecimalRangeField`。

#### `DateTimeRangeField`

class `DateTimeRangeField`

  基于 `DateTimeField`，并将其输入转化为 `DateTimeTZRange`。默认为 `DateTimeRangeField`。

#### `DateRangeField`

class `DateRangeField`

  基于 `DateField`，并将其输入转化为 `DateRange`。默认为 `DateRangeField`。

## 部件

### `RangeWidget`

class `RangeWidget`(base_widget, attrs=None)

  所有范围字段都使用的部件。基于 `MultiWidget`。

  `RangeWidget` 有一个必要的参数：

  `base_widget`

    一个 `RangeWidget` 由 `base_widget` 的二元元组组成。

  `decompress`(value)

    取一个字段的单个“压缩”值，例如一个 `DateRangeField`，并返回一个元组，代表一个下界和上界。