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

一些例子:

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。默认为 IntegerRangeFieldBigIntegerRangeField

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

一个 RangeWidgetbase_widget 的二元元组组成。

decompress(value)

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