PostgreSQL 特有表单字段和部件

所有这些字段和部件都可以从 django.contrib.postgres.forms 模块中获得。

字段

SimpleArrayField

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

一个映射到数组的字段。它由一个 HTML <input> 表示。

  • base_field

    这是一个必要的参数。

    It specifies the underlying form field for the array. This is not used to render any HTML, but it is used to process the submitted data and validate it. For example:

    1. >>> from django import forms
    2. >>> from django.contrib.postgres.forms import SimpleArrayField
    4. >>> class NumberListForm(forms.Form):
    5. ...     numbers = SimpleArrayField(forms.IntegerField())
    6. ...
    8. >>> form = NumberListForm({"numbers": "1,2,3"})
    9. >>> form.is_valid()
    10. True
    11. >>> form.cleaned_data
    12. {'numbers': [1, 2, 3]}
    14. >>> form = NumberListForm({"numbers": "1,2,a"})
    15. >>> form.is_valid()
    16. False

  • delimiter

    This is an optional argument which defaults to a comma: ,. This value is used to split the submitted data. It allows you to chain SimpleArrayField for multidimensional data:

    1. >>> from django import forms
    2. >>> from django.contrib.postgres.forms import SimpleArrayField
    4. >>> class GridForm(forms.Form):
    5. ...     places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter="|")
    6. ...
    8. >>> form = GridForm({"places": "1,2|2,1|4,3"})
    9. >>> form.is_valid()
    10. True
    11. >>> form.cleaned_data
    12. {'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，那么只有在最后才允许有空值，并且空值会被消除。

    一些例子：

    1. SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)
    3. ["1", "2", "3"]  # -> [1, 2, 3]
    4. ["1", "2", ""]  # -> ValidationError - third entry required.
    5. ["1", "", "3"]  # -> ValidationError - second entry required.
    6. ["", "2", ""]  # -> ValidationError - first and third entries required.
    8. SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)
    10. ["1", "2", "3"]  # -> [1, 2, 3]
    11. ["1", "2", ""]  # -> [1, 2, None]
    12. ["1", "", "3"]  # -> [1, None, 3]
    13. ["", "2", ""]  # -> [None, 2, None]
    15. SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)
    17. ["1", "2", "3"]  # -> [1, 2, 3]
    18. ["1", "2", ""]  # -> [1, 2]
    19. ["1", "", "3"]  # -> ValidationError - second entry required.
    20. ["", "2", ""]  # -> ValidationError - first entry required.
    22. SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)
    24. ["1", "2", "3"]  # -> [1, 2, 3]
    25. ["1", "2", ""]  # -> [1, 2]
    26. ["1", "", "3"]  # -> [1, None, 3]
    27. ["", "2", ""]  # -> [None, 2]

HStoreField

class HStoreField

一个为 HStoreField 接受 JSON 编码数据的字段。它将所有的值（除了空值）转换为字符串。它由一个 HTML <textarea> 表示。

用户友好的表单

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

备注

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

范围字段

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

IntegerRangeField

class IntegerRangeField

Based on IntegerField and translates its input into django.db.backends.postgresql.psycopg_any.NumericRange. Default for IntegerRangeField and BigIntegerRangeField.

DecimalRangeField

class DecimalRangeField

Based on DecimalField and translates its input into django.db.backends.postgresql.psycopg_any.NumericRange. Default for DecimalRangeField.

DateTimeRangeField

class DateTimeRangeField

Based on DateTimeField and translates its input into django.db.backends.postgresql.psycopg_any.DateTimeTZRange. Default for DateTimeRangeField.

DateRangeField

class DateRangeField

Based on DateField and translates its input into django.db.backends.postgresql.psycopg_any.DateRange. Default for DateRangeField.

部件

RangeWidget

class RangeWidget(base_widget, attrs=None)

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

RangeWidget 有一个必要的参数：

  • base_widget

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

  • decompress(value)

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