获取帮助

el
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
语言：en

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
文档版本：5.1

部件¶

部件是 Django 对 HTML 输入元素的表示。部件负责渲染 HTML，以及从与部件对应的 GET/POST 字典中提取数据。

内置部件生成的 HTML 使用 HTML5 语法，目标是 <!DOCTYPE html>。例如，它使用布尔属性，例如 checked，而不是 XHTML 样式的 checked='checked'。

提示

部件不应与表单字段混淆。表单字段处理输入验证的逻辑，并直接在模板中使用。部件处理在网页上渲染 HTML 表单输入元素以及提取原始提交的数据。但是，部件确实需要分配到表单字段。

指定部件¶

每当你指定表单上的字段时，Django 将使用适合要显示的数据类型的默认部件。要查找哪个字段使用哪个部件，请参阅有关内置字段类的文档。

但是，如果你想为某个字段使用不同的部件，可以使用字段定义上的widget参数。例如

from django import forms


class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField(widget=forms.Textarea)

这将指定一个表单，其中包含一个使用较大Textarea部件的注释，而不是默认的TextInput部件。

为部件设置参数¶

许多部件具有可选的额外参数；在字段上定义部件时可以设置它们。在以下示例中，为SelectDateWidget设置了years属性

from django import forms

BIRTH_YEAR_CHOICES = ["1980", "1981", "1982"]
FAVORITE_COLORS_CHOICES = {
    "blue": "Blue",
    "green": "Green",
    "black": "Black",
}


class SimpleForm(forms.Form):
    birth_year = forms.DateField(
        widget=forms.SelectDateWidget(years=BIRTH_YEAR_CHOICES)
    )
    favorite_colors = forms.MultipleChoiceField(
        required=False,
        widget=forms.CheckboxSelectMultiple,
        choices=FAVORITE_COLORS_CHOICES,
    )

请参阅内置部件，以获取有关哪些部件可用以及它们接受哪些参数的更多信息。

继承自 `Select` 部件的部件¶

继承自Select部件的部件处理选项。它们向用户提供一个可供选择的选项列表。不同的部件以不同的方式呈现此选项；Select部件本身使用<select> HTML 列表表示，而RadioSelect使用单选按钮。

Select部件默认在ChoiceField字段上使用。部件上显示的选项继承自ChoiceField，并且更改ChoiceField.choices将更新Select.choices。例如

>>> from django import forms
>>> CHOICES = {"1": "First", "2": "Second"}
>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
>>> choice_field.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices = []
>>> choice_field.choices = [("1", "First and only")]
>>> choice_field.widget.choices
[('1', 'First and only')]

但是，提供choices属性的部件可以与不基于选项的字段一起使用，例如CharField，但建议在选项固有于模型而不是仅仅是表示部件时使用基于ChoiceField的字段。

自定义部件实例¶

当 Django 将部件渲染为 HTML 时，它只渲染非常最小的标记 - Django 不会添加类名或任何其他特定于部件的属性。这意味着，例如，所有TextInput部件在你的网页上看起来都一样。

有两种方法可以自定义部件：每个部件实例和每个部件类。

设置部件实例样式¶

如果你想使一个部件实例看起来与另一个不同，你需要在实例化部件对象并将其分配给表单字段时指定其他属性（并且可能向你的 CSS 文件添加一些规则）。

例如，以下表单

from django import forms


class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

此表单将为 name 和 comment 字段包含TextInput部件，以及为 url 字段包含URLInput部件。每个都有默认渲染 - 没有 CSS 类，没有额外属性

>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" required></div>
<div>Url:<input type="url" name="url" required></div>
<div>Comment:<input type="text" name="comment" required></div>

在真实的网页上，你可能想要自定义它。你可能希望为注释使用更大的输入元素，并且你可能希望“name”部件具有某些特殊的 CSS 类。还可以指定“type”属性以使用不同的 HTML5 输入类型。为此，在创建部件时使用Widget.attrs参数

class CommentForm(forms.Form):
    name = forms.CharField(widget=forms.TextInput(attrs={"class": "special"}))
    url = forms.URLField()
    comment = forms.CharField(widget=forms.TextInput(attrs={"size": "40"}))

你也可以在表单定义中修改部件

class CommentForm(forms.Form):
    name = forms.CharField()
    url = forms.URLField()
    comment = forms.CharField()

    name.widget.attrs.update({"class": "special"})
    comment.widget.attrs.update(size="40")

