查看“Django/docs/3.0.x/ref/contrib/postgres/forms”的源代码

<div id="postgresql-specific-form-fields-and-widgets" class="section">

= PostgreSQL specific form fields and widgets =

All of these fields and widgets are available from the
<code>django.contrib.postgres.forms</code> module.

<div id="fields" class="section">

== 字段 ==

<div id="simplearrayfield" class="section">

=== <code>SimpleArrayField</code> ===

<dl>
<dt>''class'' <code>SimpleArrayField</code><span class="sig-paren">(</span>''<span class="n">base_field</span>'', ''<span class="n">delimiter</span><span class="o">=</span><span class="default_value">','</span>'', ''<span class="n">max_length</span><span class="o">=</span><span class="default_value">None</span>'', ''<span class="n">min_length</span><span class="o">=</span><span class="default_value">None</span>''<span class="sig-paren">)</span></dt>
<dd><p>A field which maps to an array. It is represented by an HTML <code>&lt;input&gt;</code>.</p>
<dl>
<dt><code>base_field</code></dt>
<dd><p>This is a required argument.</p>
<p>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:</p>
<div class="highlight-default notranslate">

<div class="highlight">

<pre>&gt;&gt;&gt; from django import forms
&gt;&gt;&gt; from django.contrib.postgres.forms import SimpleArrayField

&gt;&gt;&gt; class NumberListForm(forms.Form):
...     numbers = SimpleArrayField(forms.IntegerField())

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

&gt;&gt;&gt; form = NumberListForm({'numbers': '1,2,a'})
&gt;&gt;&gt; form.is_valid()
False</pre>

</div>

</div></dd></dl>

<dl>
<dt><code>delimiter</code></dt>
<dd><p>This is an optional argument which defaults to a comma: <code>,</code>. This
value is used to split the submitted data. It allows you to chain
<code>SimpleArrayField</code> for multidimensional data:</p>
<div class="highlight-default notranslate">

<div class="highlight">

<pre>&gt;&gt;&gt; from django import forms
&gt;&gt;&gt; from django.contrib.postgres.forms import SimpleArrayField

&gt;&gt;&gt; class GridForm(forms.Form):
...     places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter='|')

&gt;&gt;&gt; form = GridForm({'places': '1,2|2,1|4,3'})
&gt;&gt;&gt; form.is_valid()
True
&gt;&gt;&gt; form.cleaned_data
{'places': [[1, 2], [2, 1], [4, 3]]}</pre>

</div>

</div>
<div class="admonition note">

<p>注解</p>
<p>The field does not support escaping of the delimiter, so be careful
in cases where the delimiter is a valid character in the underlying
field. The delimiter does not need to be only one character.</p>

</div></dd></dl>

<dl>
<dt><code>max_length</code></dt>
<dd><p>This is an optional argument which validates that the array does not
exceed the stated length.</p></dd></dl>

<dl>
<dt><code>min_length</code></dt>
<dd><p>This is an optional argument which validates that the array reaches at
least the stated length.</p></dd></dl>

<div class="admonition-user-friendly-forms admonition">

<p>User friendly forms</p>
<p><code>SimpleArrayField</code> is not particularly user friendly in most cases,
however it is a useful way to format data from a client-side widget for
submission to the server.</p>

</div></dd></dl>


</div>
<div id="splitarrayfield" class="section">

=== <code>SplitArrayField</code> ===

<dl>
<dt>''class'' <code>SplitArrayField</code><span class="sig-paren">(</span>''<span class="n">base_field</span>'', ''<span class="n">size</span>'', ''<span class="n">remove_trailing_nulls</span><span class="o">=</span><span class="default_value">False</span>''<span class="sig-paren">)</span></dt>
<dd><p>This field handles arrays by reproducing the underlying field a fixed
number of times.</p>
<dl>
<dt><code>base_field</code></dt>
<dd><p>This is a required argument. It specifies the form field to be
repeated.</p></dd></dl>

<dl>
<dt><code>size</code></dt>
<dd><p>This is the fixed number of times the underlying field will be used.</p></dd></dl>

<dl>
<dt><code>remove_trailing_nulls</code></dt>
<dd><p>By default, this is set to <code>False</code>. When <code>False</code>, each value from
the repeated fields is stored. When set to <code>True</code>, any trailing
values which are blank will be stripped from the result. If the
underlying field has <code>required=True</code>, but <code>remove_trailing_nulls</code>
is <code>True</code>, then null values are only allowed at the end, and will be
stripped.</p>
<p>Some examples:</p>
<div class="highlight-default notranslate">

<div class="highlight">

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

['1', '2', '3']  # -&gt; [1, 2, 3]
['1', '2', '']  # -&gt; ValidationError - third entry required.
['1', '', '3']  # -&gt; ValidationError - second entry required.
['', '2', '']  # -&gt; ValidationError - first and third entries required.

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

['1', '2', '3']  # -&gt; [1, 2, 3]
['1', '2', '']  # -&gt; [1, 2, None]
['1', '', '3']  # -&gt; [1, None, 3]
['', '2', '']  # -&gt; [None, 2, None]

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

['1', '2', '3']  # -&gt; [1, 2, 3]
['1', '2', '']  # -&gt; [1, 2]
['1', '', '3']  # -&gt; ValidationError - second entry required.
['', '2', '']  # -&gt; ValidationError - first entry required.

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

['1', '2', '3']  # -&gt; [1, 2, 3]
['1', '2', '']  # -&gt; [1, 2]
['1', '', '3']  # -&gt; [1, None, 3]
['', '2', '']  # -&gt; [None, 2]</pre>

</div>

</div></dd></dl>
</dd></dl>


</div>
<div id="hstorefield" class="section">