或者，如果字段不是直接在表单上声明的（例如模型表单字段），则可以使用Form.fields属性

class CommentForm(forms.ModelForm):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["name"].widget.attrs.update({"class": "special"})
        self.fields["comment"].widget.attrs.update(size="40")

然后，Django 将在渲染的输出中包含这些额外属性

>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" class="special" required></div>
<div>Url:<input type="url" name="url" required></div>
<div>Comment:<input type="text" name="comment" size="40" required></div>

你还可以使用attrs设置 HTML id。请参阅BoundField.id_for_label以获取示例。

基本部件类¶

基本部件类Widget和MultiWidget是所有内置部件的子类，并且可以作为自定义部件的基础。

`Widget`¶

class Widget(attrs=None)[source]¶

此抽象类无法渲染，但提供了基本属性attrs。你也可以在自定义部件上实现或覆盖render()方法。

attrs¶

一个字典，包含要在渲染的部件上设置的 HTML 属性。

>>> from django import forms
>>> name = forms.TextInput(attrs={"size": 10, "title": "Your name"})
>>> name.render("name", "A name")
'<input title="Your name" type="text" name="name" value="A name" size="10">'

如果你将 True 或 False 的值分配给属性，它将被渲染为 HTML5 布尔属性

>>> name = forms.TextInput(attrs={"required": True})
>>> name.render("name", "A name")
'<input name="name" type="text" value="A name" required>'
>>>
>>> name = forms.TextInput(attrs={"required": False})
>>> name.render("name", "A name")
'<input name="name" type="text" value="A name">'

supports_microseconds¶: 一个属性，默认为 True。如果设置为 False，则 datetime 和 time 值的微秒部分将设置为 0。

format_value(value)[source]¶: 清理并返回一个用于小部件模板的值。 value 不保证是有效的输入，因此子类实现应该进行防御性编程。

get_context(name, value, attrs)[source]¶

返回一个字典，其中包含渲染小部件模板时要使用的值。默认情况下，字典包含一个键 'widget'，它是一个包含以下键的小部件的字典表示形式

'name'：来自 name 参数的字段名称。
'is_hidden'：一个布尔值，指示此小部件是否隐藏。
'required'：一个布尔值，指示此小部件的字段是否必填。
'value'：由 format_value() 返回的值。
'attrs'：要在渲染的小部件上设置的 HTML 属性。 attrs 属性和 attrs 参数的组合。
'template_name'：self.template_name 的值。

Widget 子类可以通过覆盖此方法提供自定义上下文值。

id_for_label(id_)[source]¶

给定字段的 ID，返回此小部件的 HTML ID 属性，供 <label> 使用。如果 ID 不可用，则返回空字符串。

此钩子是必要的，因为某些小部件具有多个 HTML 元素，因此具有多个 ID。在这种情况下，此方法应返回与小部件标签中的第一个 ID 对应的 ID 值。

render(name, value, attrs=None, renderer=None)[source]¶: 使用给定的渲染器将小部件渲染为 HTML。如果 renderer 为 None，则使用 FORM_RENDERER 设置中的渲染器。

value_from_datadict(data, files, name)[source]¶: 给定一个数据字典和此小部件的名称，返回此小部件的值。 files 可能包含来自 request.FILES 的数据。如果未提供值，则返回 None。另请注意，在处理表单数据期间，可能会多次调用 value_from_datadict，因此，如果您对其进行自定义并添加昂贵的处理，则应自己实现一些缓存机制。

value_omitted_from_data(data, files, name)[source]¶

给定 data 和 files 字典以及此小部件的名称，返回此小部件是否有数据或文件。

此方法的结果会影响模型表单中的字段是否回退到其默认值。

特殊情况是 CheckboxInput、CheckboxSelectMultiple 和 SelectMultiple，它们始终返回 False，因为未选中的复选框和未选中的 <select multiple> 不会出现在 HTML 表单提交的数据中，因此无法确定用户是否提交了值。

use_fieldset¶: 一个属性，用于识别在渲染时是否应将小部件与 <legend> 一起分组到 <fieldset> 中。默认为 False，但当小部件包含多个 <input> 标签（例如 CheckboxSelectMultiple、RadioSelect、MultiWidget、SplitDateTimeWidget 和 SelectDateWidget）时为 True。

use_required_attribute(initial)[source]¶

给定表单字段的 initial 值，返回小部件是否可以渲染为 required HTML 属性。表单使用此方法以及 Field.required 和 Form.use_required_attribute 来确定是否为每个字段显示 required 属性。

默认情况下，对于隐藏的小部件返回 False，否则返回 True。特殊情况是 FileInput 和 ClearableFileInput，当 initial 设置时返回 False，以及 CheckboxSelectMultiple，它始终返回 False，因为浏览器验证需要选中所有复选框，而不是至少选中一个。

在与浏览器验证不兼容的自定义小部件中覆盖此方法。例如，一个由隐藏的 textarea 元素支持的 WSYSIWG 文本编辑器小部件可能希望始终返回 False 以避免对隐藏字段进行浏览器验证。

`MultiWidget`¶

class MultiWidget(widgets, attrs=None)[source]¶

一个由多个小部件组成的部件。 MultiWidget 与 MultiValueField 协同工作。

MultiWidget 具有一个必需的参数

widgets¶

包含所需小部件的可迭代对象。例如

>>> from django.forms import MultiWidget, TextInput
>>> widget = MultiWidget(widgets=[TextInput, TextInput])
>>> widget.render("name", ["john", "paul"])
'<input type="text" name="name_0" value="john"><input type="text" name="name_1" value="paul">'

您可以提供一个字典，以便为每个子小部件上的 name 属性指定自定义后缀。在这种情况下，对于每个 (key, widget) 对，键将附加到小部件的 name 以生成属性值。您可以为单个键提供空字符串 ('')，以抑制一个小部件的后缀。例如

>>> widget = MultiWidget(widgets={"": TextInput, "last": TextInput})
>>> widget.render("name", ["john", "paul"])
'<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'

以及一个必需的方法

decompress(value)[source]¶

此方法接收字段的一个“压缩”值，并返回一个“解压缩”值的列表。可以假设输入值有效，但不一定是非空的。

此方法**必须由子类实现**，并且由于该值可能是空的，因此实现必须是防御性的。

“解压缩”背后的原理是，需要将表单字段的组合值“拆分”成每个小部件的值。

例如，SplitDateTimeWidget 如何将 datetime 值转换为包含日期和时间拆分为两个单独值的列表

from django.forms import MultiWidget


class SplitDateTimeWidget(MultiWidget):
    # ...

    def decompress(self, value):
        if value:
            return [value.date(), value.time()]
        return [None, None]

提示

请注意，MultiValueField 具有一个互补方法 compress()，其职责相反——将所有成员字段的已清理值组合成一个。

它提供了一些自定义上下文

get_context(name, value, attrs)[source]¶

除了 Widget.get_context() 中描述的 'widget' 键之外，MultiWidget 还添加了一个 widget['subwidgets'] 键。

这些可以在小部件模板中循环遍历

{% for subwidget in widget.subwidgets %}
    {% include subwidget.template_name with widget=subwidget %}
{% endfor %}

这是一个示例小部件，它继承自 MultiWidget 以使用不同的选择框显示日期的日、月和年。此小部件旨在与 DateField 而不是 MultiValueField 一起使用，因此我们实现了 value_from_datadict()

from datetime import date
from django import forms


class DateSelectorWidget(forms.MultiWidget):
    def __init__(self, attrs=None):
        days = {day: day for day in range(1, 32)}
        months = {month: month for month in range(1, 13)}
        years = {year: year for year in [2018, 2019, 2020]}
        widgets = [
            forms.Select(attrs=attrs, choices=days),
            forms.Select(attrs=attrs, choices=months),
            forms.Select(attrs=attrs, choices=years),
        ]
        super().__init__(widgets, attrs)

    def decompress(self, value):
        if isinstance(value, date):
            return [value.day, value.month, value.year]
        elif isinstance(value, str):
            year, month, day = value.split("-")
            return [day, month, year]
        return [None, None, None]

    def value_from_datadict(self, data, files, name):
        day, month, year = super().value_from_datadict(data, files, name)
        # DateField expects a single string that it can parse into a date.
        return "{}-{}-{}".format(year, month, day)

构造函数在列表中创建了几个 Select 小部件。super() 方法使用此列表来设置小部件。

必需的方法 decompress() 将 datetime.date 值分解为对应于每个小部件的日、月和年值。如果选择了无效日期，例如不存在的 2 月 30 日，则 DateField 会将此方法传递一个字符串，因此需要进行解析。最后的 return 处理 value 为 None 的情况，这意味着我们没有子小部件的任何默认值。