=== <code>HStoreField</code> ===

<dl>
<dt>''class'' <code>HStoreField</code></dt>
<dd><p>A field which accepts JSON encoded data for an
[[../fields#django.contrib.postgres.fields|<code>HStoreField</code>]]. It casts all values
(except nulls) to strings. It is represented by an HTML <code>&lt;textarea&gt;</code>.</p>
<div class="admonition-user-friendly-forms admonition">

<p>User friendly forms</p>
<p><code>HStoreField</code> is not particularly user friendly in most cases,
however it is a useful way to format data from a client-side widget for
submission to the server.</p>

</div>
<div class="admonition note">

<p>注解</p>
<p>On occasions it may be useful to require or restrict the keys which are
valid for a given field. This can be done using the
[[../validators#django.contrib.postgres.validators|<code>KeysValidator</code>]].</p>

</div></dd></dl>


</div>
<div id="jsonfield" class="section">

=== <code>JSONField</code> ===

<dl>
<dt>''class'' <code>JSONField</code></dt>
<dd><p>A field which accepts JSON encoded data for a
[[../fields#django.contrib.postgres.fields|<code>JSONField</code>]]. It is represented by an
HTML <code>&lt;textarea&gt;</code>.</p>
<div class="admonition-user-friendly-forms admonition">

<p>User friendly forms</p>
<p><code>JSONField</code> is not particularly user friendly in most cases, however
it is a useful way to format data from a client-side widget for
submission to the server.</p>

</div></dd></dl>


</div>
<div id="range-fields" class="section">

=== Range Fields ===

This group of fields all share similar functionality for accepting range data.
They are based on [[../../../forms/fields#django.forms|<code>MultiValueField</code>]]. They treat one
omitted value as an unbounded range. They also validate that the lower bound is
not greater than the upper bound. All of these fields use
[[#django.contrib.postgres.forms.RangeWidget|<code>RangeWidget</code>]].

<div id="integerrangefield" class="section">

==== <code>IntegerRangeField</code> ====

; ''class'' <code>IntegerRangeField</code>
: Based on [[../../../forms/fields#django.forms|<code>IntegerField</code>]] and translates its input into <code>NumericRange</code>. Default for [[../fields#django.contrib.postgres.fields|<code>IntegerRangeField</code>]] and [[../fields#django.contrib.postgres.fields|<code>BigIntegerRangeField</code>]].


</div>
<div id="decimalrangefield" class="section">

==== <code>DecimalRangeField</code> ====

<dl>
<dt>''class'' <code>DecimalRangeField</code></dt>
<dd><div class="versionadded">



</div>
<p>Based on [[../../../forms/fields#django.forms|<code>DecimalField</code>]] and translates its input into
<code>NumericRange</code>. Default for
[[../fields#django.contrib.postgres.fields|<code>DecimalRangeField</code>]].</p></dd></dl>


</div>
<div id="floatrangefield" class="section">

==== <code>FloatRangeField</code> ====

<dl>
<dt>''class'' <code>FloatRangeField</code></dt>
<dd><p>Based on [[../../../forms/fields#django.forms|<code>FloatField</code>]] and translates its input into
<code>NumericRange</code>. Default for
[[../fields#django.contrib.postgres.fields|<code>FloatRangeField</code>]].</p>
<div class="deprecated">

<p><span class="versionmodified deprecated">2.2 版后已移除: </span>Use [[#django.contrib.postgres.forms.DecimalRangeField|<code>DecimalRangeField</code>]] instead.</p>

</div></dd></dl>


</div>
<div id="datetimerangefield" class="section">

==== <code>DateTimeRangeField</code> ====

; ''class'' <code>DateTimeRangeField</code>
: Based on [[../../../forms/fields#django.forms|<code>DateTimeField</code>]] and translates its input into <code>DateTimeTZRange</code>. Default for [[../fields#django.contrib.postgres.fields|<code>DateTimeRangeField</code>]].


</div>
<div id="daterangefield" class="section">

==== <code>DateRangeField</code> ====

; ''class'' <code>DateRangeField</code>
: Based on [[../../../forms/fields#django.forms|<code>DateField</code>]] and translates its input into <code>DateRange</code>. Default for [[../fields#django.contrib.postgres.fields|<code>DateRangeField</code>]].


</div>

</div>

</div>
<div id="widgets" class="section">

== 小部件 ==

<div id="rangewidget" class="section">

=== <code>RangeWidget</code> ===

<dl>
<dt>''class'' <code>RangeWidget</code><span class="sig-paren">(</span>''<span class="n">base_widget</span>'', ''<span class="n">attrs</span><span class="o">=</span><span class="default_value">None</span>''<span class="sig-paren">)</span></dt>
<dd><p>Widget used by all of the range fields.
Based on [[../../../forms/widgets#django.forms|<code>MultiWidget</code>]].</p>
<p>[[#django.contrib.postgres.forms.RangeWidget|<code>RangeWidget</code>]] has one required argument:</p>
<dl>
<dt><code>base_widget</code></dt>
<dd><p>A [[#django.contrib.postgres.forms.RangeWidget|<code>RangeWidget</code>]] comprises a 2-tuple of <code>base_widget</code>.</p></dd></dl>

<dl>
<dt><code>decompress</code><span class="sig-paren">(</span>''<span class="n">value</span>''<span class="sig-paren">)</span></dt>
<dd><p>Takes a single &quot;compressed&quot; value of a field, for example a
[[../fields#django.contrib.postgres.fields|<code>DateRangeField</code>]],
and returns a tuple representing a lower and upper bound.</p></dd></dl>
</dd></dl>


</div>

</div>

</div>

[[Category:Django 3.0.x 中文文档]]