value_from_datadict() 的默认实现返回一个与每个 Widget 对应的值的列表。当将 MultiWidget 与 MultiValueField 一起使用时，这是合适的。但是，由于我们希望将此小部件与 DateField 一起使用，后者接受单个值，因此我们覆盖了此方法。此处的实现将子小部件中的数据组合成 DateField 期望的格式的字符串。

内置小部件¶

Django 提供了所有基本 HTML 小部件的表示形式，以及 django.forms.widgets 模块中一些常用的分组小部件，包括文本输入、各种复选框和选择器、上传文件以及处理多值输入。

处理文本输入的小部件¶

这些小部件使用 HTML 元素 input 和 textarea。

`TextInput`¶

class TextInput[source]¶

input_type: 'text'
template_name: 'django/forms/widgets/text.html'
呈现为：<input type="text" ...>

`NumberInput`¶

class NumberInput[source]¶

input_type: 'number'
template_name: 'django/forms/widgets/number.html'
呈现为：<input type="number" ...>

请注意，并非所有浏览器都支持在 number 输入类型中输入本地化数字。Django 本身避免将它们用于其 localize 属性设置为 True 的字段。

`EmailInput`¶

class EmailInput[source]¶

input_type: 'email'
template_name: 'django/forms/widgets/email.html'
呈现为：<input type="email" ...>

`URLInput`¶

class URLInput[source]¶

input_type: 'url'
template_name: 'django/forms/widgets/url.html'
呈现为：<input type="url" ...>

`PasswordInput`¶

class PasswordInput[source]¶

input_type: 'password'
template_name: 'django/forms/widgets/password.html'
渲染为: <input type="password" ...>

接受一个可选参数

render_value¶: 确定在表单验证错误后重新显示时，小部件是否会有填充的值（默认为 False）。

`HiddenInput`¶

class HiddenInput[source]¶

input_type: 'hidden'
template_name: 'django/forms/widgets/hidden.html'
渲染为: <input type="hidden" ...>

请注意，还有一个 MultipleHiddenInput 小部件，它封装了一组隐藏的输入元素。

`DateInput`¶

class DateInput[source]¶

input_type: 'text'
template_name: 'django/forms/widgets/date.html'
呈现为：<input type="text" ...>

接受与 TextInput 相同的参数，以及一个额外的可选参数

format¶: 此字段初始值将以其显示的格式。

如果未提供 format 参数，则默认格式为在 DATE_INPUT_FORMATS 中找到的第一个格式，并遵循格式本地化。此小部件不支持 %U、%W 和 %j 格式。

`DateTimeInput`¶

class DateTimeInput[source]¶

input_type: 'text'
template_name: 'django/forms/widgets/datetime.html'
呈现为：<input type="text" ...>

接受与 TextInput 相同的参数，以及一个额外的可选参数

format¶: 此字段初始值将以其显示的格式。

如果未提供 format 参数，则默认格式为在 DATETIME_INPUT_FORMATS 中找到的第一个格式，并遵循格式本地化。此小部件不支持 %U、%W 和 %j 格式。

默认情况下，时间值的微秒部分始终设置为 0。如果需要微秒，请使用具有 supports_microseconds 属性设置为 True 的子类。

`TimeInput`¶

class TimeInput[source]¶

input_type: 'text'
template_name: 'django/forms/widgets/time.html'
呈现为：<input type="text" ...>

接受与 TextInput 相同的参数，以及一个额外的可选参数

format¶: 此字段初始值将以其显示的格式。

如果未提供 format 参数，则默认格式为在 TIME_INPUT_FORMATS 中找到的第一个格式，并遵循格式本地化。

有关微秒的处理，请参阅 DateTimeInput。

`Textarea`¶

class Textarea[source]¶

template_name: 'django/forms/widgets/textarea.html'
渲染为: <textarea>...</textarea>

选择器和小部件¶

这些小部件使用 HTML 元素 <select>、<input type="checkbox"> 和 <input type="radio">。

渲染多个选项的小部件具有一个 option_template_name 属性，该属性指定用于渲染每个选项的模板。例如，对于 Select 小部件，select_option.html 渲染 <select> 的 <option>。

`CheckboxInput`¶

class CheckboxInput[source]¶

input_type: 'checkbox'
template_name: 'django/forms/widgets/checkbox.html'
渲染为: <input type="checkbox" ...>

接受一个可选参数

check_test¶: 一个可调用对象，它接收 CheckboxInput 的值并返回 True，如果该值的复选框应被选中。

`Select`¶

class Select[source]¶

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'
渲染为: <select><option ...>...</select>

choices¶: 当表单字段没有 choices 属性时，此属性是可选的。如果有，当在 Field 上更新属性时，它将覆盖此处设置的任何内容。

`NullBooleanSelect`¶

class NullBooleanSelect[source]¶

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'

具有“未知”、“是”和“否”选项的选择小部件

`SelectMultiple`¶

class SelectMultiple[source]¶

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'

类似于 Select，但允许多选：<select multiple>...</select>

`RadioSelect`¶

class RadioSelect[source]¶

template_name: 'django/forms/widgets/radio.html'
option_template_name: 'django/forms/widgets/radio_option.html'

类似于 Select，但渲染为包含在 <div> 标签中的单选按钮列表。

<div>
  <div><input type="radio" name="..."></div>
  ...
</div>

为了更细粒度地控制生成的标记，您可以在模板中循环遍历单选按钮。假设一个表单 myform，其中包含一个字段 beatles，该字段使用 RadioSelect 作为其小部件。

<fieldset>
    <legend>{{ myform.beatles.label }}</legend>
    {% for radio in myform.beatles %}
    <div class="myradio">
        {{ radio }}
    </div>
    {% endfor %}
</fieldset>

这将生成以下 HTML 代码。

<fieldset>
    <legend>Radio buttons</legend>
    <div class="myradio">
        <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
    </div>
    <div class="myradio">
        <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
    </div>
    <div class="myradio">
        <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
    </div>
    <div class="myradio">
        <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
    </div>
</fieldset>

其中包括 <label> 标签。为了获得更细粒度的控制，您可以使用每个单选按钮的 tag、choice_label 和 id_for_label 属性。例如，此模板…

<fieldset>
    <legend>{{ myform.beatles.label }}</legend>
    {% for radio in myform.beatles %}
    <label for="{{ radio.id_for_label }}">
        {{ radio.choice_label }}
        <span class="radio">{{ radio.tag }}</span>
    </label>
    {% endfor %}
</fieldset>

…将产生以下 HTML 代码。

<fieldset>
    <legend>Radio buttons</legend>
    <label for="id_beatles_0">
        John
        <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
    </label>
    <label for="id_beatles_1">
        Paul
        <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
    </label>
    <label for="id_beatles_2">
        George
        <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
    </label>
    <label for="id_beatles_3">
        Ringo
        <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
    </label>
</fieldset>

如果您决定不循环遍历单选按钮 - 例如，如果您的模板包含 {{ myform.beatles }} - 它们将输出在具有 <div> 标签的 <div> 中，如上所示。

外部 <div> 容器接收小部件的 id 属性（如果已定义），否则接收 BoundField.auto_id。

在循环遍历单选按钮时，label 和 input 标签分别包含 for 和 id 属性。每个单选按钮都有一个 id_for_label 属性来输出元素的 ID。

`CheckboxSelectMultiple`¶

class CheckboxSelectMultiple[source]¶

template_name: 'django/forms/widgets/checkbox_select.html'
option_template_name: 'django/forms/widgets/checkbox_option.html'

类似于 SelectMultiple，但渲染为复选框列表。

<div>
  <div><input type="checkbox" name="..." ></div>
  ...
</div>

外部 <div> 容器接收小部件的 id 属性（如果已定义），否则接收 BoundField.auto_id。

像 RadioSelect 一样，您可以循环遍历小部件选择的各个复选框。与 RadioSelect 不同，如果字段是必需的，复选框将不包含 required HTML 属性，因为浏览器验证将要求选中所有复选框而不是至少选中一个。

在循环遍历复选框时，label 和 input 标签分别包含 for 和 id 属性。每个复选框都有一个 id_for_label 属性来输出元素的 ID。

文件上传小部件¶

`FileInput`¶

class FileInput[source]¶

template_name: 'django/forms/widgets/file.html'
渲染为：<input type="file" ...>

`ClearableFileInput`¶

class ClearableFileInput[source]¶

template_name: 'django/forms/widgets/clearable_file_input.html'
渲染为：<input type="file" ...>，如果字段不是必需的并且具有初始数据，则包含一个额外的复选框输入以清除字段的值。

复合小部件¶

`MultipleHiddenInput`¶

class MultipleHiddenInput[source]¶

template_name: 'django/forms/widgets/multiple_hidden.html'
渲染为：多个 <input type="hidden" ...> 标签。

一个处理具有值列表的字段的多个隐藏小部件的小部件。

`SplitDateTimeWidget`¶

class SplitDateTimeWidget[source]¶

template_name: 'django/forms/widgets/splitdatetime.html'

围绕两个小部件的包装器（使用 MultiWidget）：DateInput 用于日期，TimeInput 用于时间。必须与 SplitDateTimeField 而不是 DateTimeField 一起使用。

SplitDateTimeWidget 有几个可选参数。

date_format¶: 类似于 DateInput.format。

time_format¶: 类似于 TimeInput.format。

date_attrs¶

time_attrs¶: 类似于 Widget.attrs。一个包含要设置在渲染的 DateInput 和 TimeInput 小部件上的 HTML 属性的字典。如果未设置这些属性，则使用 Widget.attrs。

`SplitHiddenDateTimeWidget`¶

class SplitHiddenDateTimeWidget[source]¶

template_name: 'django/forms/widgets/splithiddendatetime.html'

类似于 SplitDateTimeWidget，但对日期和时间都使用 HiddenInput。

`SelectDateWidget`¶

class SelectDateWidget[source]¶

template_name: 'django/forms/widgets/select_date.html'

围绕三个 Select 小部件的包装器：每个用于月份、日期和年份。

接受几个可选参数。

years¶: 一个可选的列表/元组，用于“年份”选择框中的年份。默认情况下，该列表包含当前年份和接下来的 9 年。

months¶

一个可选的字典，用于“月份”选择框中的月份。

字典的键对应于月份编号（从 1 开始），值是显示的月份。

MONTHS = {
_("jan"),
_("feb"),
_("mar"),
_("apr"),
_("may"),
_("jun"),
_("jul"),
_("aug"),
_("sep"),
_("oct"),
_("nov"),
_("dec"),
}

empty_label¶

如果 DateField 不是必需的，SelectDateWidget 将在列表顶部有一个空选项（默认情况下为 ---）。您可以使用 empty_label 属性更改此标签的文本。empty_label 可以是 string、list 或 tuple。当使用字符串时，所有选择框都将具有一个带有此标签的空选项。如果 empty_label 是一个包含 3 个字符串元素的 list 或 tuple，则选择框将具有自己的自定义标签。标签应按此顺序排列 ('year_label', 'month_label', 'day_label')。

# A custom empty label with string
field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))

# A custom empty label with tuple
field1 = forms.DateField(
    widget=SelectDateWidget(
        empty_label=("Choose Year", "Choose Month", "Choose Day"),
    ),
)

表单渲染 API

表单和字段验证

返回顶部

文档

部件¶

指定部件¶

为部件设置参数¶

继承自 Select 部件的部件¶

自定义部件实例¶

设置部件实例样式¶

设置部件类样式¶

基本部件类¶

Widget¶

MultiWidget¶

内置小部件¶

处理文本输入的小部件¶

TextInput¶

NumberInput¶

EmailInput¶

URLInput¶

PasswordInput¶

HiddenInput¶

DateInput¶

DateTimeInput¶

TimeInput¶

Textarea¶

选择器和小部件¶

CheckboxInput¶

Select¶

NullBooleanSelect¶

SelectMultiple¶

RadioSelect¶

CheckboxSelectMultiple¶

文件上传小部件¶

FileInput¶

ClearableFileInput¶

复合小部件¶

MultipleHiddenInput¶

SplitDateTimeWidget¶

SplitHiddenDateTimeWidget¶

SelectDateWidget¶

其他信息

支持 Django！

内容

浏览

您当前位置

获取帮助

下载

继承自 `Select` 部件的部件¶

`Widget`¶

`MultiWidget`¶

`TextInput`¶

`NumberInput`¶

`EmailInput`¶

`URLInput`¶

`PasswordInput`¶

`HiddenInput`¶

`DateInput`¶

`DateTimeInput`¶

`TimeInput`¶

`Textarea`¶

`CheckboxInput`¶

`Select`¶

`NullBooleanSelect`¶

`SelectMultiple`¶

`RadioSelect`¶

`CheckboxSelectMultiple`¶

`FileInput`¶

`ClearableFileInput`¶

`MultipleHiddenInput`¶

`SplitDateTimeWidget`¶

`SplitHiddenDateTimeWidget`¶

`SelectDateWidget`¶