2021年10月31日 (日) 04:14的最新版本

小工具

小部件是 Django 对 HTML 输入元素的表示。小部件处理 HTML 的呈现，以及从对应于小部件的 GET/POST 字典中提取数据。

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

提示

小部件不应与表单字段混淆。表单字段处理输入验证的逻辑并直接在模板中使用。小部件处理网页上 HTML 表单输入元素的呈现和原始提交数据的提取。但是，小部件确实需要 assigned 来形成字段。

指定小部件

每当您在表单上指定字段时，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 -based field when the choices are inherent to the model and not just the representational widget.

自定义小部件实例

当 Django 将小部件呈现为 HTML 时，它只会呈现非常少的标记——Django 不会添加类名或任何其他特定于小部件的属性。这意味着，例如，所有 TextInput 小部件在您的网页上将显示相同。

自定义小部件有两种方式：每个小部件实例和每个小部件类。

样式小部件实例

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

例如，采用以下形式：

from django import forms

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

此表单将包含三个默认的 TextInput 小部件，具有默认呈现 - 没有 CSS 类，没有额外的属性。这意味着为每个小部件提供的输入框将呈现完全相同：

>>> f = CommentForm(auto_id=False)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

在真实的 Web 页面上，您可能不希望每个小部件看起来都一样。您可能需要更大的评论输入元素，并且您可能希望“名称”小部件具有一些特殊的 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)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required></td></tr>

您还可以使用 attrs 设置 HTML id。有关示例，请参阅 BoundField.id_for_label。

基本小部件类

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

Widget

class Widget(attrs=None)

这个抽象类不能被渲染，但提供了基本属性 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): 清理并返回一个值以在小部件模板中使用。 value 不能保证是有效的输入，因此子类实现应该防御性地编程。

get_context(name, value, attrs)

返回呈现小部件模板时要使用的值字典。默认情况下，字典包含一个键，'widget'，它是包含以下键的小部件的字典表示：

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

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

id_for_label(id_)

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

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

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

value_from_datadict(data, files, name): 给定一个数据字典和这个小部件的名称，返回这个小部件的值。 files 可能包含来自 request.FILES 的数据。如果未提供值，则返回 None。还要注意 value_from_datadict 在处理表单数据的过程中可能会被多次调用，所以如果你自定义它并添加昂贵的处理，你应该自己实现一些缓存机制。

value_omitted_from_data(data, files, name)

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

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

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

use_required_attribute(initial)

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

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

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

3.1 版更改：在旧版本中，设置 initial 时为 FileInput 返回 True。

MultiWidget

class MultiWidget(widgets, attrs=None)

由多个小部件组成的小部件。 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)

此方法从字段中获取单个“压缩”值并返回“解压缩”值列表。可以假定输入值有效，但不一定非空。

这个方法必须由子类实现，并且由于值可能为空，所以实现必须是防御性的。

“解压”背后的基本原理是必须将表单字段的组合值“拆分”为每个小部件的值。

这方面的一个例子是 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)

除了 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 会向该方法传递一个字符串，因此需要解析。当 value 为 None 时，最终的 return 处理，这意味着我们的子部件没有任何默认值。

value_from_datadict() 的默认实现返回与每个 Widget 对应的值列表。这适用于使用 MultiWidget 和 MultiValueField。但是由于我们想要使用带有一个 DateField 的小部件，它接受一个值，我们已经覆盖了这个方法。这里的实现将来自 subwidget 的数据以 DateField 期望的格式组合成一个字符串。

内置小部件

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

处理文本输入的小部件

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

TextInput

class TextInput: ;* input_type：'text'

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

NumberInput

class NumberInput

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

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

EmailInput

class EmailInput: ;* input_type：'email'

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

URLInput

class URLInput: ;* input_type：'url'

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

PasswordInput

class PasswordInput

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

采用一个可选参数：

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

HiddenInput

class HiddenInput

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

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

DateInput

class DateInput

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

采用与 TextInput 相同的参数，还有一个可选参数：

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

如果没有提供 format 参数，默认格式是在 :setting:`DATE_INPUT_FORMATS` 中找到的第一个格式，并尊重格式本地化。

DateTimeInput

class DateTimeInput

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

采用与 TextInput 相同的参数，还有一个可选参数：

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

如果没有提供 format 参数，默认格式是在 :setting:`DATETIME_INPUT_FORMATS` 中找到的第一个格式，并尊重格式本地化。

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

TimeInput

class TimeInput

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

采用与 TextInput 相同的参数，还有一个可选参数：

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

如果没有提供 format 参数，则默认格式是在 :setting:`TIME_INPUT_FORMATS` 中找到的第一个格式，并尊重格式本地化。

微秒的处理见DateTimeInput。

Textarea

class Textarea: ;* 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

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

采用一个可选参数：

check_test: 如果应选中该值的复选框，则采用 CheckboxInput 的值并返回 True 的可调用对象。

Select

class Select

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

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

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

SelectMultiple

class SelectMultiple

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

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

RadioSelect

class RadioSelect

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

类似于 Select，但呈现为 <li> 标签内的单选按钮列表：

<ul>
  <li><input type="radio" name="..."></li>
  ...
</ul>

要对生成的标记进行更精细的控制，您可以在模板中的单选按钮上循环。假设表单 myform 的字段 beatles 使用 RadioSelect 作为其小部件：

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

这将生成以下 HTML：

<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>

其中包括 <label> 标签。要获得更详细的信息，您可以使用每个单选按钮的 tag、choice_label 和 id_for_label 属性。例如，这个模板…

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

...将产生以下 HTML：

<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>

如果您决定不循环使用单选按钮——例如，如果您的模板包含 模板:Myform.beatles——它们将在带有 <li> 标签的 <ul> 中输出，如上所述。

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

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

CheckboxSelectMultiple

class CheckboxSelectMultiple

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

类似于 SelectMultiple，但呈现为复选框列表：

<ul>
  <li><input type="checkbox" name="..." ></li>
  ...
</ul>

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

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

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

文件上传小工具

FileInput

class FileInput: ;* template_name：'django/forms/widgets/file.html'

呈现为：<input type="file" ...>

ClearableFileInput

class ClearableFileInput: ;* template_name：'django/forms/widgets/clearable_file_input.html'

呈现为：<input type="file" ...> 带有额外的复选框输入以清除该字段的值，如果该字段不是必需的并且具有初始数据。

复合小部件

MultipleHiddenInput

class MultipleHiddenInput

template_name：'django/forms/widgets/multiple_hidden.html'
呈现为：多个 <input type="hidden" ...> 标签

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

SplitDateTimeWidget

class SplitDateTimeWidget

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

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

类似于 SplitDateTimeWidget，但使用 HiddenInput 作为日期和时间。

SelectDateWidget

class SelectDateWidget

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

环绕三个 Select 小部件：每个月、日和年各一个。

采用几个可选参数：

years: 在“年份”选择框中使用的可选年份列表/元组。默认值为包含当前年份和未来 9 年的列表。

months

在“月份”选择框中使用的可选月份字典。

dict 的键对应于月份编号（1-indexed），值是显示的月份：

MONTHS = {
    1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
    5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
    9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('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"),
    ),
)

“Django/docs/3.1.x/ref/forms/widgets”的版本间差异

2021年10月31日 (日) 04:14的最新版本

目录

小工具

指定小部件

为小部件设置参数

继承自 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

@@ 第1行： / 第1行： @@
+{{DISPLAYTITLE:小部件 — Django 文档}}
 <div id="module-django.forms.widgets" class="section">
 <span id="widgets"></span>
-= 小部件 =
+= 小工具 =
-A widget is Django's representation of an HTML input element. The widget
+小部件是 Django 对 HTML 输入元素的表示。 小部件处理 HTML 的呈现，以及从对应于小部件的 GET/POST 字典中提取数据。
-handles the rendering of the HTML, and the extraction of data from a GET/POST
-dictionary that corresponds to the widget.
-The HTML generated by the built-in widgets uses HTML5 syntax, targeting
+内置小部件生成的 HTML 使用 HTML5 语法，针对 <code>&lt;!DOCTYPE html&gt;</code>。 例如，它使用 <code>checked</code> 等布尔属性，而不是 <code>checked='checked'</code> 的 XHTML 样式。
-<code>&lt;!DOCTYPE html&gt;</code>. For example, it uses boolean attributes such as <code>checked</code>
-rather than the XHTML style of <code>checked='checked'</code>.
 <div class="admonition tip">
-小技巧
+提示
-Widgets should not be confused with the [[../fields|<span class="doc">form fields</span>]].
+小部件不应与 [[../fields|表单字段]] 混淆。 表单字段处理输入验证的逻辑并直接在模板中使用。 小部件处理网页上 HTML 表单输入元素的呈现和原始提交数据的提取。 但是，小部件确实需要 [[#widget-to-field|assigned]] 来形成字段。
-Form fields deal with the logic of input validation and are used directly
-in templates. Widgets deal with rendering of HTML form input elements on
-the web page and extraction of raw submitted data. However, widgets do
-need to be [[#widget-to-field|<span class="std std-ref">assigned</span>]] to form fields.
@@ 第27行： / 第20行： @@
 <span id="widget-to-field"></span>
-== Specifying widgets ==
+== 指定小部件 ==
-Whenever you specify a field on a form, Django will use a default widget
+每当您在表单上指定字段时，Django 将使用适合要显示的数据类型的默认小部件。 要查找哪个小部件用于哪个字段，请参阅有关 [[../fields#built-in-fields|内置字段类]] 的文档。
-that is appropriate to the type of data that is to be displayed. To find
-which widget is used on which field, see the documentation about
-[[../fields#built-in-fields|<span class="std std-ref">Built-in Field classes</span>]].
-However, if you want to use a different widget for a field, you can
+但是，如果您想对字段使用不同的小部件，则可以在字段定义中使用 [[../fields#django.forms.Field|widget]] 参数。 例如：
-use the [[../fields#django.forms.Field|<code>widget</code>]] argument on the field definition. For example:
 <div class="highlight-default notranslate">
@@ 第41行： / 第30行： @@
 <div class="highlight">
-<pre>from django import forms
+<syntaxhighlight lang="python">from django import forms
 class CommentForm(forms.Form):
      name = forms.CharField()
      url = forms.URLField()
-     comment = forms.CharField(widget=forms.Textarea)</pre>
+     comment = forms.CharField(widget=forms.Textarea)</syntaxhighlight>
 </div>
 </div>
-This would specify a form with a comment that uses a larger [[#django.forms.Textarea|<code>Textarea</code>]]
+这将指定一个带有注释的表单，该表单使用更大的 [[#django.forms.Textarea|Textarea]] 小部件，而不是默认的 [[#django.forms.TextInput|TextInput]] 小部件。
-widget, rather than the default [[#django.forms.TextInput|<code>TextInput</code>]] widget.
@@ 第58行： / 第46行： @@
 <div id="setting-arguments-for-widgets" class="section">
-== Setting arguments for widgets ==
+== 为小部件设置参数 ==
-Many widgets have optional extra arguments; they can be set when defining the
+许多小部件都有可选的额外参数； 它们可以在定义字段上的小部件时设置。 在以下示例中，为 [[#django.forms.SelectDateWidget|SelectDateWidget]] 设置了 [[#django.forms.SelectDateWidget.years|years]] 属性：
-widget on the field. In the following example, the
-[[#django.forms.SelectDateWidget.years|<code>years</code>]] attribute is set for a
-[[#django.forms.SelectDateWidget|<code>SelectDateWidget</code>]]:
 <div class="highlight-default notranslate">
@@ 第69行： / 第54行： @@
 <div class="highlight">
-<pre>from django import forms
+<syntaxhighlight lang="python">from django import forms
 BIRTH_YEAR_CHOICES = ['1980', '1981', '1982']
@@ 第84行： / 第69行： @@
          widget=forms.CheckboxSelectMultiple,
          choices=FAVORITE_COLORS_CHOICES,
-     )</pre>
+     )</syntaxhighlight>
 </div>
 </div>
-See the [[#built-in-widgets|<span class="std std-ref">Built-in widgets</span>]] for more information about which widgets
+有关哪些小部件可用以及它们接受哪些参数的更多信息，请参阅 [[#built-in-widgets|内置小部件]] 。
-are available and which arguments they accept.
@@ 第96行： / 第80行： @@
 <div id="widgets-inheriting-from-the-select-widget" class="section">
-== Widgets inheriting from the <code>Select</code> widget ==
+== 继承自 Select 小部件的小部件 ==
-Widgets inheriting from the [[#django.forms.Select|<code>Select</code>]] widget deal with choices. They
+继承自 [[#django.forms.Select|Select]] 小部件的小部件处理选择。 它们为用户提供了一个可供选择的选项列表。 不同的小部件以不同的方式呈现此选择； [[#django.forms.Select|Select]] 小部件本身使用 <code>&lt;select&gt;</code> HTML 列表表示，而 [[#django.forms.RadioSelect|RadioSelect]] 使用单选按钮。
-present the user with a list of options to choose from. The different widgets
-present this choice differently; the [[#django.forms.Select|<code>Select</code>]] widget itself uses a
-<code>&lt;select&gt;</code> HTML list representation, while [[#django.forms.RadioSelect|<code>RadioSelect</code>]] uses radio
-buttons.
-[[#django.forms.Select|<code>Select</code>]] widgets are used by default on [[../fields#django.forms|<code>ChoiceField</code>]] fields. The
+[[#django.forms.Select|Select]] 小部件默认用于 [[../fields#django.forms|ChoiceField]] 字段。 小部件上显示的选项继承自 [[../fields#django.forms|ChoiceField]]，更改 [[../fields#django.forms.ChoiceField|ChoiceField.choices]] 将更新 [[#django.forms.Select.choices|Select.choices]]。 例如：
-choices displayed on the widget are inherited from the [[../fields#django.forms|<code>ChoiceField</code>]] and
-changing [[../fields#django.forms.ChoiceField|<code>ChoiceField.choices</code>]] will update [[#django.forms.Select.choices|<code>Select.choices</code>]]. For
-example:
 <div class="highlight-default notranslate">
@@ 第113行： / 第90行： @@
 <div class="highlight">
-<pre>&gt;&gt;&gt; from django import forms
+<syntaxhighlight lang="python">>>> from django import forms
-&gt;&gt;&gt; CHOICES = [('1', 'First'), ('2', 'Second')]
+>>> CHOICES = [('1', 'First'), ('2', 'Second')]
-&gt;&gt;&gt; choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
+>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
-&gt;&gt;&gt; choice_field.choices
+>>> choice_field.choices
 [('1', 'First'), ('2', 'Second')]
-&gt;&gt;&gt; choice_field.widget.choices
+>>> choice_field.widget.choices
 [('1', 'First'), ('2', 'Second')]
-&gt;&gt;&gt; choice_field.widget.choices = []
+>>> choice_field.widget.choices = []
-&gt;&gt;&gt; choice_field.choices = [('1', 'First and only')]
+>>> choice_field.choices = [('1', 'First and only')]
-&gt;&gt;&gt; choice_field.widget.choices
+>>> choice_field.widget.choices
-[('1', 'First and only')]</pre>
+[('1', 'First and only')]</syntaxhighlight>
 </div>
 </div>
-Widgets which offer a [[#django.forms.Select.choices|<code>choices</code>]] attribute can however be used
+然而，提供 [[#django.forms.Select.choices|choices]] 属性的小部件可以与不基于选择的字段一起使用 - 例如 [[../fields#django.forms|CharField]] - 但建议使用 [[../fields#django.forms|ChoiceField]] -based field when the choices are inherent to the model and not just the representational widget.
-with fields which are not based on choice -- such as a [[../fields#django.forms|<code>CharField</code>]] --
-but it is recommended to use a [[../fields#django.forms|<code>ChoiceField</code>]]-based field when the
-choices are inherent to the model and not just the representational widget.
@@ 第137行： / 第111行： @@
 <div id="customizing-widget-instances" class="section">
-== Customizing widget instances ==
+== 自定义小部件实例 ==
-When Django renders a widget as HTML, it only renders very minimal markup -
+当 Django 将小部件呈现为 HTML 时，它只会呈现非常少的标记——Django 不会添加类名或任何其他特定于小部件的属性。 这意味着，例如，所有 [[#django.forms.TextInput|TextInput]] 小部件在您的网页上将显示相同。
-Django doesn't add class names, or any other widget-specific attributes. This
-means, for example, that all [[#django.forms.TextInput|<code>TextInput</code>]] widgets will appear the same
-on your Web pages.
-There are two ways to customize widgets: [[#styling-widget-instances|<span class="std std-ref">per widget instance</span>]] and [[#styling-widget-classes|<span class="std std-ref">per widget class</span>]].
+自定义小部件有两种方式：[[#styling-widget-instances|每个小部件实例]]和[[#styling-widget-classes|每个小部件类]]。
 <div id="styling-widget-instances" class="section">
 <span id="id1"></span>
-=== Styling widget instances ===
+=== 样式小部件实例 ===
-If you want to make one widget instance look different from another, you will
+如果您想让一个小部件实例看起来与另一个不同，您需要在小部件对象实例化并分配给表单字段时指定其他属性（并且可能向您的 CSS 文件添加一些规则）。
-need to specify additional attributes at the time when the widget object is
-instantiated and assigned to a form field (and perhaps add some rules to your
-CSS files).
-For example, take the following form:
+例如，采用以下形式：
 <div class="highlight-default notranslate">
@@ 第162行： / 第130行： @@
 <div class="highlight">
-<pre>from django import forms
+<syntaxhighlight lang="python">from django import forms
 class CommentForm(forms.Form):
      name = forms.CharField()
      url = forms.URLField()
-     comment = forms.CharField()</pre>
+     comment = forms.CharField()</syntaxhighlight>
 </div>
 </div>
-This form will include three default [[#django.forms.TextInput|<code>TextInput</code>]] widgets, with default
+此表单将包含三个默认的 [[#django.forms.TextInput|TextInput]] 小部件，具有默认呈现 - 没有 CSS 类，没有额外的属性。 这意味着为每个小部件提供的输入框将呈现完全相同：
-rendering -- no CSS class, no extra attributes. This means that the input boxes
-provided for each widget will be rendered exactly the same:
 <div class="highlight-default notranslate">
@@ 第180行： / 第146行： @@
 <div class="highlight">
-<pre>&gt;&gt;&gt; f = CommentForm(auto_id=False)
+<syntaxhighlight lang="python">>>> f = CommentForm(auto_id=False)
-&gt;&gt;&gt; f.as_table()
+>>> f.as_table()
-&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;name&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;
+<tr><th>Name:</th><td><input type="text" name="name" required></td></tr>
-&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;url&quot; name=&quot;url&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;
+<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
-&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;comment&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</pre>
+<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr></syntaxhighlight>
 </div>
 </div>
-On a real Web page, you probably don't want every widget to look the same. You
+在真实的 Web 页面上，您可能不希望每个小部件看起来都一样。 您可能需要更大的评论输入元素，并且您可能希望“名称”小部件具有一些特殊的 CSS 类。 还可以指定 'type' 属性以利用新的 HTML5 输入类型。 为此，您在创建小部件时使用 [[#django.forms.Widget.attrs|Widget.attrs]] 参数：
-might want a larger input element for the comment, and you might want the
-'name' widget to have some special CSS class. It is also possible to specify
-the 'type' attribute to take advantage of the new HTML5 input types. To do
-this, you use the [[#django.forms.Widget.attrs|<code>Widget.attrs</code>]] argument when creating the widget:
 <div class="highlight-default notranslate">
@@ 第199行： / 第161行： @@
 <div class="highlight">
-<pre>class CommentForm(forms.Form):
+<syntaxhighlight lang="python">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'}))</pre>
+     comment = forms.CharField(widget=forms.TextInput(attrs={'size': '40'}))</syntaxhighlight>
 </div>
 </div>
-You can also modify a widget in the form definition:
+您还可以修改表单定义中的小部件：
 <div class="highlight-default notranslate">
@@ 第213行： / 第175行： @@
 <div class="highlight">
-<pre>class CommentForm(forms.Form):
+<syntaxhighlight lang="python">class CommentForm(forms.Form):
      name = forms.CharField()
      url = forms.URLField()
@@ 第219行： / 第181行： @@
      name.widget.attrs.update({'class': 'special'})
-     comment.widget.attrs.update(size='40')</pre>
+     comment.widget.attrs.update(size='40')</syntaxhighlight>
 </div>
 </div>
-Or if the field isn't declared directly on the form (such as model form fields),
+或者，如果该字段未直接在表单上声明（例如模型表单字段），则可以使用 [[../api#django.forms.Form|Form.fields]] 属性：
-you can use the [[../api#django.forms.Form|<code>Form.fields</code>]] attribute:
 <div class="highlight-default notranslate">
@@ 第231行： / 第192行： @@
 <div class="highlight">
-<pre>class CommentForm(forms.ModelForm):
+<syntaxhighlight lang="python">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')</pre>
+         self.fields['comment'].widget.attrs.update(size='40')</syntaxhighlight>
 </div>
 </div>
-Django will then include the extra attributes in the rendered output:
+然后 Django 将在呈现的输出中包含额外的属性：
 <div class="doctest highlight-default notranslate">
@@ 第246行： / 第207行： @@
 <div class="highlight">
-<pre>&gt;&gt;&gt; f = CommentForm(auto_id=False)
+<syntaxhighlight lang="python">>>> f = CommentForm(auto_id=False)
-&gt;&gt;&gt; f.as_table()
+>>> f.as_table()
-&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;name&quot; class=&quot;special&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;
+<tr><th>Name:</th><td><input type="text" name="name" class="special" required></td></tr>
-&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;url&quot; name=&quot;url&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;
+<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
-&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type=&quot;text&quot; name=&quot;comment&quot; size=&quot;40&quot; required&gt;&lt;/td&gt;&lt;/tr&gt;</pre>
+<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required></td></tr></syntaxhighlight>
 </div>
 </div>
-You can also set the HTML <code>id</code> using [[#django.forms.Widget.attrs|<code>attrs</code>]]. See
+您还可以使用 [[#django.forms.Widget.attrs|attrs]] 设置 HTML <code>id</code>。 有关示例，请参阅 [[../api#django.forms.BoundField|BoundField.id_for_label]]。
-[[../api#django.forms.BoundField|<code>BoundField.id_for_label</code>]] for an example.
@@ 第263行： / 第223行： @@
 <span id="id2"></span>
-=== Styling widget classes ===
+=== 样式小部件类 ===
-With widgets, it is possible to add assets (<code>css</code> and <code>javascript</code>)
+使用小部件，可以添加资产（<code>css</code> 和 <code>javascript</code>）并更深入地自定义它们的外观和行为。
-and more deeply customize their appearance and behavior.
-In a nutshell, you will need to subclass the widget and either
+简而言之，您需要对小部件进行子类化，并 [[../../../topics/forms/media#assets-as-a-static-definition|定义“媒体”内部类]] 或 [[../../../topics/forms/media#dynamic-property|创建“媒体”属性]] 。
-[[../../../topics/forms/media#assets-as-a-static-definition|<span class="std std-ref">define a &quot;Media&quot; inner class</span>]] or
-[[../../../topics/forms/media#dynamic-property|<span class="std std-ref">create a &quot;media&quot; property</span>]].
-These methods involve somewhat advanced Python programming and are described in
+这些方法涉及一些高级 Python 编程，并在 [[../../../topics/forms/media|Form Assets]] 主题指南中进行了详细描述。
-detail in the [[../../../topics/forms/media|<span class="doc">Form Assets</span>]] topic guide.
@@ 第282行： / 第238行： @@
 <span id="id3"></span>
-== Base widget classes ==
+== 基本小部件类 ==
-Base widget classes [[#django.forms.Widget|<code>Widget</code>]] and [[#django.forms.MultiWidget|<code>MultiWidget</code>]] are subclassed by
+基本小部件类 [[#django.forms.Widget|Widget]] 和 [[#django.forms.MultiWidget|MultiWidget]] 是所有 [[#built-in-widgets|内置小部件]] 的子类，可以作为自定义小部件的基础。
-all the [[#built-in-widgets|<span class="std std-ref">built-in widgets</span>]] and may serve as a
-foundation for custom widgets.
 <div id="widget" class="section">
-=== <code>Widget</code> ===
+=== Widget ===
 <dl>
-<dt>''class'' <code>Widget</code><span class="sig-paren">(</span>''<span class="n">attrs</span><span class="o">=</span><span class="default_value">None</span>''<span class="sig-paren">)</span></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">Widget</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">attrs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>This abstract class cannot be rendered, but provides the basic attribute
+<dd><p>这个抽象类不能被渲染，但提供了基本属性 [[#django.forms.Widget.attrs|attrs]]。 您还可以在自定义小部件上实现或覆盖 [[#django.forms.Widget.render|render()]] 方法。</p>
-[[#django.forms.Widget.attrs|<code>attrs</code>]]. You may also implement or override the
-[[#django.forms.Widget.render|<code>render()</code>]] method on custom widgets.</p>
 <dl>
-<dt><code>attrs</code></dt>
+<dt><span class="sig-name descname"><span class="pre">attrs</span></span></dt>
-<dd><p>A dictionary containing HTML attributes to be set on the rendered
+<dd><p>包含要在呈现的小部件上设置的 HTML 属性的字典。</p>
-widget.</p>
 <div class="highlight-pycon notranslate">
 <div class="highlight">
-<pre>&gt;&gt;&gt; from django import forms
+<syntaxhighlight lang="pycon">>>> from django import forms
-&gt;&gt;&gt; name = forms.TextInput(attrs={'size': 10, 'title': 'Your name'})
+>>> name = forms.TextInput(attrs={'size': 10, 'title': 'Your name'})
-&gt;&gt;&gt; name.render('name', 'A name')
+>>> name.render('name', 'A name')
-'&lt;input title=&quot;Your name&quot; type=&quot;text&quot; name=&quot;name&quot; value=&quot;A name&quot; size=&quot;10&quot;&gt;'</pre>
+'<input title="Your name" type="text" name="name" value="A name" size="10">'</syntaxhighlight>
 </div>
 </div>
-<p>If you assign a value of <code>True</code> or <code>False</code> to an attribute,
+<p>如果您为属性分配 <code>True</code> 或 <code>False</code> 的值，它将呈现为 HTML5 布尔属性：</p>
-it will be rendered as an HTML5 boolean attribute:</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>&gt;&gt;&gt; name = forms.TextInput(attrs={'required': True})
+<syntaxhighlight lang="python">>>> name = forms.TextInput(attrs={'required': True})
-&gt;&gt;&gt; name.render('name', 'A name')
+>>> name.render('name', 'A name')
-'&lt;input name=&quot;name&quot; type=&quot;text&quot; value=&quot;A name&quot; required&gt;'
+'<input name="name" type="text" value="A name" required>'
-&gt;&gt;&gt;
+>>>
-&gt;&gt;&gt; name = forms.TextInput(attrs={'required': False})
+>>> name = forms.TextInput(attrs={'required': False})
-&gt;&gt;&gt; name.render('name', 'A name')
+>>> name.render('name', 'A name')
-'&lt;input name=&quot;name&quot; type=&quot;text&quot; value=&quot;A name&quot;&gt;'</pre>
+'<input name="name" type="text" value="A name">'</syntaxhighlight>
 </div>
@@ 第332行： / 第282行： @@
 <dl>
-<dt><code>supports_microseconds</code></dt>
+<dt><span class="sig-name descname"><span class="pre">supports_microseconds</span></span></dt>
-<dd><p>An attribute that defaults to <code>True</code>. If set to <code>False</code>, the
+<dd><p>默认为 <code>True</code> 的属性。 如果设置为 <code>False</code>，<code>datetime</code> 和 <code>time</code> 值的微秒部分将设置为 <code>0</code>。</p></dd></dl>
-microseconds part of <code>datetime</code> and
-<code>time</code> values will be set to <code>0</code>.</p></dd></dl>
 <dl>
-<dt><code>format_value</code><span class="sig-paren">(</span>''<span class="n">value</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">format_value</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">value</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Cleans and returns a value for use in the widget template. <code>value</code>
+<dd><p>清理并返回一个值以在小部件模板中使用。 <code>value</code> 不能保证是有效的输入，因此子类实现应该防御性地编程。</p></dd></dl>
-isn't guaranteed to be valid input, therefore subclass implementations
-should program defensively.</p></dd></dl>
 <dl>
-<dt><code>get_context</code><span class="sig-paren">(</span>''<span class="n">name</span>'', ''<span class="n">value</span>'', ''<span class="n">attrs</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">get_context</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">name</span></span>'', ''<span class="n"><span class="pre">value</span></span>'', ''<span class="n"><span class="pre">attrs</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Returns a dictionary of values to use when rendering the widget
+<dd><p>返回呈现小部件模板时要使用的值字典。 默认情况下，字典包含一个键，<code>'widget'</code>，它是包含以下键的小部件的字典表示：</p>
-template. By default, the dictionary contains a single key,
-<code>'widget'</code>, which is a dictionary representation of the widget
-containing the following keys:</p>
 <ul>
-<li><p><code>'name'</code>: The name of the field from the <code>name</code> argument.</p></li>
+<li><p><code>'name'</code>：来自 <code>name</code> 参数的字段名称。</p></li>
-<li><p><code>'is_hidden'</code>: A boolean indicating whether or not this widget is
+<li><p><code>'is_hidden'</code>：指示此小部件是否隐藏的布尔值。</p></li>
-hidden.</p></li>
+<li><p><code>'required'</code>：一个布尔值，指示是否需要此小部件的字段。</p></li>
-<li><p><code>'required'</code>: A boolean indicating whether or not the field for
+<li><p><code>'value'</code>：[[#django.forms.Widget.format_value|format_value()]] 返回的值。</p></li>
-this widget is required.</p></li>
+<li><p><code>'attrs'</code>：要在呈现的小部件上设置的 HTML 属性。 [[#django.forms.Widget.attrs|attrs]] 属性和 <code>attrs</code> 参数的组合。</p></li>
-<li><p><code>'value'</code>: The value as returned by [[#django.forms.Widget.format_value|<code>format_value()</code>]].</p></li>
+<li><p><code>'template_name'</code>：<code>self.template_name</code> 的值。</p></li></ul>
-<li><p><code>'attrs'</code>: HTML attributes to be set on the rendered widget. The
-combination of the [[#django.forms.Widget.attrs|<code>attrs</code>]] attribute and the <code>attrs</code> argument.</p></li>
-<li><p><code>'template_name'</code>: The value of <code>self.template_name</code>.</p></li></ul>
-<p><code>Widget</code> subclasses can provide custom context values by overriding
+<p><code>Widget</code> 子类可以通过覆盖此方法提供自定义上下文值。</p></dd></dl>
-this method.</p></dd></dl>
 <dl>
-<dt><code>id_for_label</code><span class="sig-paren">(</span>''<span class="n">id_</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">id_for_label</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">id_</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Returns the HTML ID attribute of this widget for use by a <code>&lt;label&gt;</code>,
+<dd><p>给定字段的 ID，返回此小部件的 HTML ID 属性以供 <code>&lt;label&gt;</code> 使用。 如果 ID 不可用，则返回 <code>None</code>。</p>
-given the ID of the field. Returns <code>None</code> if an ID isn't available.</p>
+<p>这个钩子是必要的，因为一些小部件有多个 HTML 元素，因此有多个 ID。 在这种情况下，此方法应返回与小部件标签中的第一个 ID 对应的 ID 值。</p></dd></dl>
-<p>This hook is necessary because some widgets have multiple HTML
-elements and, thus, multiple IDs. In that case, this method should
-return an ID value that corresponds to the first ID in the widget's
-tags.</p></dd></dl>
 <dl>
-<dt><code>render</code><span class="sig-paren">(</span>''<span class="n">name</span>'', ''<span class="n">value</span>'', ''<span class="n">attrs</span><span class="o">=</span><span class="default_value">None</span>'', ''<span class="n">renderer</span><span class="o">=</span><span class="default_value">None</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">render</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">name</span></span>'', ''<span class="n"><span class="pre">value</span></span>'', ''<span class="n"><span class="pre">attrs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">renderer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Renders a widget to HTML using the given renderer. If <code>renderer</code> is
+<dd><p>使用给定的渲染器将小部件渲染为 HTML。 如果 <code>renderer</code> 是 <code>None</code>，则使用 [[#id4|:setting:`FORM_RENDERER`]] 设置中的渲染器。</p></dd></dl>
-<code>None</code>, the renderer from the [[../../settings#std-setting-FORM_RENDERER|<code>FORM_RENDERER</code>]] setting is
-used.</p></dd></dl>
 <dl>
-<dt><code>value_from_datadict</code><span class="sig-paren">(</span>''<span class="n">data</span>'', ''<span class="n">files</span>'', ''<span class="n">name</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">value_from_datadict</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">data</span></span>'', ''<span class="n"><span class="pre">files</span></span>'', ''<span class="n"><span class="pre">name</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Given a dictionary of data and this widget's name, returns the value
+<dd><p>给定一个数据字典和这个小部件的名称，返回这个小部件的值。 <code>files</code> 可能包含来自 [[../../request-response#django.http.HttpRequest|request.FILES]] 的数据。 如果未提供值，则返回 <code>None</code>。 还要注意 <code>value_from_datadict</code> 在处理表单数据的过程中可能会被多次调用，所以如果你自定义它并添加昂贵的处理，你应该自己实现一些缓存机制。</p></dd></dl>
-of this widget. <code>files</code> may contain data coming from
-[[../../request-response#django.http.HttpRequest|<code>request.FILES</code>]]. Returns <code>None</code>
-if a value wasn't provided. Note also that <code>value_from_datadict</code> may
-be called more than once during handling of form data, so if you
-customize it and add expensive processing, you should implement some
-caching mechanism yourself.</p></dd></dl>
 <dl>
-<dt><code>value_omitted_from_data</code><span class="sig-paren">(</span>''<span class="n">data</span>'', ''<span class="n">files</span>'', ''<span class="n">name</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">value_omitted_from_data</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">data</span></span>'', ''<span class="n"><span class="pre">files</span></span>'', ''<span class="n"><span class="pre">name</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Given <code>data</code> and <code>files</code> dictionaries and this widget's name,
+<dd><p>给定 <code>data</code> 和 <code>files</code> 字典和这个小部件的名称，返回小部件是否有数据或文件。</p>
-returns whether or not there's data or files for the widget.</p>
+<p>该方法的结果会影响模型表单 [[../../../topics/forms/modelforms#topics-modelform-save|中的字段是否回退到其默认值]] 。</p>
-<p>The method's result affects whether or not a field in a model form
+<p>特殊情况是 [[#django.forms.CheckboxInput|CheckboxInput]]、[[#django.forms.CheckboxSelectMultiple|CheckboxSelectMultiple]] 和 [[#django.forms.SelectMultiple|SelectMultiple]]，它们总是返回 <code>False</code> 因为未选中的复选框和未选中的 <code>&lt;select multiple&gt;</code> '不会出现在 HTML 表单提交的数据中，因此不知道用户是否提交了值。</p></dd></dl>
-[[../../../topics/forms/modelforms#topics-modelform-save|<span class="std std-ref">falls back to its default</span>]].</p>
-<p>Special cases are [[#django.forms.CheckboxInput|<code>CheckboxInput</code>]],
-[[#django.forms.CheckboxSelectMultiple|<code>CheckboxSelectMultiple</code>]], and
-[[#django.forms.SelectMultiple|<code>SelectMultiple</code>]], which always return
-<code>False</code> because an unchecked checkbox and unselected
-<code>&lt;select multiple&gt;</code> don't appear in the data of an HTML form
-submission, so it's unknown whether or not the user submitted a value.</p></dd></dl>
 <dl>
-<dt><code>use_required_attribute</code><span class="sig-paren">(</span>''<span class="n">initial</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">use_required_attribute</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">initial</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>Given a form field's <code>initial</code> value, returns whether or not the
+<dd><p>给定表单字段的 <code>initial</code> 值，返回是否可以使用 <code>required</code> HTML 属性呈现小部件。 表单使用此方法以及 [[../fields#django.forms.Field|Field.required]] 和 [[../api#django.forms.Form|Form.use_required_attribute]] 来确定是否为每个字段显示 <code>required</code> 属性。</p>
-widget can be rendered with the <code>required</code> HTML attribute. Forms use
+<p>默认情况下，为隐藏小部件返回 <code>False</code>，否则返回 <code>True</code>。 特殊情况是 [[#django.forms.FileInput|FileInput]] 和 [[#django.forms.ClearableFileInput|ClearableFileInput]]，当设置 <code>initial</code> 时返回 <code>False</code>，以及 [[#django.forms.CheckboxSelectMultiple|CheckboxSelectMultiple]]，总是返回 [ X174X] 因为浏览器验证需要选中所有复选框，而不是至少选中一个。</p>
-this method along with [[../fields#django.forms.Field|<code>Field.required</code>]] and [[../api#django.forms.Form|<code>Form.use_required_attribute</code>]] to determine whether or not
+<p>在与浏览器验证不兼容的自定义小部件中覆盖此方法。 例如，由隐藏的 <code>textarea</code> 元素支持的 WSYSIWG 文本编辑器小部件可能希望始终返回 <code>False</code> 以避免对隐藏字段进行浏览器验证。</p>
-to display the <code>required</code> attribute for each field.</p>
-<p>By default, returns <code>False</code> for hidden widgets and <code>True</code>
-otherwise. Special cases are [[#django.forms.FileInput|<code>FileInput</code>]] and
-[[#django.forms.ClearableFileInput|<code>ClearableFileInput</code>]], which return <code>False</code> when
-<code>initial</code> is set, and [[#django.forms.CheckboxSelectMultiple|<code>CheckboxSelectMultiple</code>]],
-which always returns <code>False</code> because browser validation would require
-all checkboxes to be checked instead of at least one.</p>
-<p>Override this method in custom widgets that aren't compatible with
-browser validation. For example, a WSYSIWG text editor widget backed by
-a hidden <code>textarea</code> element may want to always return <code>False</code> to
-avoid browser validation on the hidden field.</p>
 <div class="versionchanged">
-<p>In older versions, <code>True</code> was returned for
+<p><span class="versionmodified changed"> 3.1 版更改： </span> 在旧版本中，设置 <code>initial</code> 时为 [[#django.forms.FileInput|FileInput]] 返回 <code>True</code>。</p>
-[[#django.forms.FileInput|<code>FileInput</code>]] when <code>initial</code> was set.</p>
 </div></dd></dl>
@@ 第429行： / 第337行： @@
 <div id="multiwidget" class="section">
-=== <code>MultiWidget</code> ===
+=== MultiWidget ===
 <dl>
-<dt>''class'' <code>MultiWidget</code><span class="sig-paren">(</span>''<span class="n">widgets</span>'', ''<span class="n">attrs</span><span class="o">=</span><span class="default_value">None</span>''<span class="sig-paren">)</span></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">MultiWidget</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">widgets</span></span>'', ''<span class="n"><span class="pre">attrs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>A widget that is composed of multiple widgets.
+<dd><p>由多个小部件组成的小部件。 [[#django.forms.MultiWidget|MultiWidget]] 与 [[../fields#django.forms|MultiValueField]] 协同工作。</p>
-[[#django.forms.MultiWidget|<code>MultiWidget</code>]] works hand in hand with the
+<p>[[#django.forms.MultiWidget|MultiWidget]] 有一个必需的参数：</p>
-[[../fields#django.forms|<code>MultiValueField</code>]].</p>
-<p>[[#django.forms.MultiWidget|<code>MultiWidget</code>]] has one required argument:</p>
 <dl>
-<dt><code>widgets</code></dt>
+<dt><span class="sig-name descname"><span class="pre">widgets</span></span></dt>
-<dd><p>An iterable containing the widgets needed. For example:</p>
+<dd><p>包含所需小部件的可迭代对象。 例如：</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>&gt;&gt;&gt; from django.forms import MultiWidget, TextInput
+<syntaxhighlight lang="python">>>> from django.forms import MultiWidget, TextInput
-&gt;&gt;&gt; widget = MultiWidget(widgets=[TextInput, TextInput])
+>>> widget = MultiWidget(widgets=[TextInput, TextInput])
-&gt;&gt;&gt; widget.render('name', ['john', 'paul'])
+>>> widget.render('name', ['john', 'paul'])
-'&lt;input type=&quot;text&quot; name=&quot;name_0&quot; value=&quot;john&quot;&gt;&lt;input type=&quot;text&quot; name=&quot;name_1&quot; value=&quot;paul&quot;&gt;'</pre>
+'<input type="text" name="name_0" value="john"><input type="text" name="name_1" value="paul">'</syntaxhighlight>
 </div>
 </div>
-<p>You may provide a dictionary in order to specify custom suffixes for
+<p>您可以提供字典以便为每个子小部件上的 <code>name</code> 属性指定自定义后缀。 在这种情况下，对于每个 <code>(key, widget)</code> 对，密钥将附加到小部件的 <code>name</code> 以生成属性值。 您可以为单个键提供空字符串 (<code>''</code>)，以抑制一个小部件的后缀。 例如：</p>
-the <code>name</code> attribute on each subwidget. In this case, for each
-<code>(key, widget)</code> pair, the key will be appended to the <code>name</code> of the
-widget in order to generate the attribute value. You may provide the
-empty string (<code>''</code>) for a single key, in order to suppress the suffix
-for one widget. For example:</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>&gt;&gt;&gt; widget = MultiWidget(widgets={'': TextInput, 'last': TextInput})
+<syntaxhighlight lang="python">>>> widget = MultiWidget(widgets={'': TextInput, 'last': TextInput})
-&gt;&gt;&gt; widget.render('name', ['john', 'lennon'])
+>>> widget.render('name', ['john', 'paul'])
-'&lt;input type=&quot;text&quot; name=&quot;name&quot; value=&quot;john&quot;&gt;&lt;input type=&quot;text&quot; name=&quot;name_last&quot; value=&quot;paul&quot;&gt;'</pre>
+'<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'</syntaxhighlight>
 </div>
@@ 第470行： / 第371行： @@
 </div></dd></dl>
-<p>And one required method:</p>
+<p>以及一种必需的方法：</p>
 <dl>
-<dt><code>decompress</code><span class="sig-paren">(</span>''<span class="n">value</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">decompress</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">value</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>This method takes a single &quot;compressed&quot; value from the field and
+<dd><p>此方法从字段中获取单个“压缩”值并返回“解压缩”值列表。 可以假定输入值有效，但不一定非空。</p>
-returns a list of &quot;decompressed&quot; values. The input value can be
+<p>这个方法'''必须由子类实现'''，并且由于值可能为空，所以实现必须是防御性的。</p>
-assumed valid, but not necessarily non-empty.</p>
+<p>“解压”背后的基本原理是必须将表单字段的组合值“拆分”为每个小部件的值。</p>
-<p>This method '''must be implemented''' by the subclass, and since the
+<p>这方面的一个例子是 [[#django.forms.SplitDateTimeWidget|SplitDateTimeWidget]] 如何将 <code>datetime</code> 值转换为一个列表，其中日期和时间分为两个单独的值：</p>
-value may be empty, the implementation must be defensive.</p>
-<p>The rationale behind &quot;decompression&quot; is that it is necessary to &quot;split&quot;
-the combined value of the form field into the values for each widget.</p>
-<p>An example of this is how [[#django.forms.SplitDateTimeWidget|<code>SplitDateTimeWidget</code>]] turns a
-<code>datetime</code> value into a list with date and time split
-into two separate values:</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>from django.forms import MultiWidget
+<syntaxhighlight lang="python">from django.forms import MultiWidget
 class SplitDateTimeWidget(MultiWidget):
@@ 第496行： / 第391行： @@
          if value:
              return [value.date(), value.time()]
-         return [None, None]</pre>
+         return [None, None]</syntaxhighlight>
 </div>
@@ 第503行： / 第398行： @@
 <div class="admonition tip">
-<p>小技巧</p>
+<p>提示</p>
-<p>Note that [[../fields#django.forms|<code>MultiValueField</code>]] has a
+<p>请注意， [[../fields#django.forms|MultiValueField]] 有一个补充方法 [[../fields#django.forms.MultiValueField|compress()]] 具有相反的职责 - 将所有成员字段的清理值合并为一个。</p>
-complementary method [[../fields#django.forms.MultiValueField|<code>compress()</code>]]
-with the opposite responsibility - to combine cleaned values of
-all member fields into one.</p>
 </div></dd></dl>
-<p>It provides some custom context:</p>
+<p>它提供了一些自定义上下文：</p>
 <dl>
-<dt><code>get_context</code><span class="sig-paren">(</span>''<span class="n">name</span>'', ''<span class="n">value</span>'', ''<span class="n">attrs</span>''<span class="sig-paren">)</span></dt>
+<dt><span class="sig-name descname"><span class="pre">get_context</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">name</span></span>'', ''<span class="n"><span class="pre">value</span></span>'', ''<span class="n"><span class="pre">attrs</span></span>''<span class="sig-paren">)</span></dt>
-<dd><p>In addition to the <code>'widget'</code> key described in
+<dd><p>除了 [[#django.forms.Widget.get_context|Widget.get_context()]] 中描述的 <code>'widget'</code> 键之外，<code>MultiWidget</code> 添加了一个 <code>widget['subwidgets']</code> 键。</p>
-[[#django.forms.Widget.get_context|<code>Widget.get_context()</code>]], <code>MultiValueWidget</code> adds a
+<p>这些可以在小部件模板中循环：</p>
-<code>widget['subwidgets']</code> key.</p>
-<p>These can be looped over in the widget template:</p>
 <div class="highlight-html+django notranslate">
 <div class="highlight">
-<pre>{% for subwidget in widget.subwidgets %}
+<syntaxhighlight lang="html+django">{% for subwidget in widget.subwidgets %}
      {% include subwidget.template_name with widget=subwidget %}
-{% endfor %}</pre>
+{% endfor %}</syntaxhighlight>
 </div>
@@ 第530行： / 第420行： @@
 </div></dd></dl>
-<p>Here's an example widget which subclasses [[#django.forms.MultiWidget|<code>MultiWidget</code>]] to display
+<p>这是一个示例小部件，它子类化 [[#django.forms.MultiWidget|MultiWidget]] 以在不同的选择框中显示带有日、月和年的日期。 此小部件旨在与 [[../fields#django.forms|DateField]] 而不是 [[../fields#django.forms|MultiValueField]] 一起使用，因此我们实现了 [[#django.forms.Widget.value_from_datadict|value_from_datadict()]]：</p>
-a date with the day, month, and year in different select boxes. This widget
-is intended to be used with a [[../fields#django.forms|<code>DateField</code>]] rather than
-a [[../fields#django.forms|<code>MultiValueField</code>]], thus we have implemented
-[[#django.forms.Widget.value_from_datadict|<code>value_from_datadict()</code>]]:</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>from datetime import date
+<syntaxhighlight lang="python">from datetime import date
 from django import forms
@@ 第565行： / 第451行： @@
          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)</pre>
+         return '{}-{}-{}'.format(year, month, day)</syntaxhighlight>
 </div>
 </div>
-<p>The constructor creates several [[#django.forms.Select|<code>Select</code>]] widgets in a list. The
+<p>构造函数在一个列表中创建了几个 [[#django.forms.Select|Select]] 小部件。 <code>super()</code> 方法使用此列表来设置小部件。</p>
-<code>super()</code> method uses this list to setup the widget.</p>
+<p>所需的方法 [[#django.forms.MultiWidget.decompress|decompress()]] 将 <code>datetime.date</code> 值分解为与每个小部件对应的日、月和年值。 如果选择了无效的日期，例如不存在的 2 月 30 日，则 [[../fields#django.forms|DateField]] 会向该方法传递一个字符串，因此需要解析。 当 <code>value</code> 为 <code>None</code> 时，最终的 <code>return</code> 处理，这意味着我们的子部件没有任何默认值。</p>
-<p>The required method [[#django.forms.MultiWidget.decompress|<code>decompress()</code>]] breaks up a
+<p>[[#django.forms.Widget.value_from_datadict|value_from_datadict()]] 的默认实现返回与每个 <code>Widget</code> 对应的值列表。 这适用于使用 <code>MultiWidget</code> 和 [[../fields#django.forms|MultiValueField]]。 但是由于我们想要使用带有一个 [[../fields#django.forms|DateField]] 的小部件，它接受一个值，我们已经覆盖了这个方法。 这里的实现将来自 subwidget 的数据以 [[../fields#django.forms|DateField]] 期望的格式组合成一个字符串。</p></dd></dl>
-<code>datetime.date</code> value into the day, month, and year values corresponding
-to each widget. If an invalid date was selected, such as the non-existent
-th February, the [[../fields#django.forms|<code>DateField</code>]] passes this method a
-string instead, so that needs parsing. The final <code>return</code> handles when
-<code>value</code> is <code>None</code>, meaning we don't have any defaults for our
-subwidgets.</p>
-<p>The default implementation of [[#django.forms.Widget.value_from_datadict|<code>value_from_datadict()</code>]] returns a
-list of values corresponding to each <code>Widget</code>. This is appropriate when
-using a <code>MultiWidget</code> with a [[../fields#django.forms|<code>MultiValueField</code>]]. But
-since we want to use this widget with a [[../fields#django.forms|<code>DateField</code>]],
-which takes a single value, we have overridden this method. The
-implementation here combines the data from the subwidgets into a string in
-the format that [[../fields#django.forms|<code>DateField</code>]] expects.</p></dd></dl>
@@ 第593行： / 第466行： @@
 <div id="built-in-widgets" class="section">
-<span id="id4"></span>
+<span id="id6"></span>
-== Built-in widgets ==
+== 内置小部件 ==
-Django provides a representation of all the basic HTML widgets, plus some
+Django 提供了所有基本 HTML 小部件的表示，以及 <code>django.forms.widgets</code> 模块中一些常用的小部件组，包括 [[#text-widgets|文本输入]] 、 [[#selector-widgets|各种复选框和选择器]] , [[#file-upload-widgets|上传文件]] 和 [[#composite-widgets|处理多值输入]] 。
-commonly used groups of widgets in the <code>django.forms.widgets</code> module,
-including [[#text-widgets|<span class="std std-ref">the input of text</span>]], [[#selector-widgets|<span class="std std-ref">various checkboxes
-and selectors</span>]], [[#file-upload-widgets|<span class="std std-ref">uploading files</span>]],
-and [[#composite-widgets|<span class="std std-ref">handling of multi-valued input</span>]].
 <div id="widgets-handling-input-of-text" class="section">
 <span id="text-widgets"></span>
-=== Widgets handling input of text ===
+=== 处理文本输入的小部件 ===
-These widgets make use of the HTML elements <code>input</code> and <code>textarea</code>.
+这些小部件使用 HTML 元素 <code>input</code> 和 <code>textarea</code>。
 <div id="textinput" class="section">
-==== <code>TextInput</code> ====
+==== TextInput ====
-; ''class'' <code>TextInput</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">TextInput</span></span>
-: ;* <code>input_type</code>: <code>'text'</code>
+: ;* <code>input_type</code>：<code>'text'</code>
-;* <code>template_name</code>: <code>'django/forms/widgets/text.html'</code>
+;* <code>template_name</code>：<code>'django/forms/widgets/text.html'</code>
-;* Renders as: <code>&lt;input type=&quot;text&quot; ...&gt;</code>
+;* 呈现为：<code>&lt;input type=&quot;text&quot; ...&gt;</code>
@@ 第622行： / 第491行： @@
 <div id="numberinput" class="section">
-==== <code>NumberInput</code> ====
+==== NumberInput ====
 <dl>
-<dt>''class'' <code>NumberInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">NumberInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'number'</code></p></li>
+<li><p><code>input_type</code>：<code>'number'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/number.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/number.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;number&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;number&quot; ...&gt;</code></p></li></ul>
-<p>Beware that not all browsers support entering localized numbers in
+<p>请注意，并非所有浏览器都支持在 <code>number</code> 输入类型中输入本地化数字。 Django 本身避免将它们用于将 [[../fields#django.forms.Field|localize]] 属性设置为 <code>True</code> 的字段。</p></dd></dl>
-<code>number</code> input types. Django itself avoids using them for fields having
-their [[../fields#django.forms.Field|<code>localize</code>]] property set to <code>True</code>.</p></dd></dl>
@@ 第639行： / 第506行： @@
 <div id="emailinput" class="section">
-==== <code>EmailInput</code> ====
+==== EmailInput ====
-; ''class'' <code>EmailInput</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">EmailInput</span></span>
-: ;* <code>input_type</code>: <code>'email'</code>
+: ;* <code>input_type</code>：<code>'email'</code>
-;* <code>template_name</code>: <code>'django/forms/widgets/email.html'</code>
+;* <code>template_name</code>：<code>'django/forms/widgets/email.html'</code>
-;* Renders as: <code>&lt;input type=&quot;email&quot; ...&gt;</code>
+;* 呈现为：<code>&lt;input type=&quot;email&quot; ...&gt;</code>
@@ 第650行： / 第517行： @@
 <div id="urlinput" class="section">
-==== <code>URLInput</code> ====
+==== URLInput ====
-; ''class'' <code>URLInput</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">URLInput</span></span>
-: ;* <code>input_type</code>: <code>'url'</code>
+: ;* <code>input_type</code>：<code>'url'</code>
-;* <code>template_name</code>: <code>'django/forms/widgets/url.html'</code>
+;* <code>template_name</code>：<code>'django/forms/widgets/url.html'</code>
-;* Renders as: <code>&lt;input type=&quot;url&quot; ...&gt;</code>
+;* 呈现为：<code>&lt;input type=&quot;url&quot; ...&gt;</code>
@@ 第661行： / 第528行： @@
 <div id="passwordinput" class="section">
-==== <code>PasswordInput</code> ====
+==== PasswordInput ====
 <dl>
-<dt>''class'' <code>PasswordInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">PasswordInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'password'</code></p></li>
+<li><p><code>input_type</code>：<code>'password'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/password.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/password.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;password&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;password&quot; ...&gt;</code></p></li></ul>
-<p>Takes one optional argument:</p>
+<p>采用一个可选参数：</p>
 <dl>
-<dt><code>render_value</code></dt>
+<dt><span class="sig-name descname"><span class="pre">render_value</span></span></dt>
-<dd><p>Determines whether the widget will have a value filled in when the
+<dd><p>确定在验证错误后重新显示表单时小部件是否将填充值（默认为 <code>False</code>）。</p></dd></dl>
-form is re-displayed after a validation error (default is <code>False</code>).</p></dd></dl>
 </dd></dl>
@@ 第681行： / 第547行： @@
 <div id="hiddeninput" class="section">
-==== <code>HiddenInput</code> ====
+==== HiddenInput ====
 <dl>
-<dt>''class'' <code>HiddenInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">HiddenInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'hidden'</code></p></li>
+<li><p><code>input_type</code>：<code>'hidden'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/hidden.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/hidden.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;hidden&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;hidden&quot; ...&gt;</code></p></li></ul>
-<p>Note that there also is a [[#django.forms.MultipleHiddenInput|<code>MultipleHiddenInput</code>]] widget that
+<p>请注意，还有一个 [[#django.forms.MultipleHiddenInput|MultipleHiddenInput]] 小部件封装了一组隐藏的输入元素。</p></dd></dl>
-encapsulates a set of hidden input elements.</p></dd></dl>
@@ 第697行： / 第562行： @@
 <div id="dateinput" class="section">
-==== <code>DateInput</code> ====
+==== DateInput ====
 <dl>
-<dt>''class'' <code>DateInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">DateInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'text'</code></p></li>
+<li><p><code>input_type</code>：<code>'text'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/date.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/date.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
-<p>Takes same arguments as [[#django.forms.TextInput|<code>TextInput</code>]], with one more optional argument:</p>
+<p>采用与 [[#django.forms.TextInput|TextInput]] 相同的参数，还有一个可选参数：</p>
 <dl>
-<dt><code>format</code></dt>
+<dt><span class="sig-name descname"><span class="pre">format</span></span></dt>
-<dd><p>The format in which this field's initial value will be displayed.</p></dd></dl>
+<dd><p>此字段的初始值将显示的格式。</p></dd></dl>
-<p>If no <code>format</code> argument is provided, the default format is the first
+<p>如果没有提供 <code>format</code> 参数，默认格式是在 [[#id7|:setting:`DATE_INPUT_FORMATS`]] 中找到的第一个格式，并尊重 [[../../../topics/i18n/formatting|格式本地化]] 。</p></dd></dl>
-format found in [[../../settings#std-setting-DATE_INPUT_FORMATS|<code>DATE_INPUT_FORMATS</code>]] and respects
-[[../../../topics/i18n/formatting|<span class="doc">本地格式化</span>]].</p></dd></dl>
@@ 第719行： / 第582行： @@
 <div id="datetimeinput" class="section">
-==== <code>DateTimeInput</code> ====
+==== DateTimeInput ====
 <dl>
-<dt>''class'' <code>DateTimeInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">DateTimeInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'text'</code></p></li>
+<li><p><code>input_type</code>：<code>'text'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/datetime.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/datetime.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
-<p>Takes same arguments as [[#django.forms.TextInput|<code>TextInput</code>]], with one more optional argument:</p>
+<p>采用与 [[#django.forms.TextInput|TextInput]] 相同的参数，还有一个可选参数：</p>
 <dl>
-<dt><code>format</code></dt>
+<dt><span class="sig-name descname"><span class="pre">format</span></span></dt>
-<dd><p>The format in which this field's initial value will be displayed.</p></dd></dl>
+<dd><p>此字段的初始值将显示的格式。</p></dd></dl>
-<p>If no <code>format</code> argument is provided, the default format is the first
+<p>如果没有提供 <code>format</code> 参数，默认格式是在 [[#id9|:setting:`DATETIME_INPUT_FORMATS`]] 中找到的第一个格式，并尊重 [[../../../topics/i18n/formatting|格式本地化]] 。</p>
-format found in [[../../settings#std-setting-DATETIME_INPUT_FORMATS|<code>DATETIME_INPUT_FORMATS</code>]] and respects
+<p>默认情况下，时间值的微秒部分始终设置为 <code>0</code>。 如果需要微秒，请使用 [[#django.forms.Widget.supports_microseconds|supports_microseconds]] 属性设置为 <code>True</code> 的子类。</p></dd></dl>
-[[../../../topics/i18n/formatting|<span class="doc">本地格式化</span>]].</p>
-<p>By default, the microseconds part of the time value is always set to <code>0</code>.
-If microseconds are required, use a subclass with the
-[[#django.forms.Widget.supports_microseconds|<code>supports_microseconds</code>]] attribute set to <code>True</code>.</p></dd></dl>
@@ 第744行： / 第603行： @@
 <div id="timeinput" class="section">
-==== <code>TimeInput</code> ====
+==== TimeInput ====
 <dl>
-<dt>''class'' <code>TimeInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">TimeInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'text'</code></p></li>
+<li><p><code>input_type</code>：<code>'text'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/time.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/time.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;text&quot; ...&gt;</code></p></li></ul>
-<p>Takes same arguments as [[#django.forms.TextInput|<code>TextInput</code>]], with one more optional argument:</p>
+<p>采用与 [[#django.forms.TextInput|TextInput]] 相同的参数，还有一个可选参数：</p>
 <dl>
-<dt><code>format</code></dt>
+<dt><span class="sig-name descname"><span class="pre">format</span></span></dt>
-<dd><p>The format in which this field's initial value will be displayed.</p></dd></dl>
+<dd><p>此字段的初始值将显示的格式。</p></dd></dl>
-<p>If no <code>format</code> argument is provided, the default format is the first
+<p>如果没有提供 <code>format</code> 参数，则默认格式是在 [[#id11|:setting:`TIME_INPUT_FORMATS`]] 中找到的第一个格式，并尊重 [[../../../topics/i18n/formatting|格式本地化]] 。</p>
-format found in [[../../settings#std-setting-TIME_INPUT_FORMATS|<code>TIME_INPUT_FORMATS</code>]] and respects
+<p>微秒的处理见[[#django.forms.DateTimeInput|DateTimeInput]]。</p></dd></dl>
-[[../../../topics/i18n/formatting|<span class="doc">本地格式化</span>]].</p>
-<p>For the treatment of microseconds, see [[#django.forms.DateTimeInput|<code>DateTimeInput</code>]].</p></dd></dl>
@@ 第767行： / 第624行： @@
 <div id="textarea" class="section">
-==== <code>Textarea</code> ====
+==== Textarea ====
-; ''class'' <code>Textarea</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">Textarea</span></span>
-: ;* <code>template_name</code>: <code>'django/forms/widgets/textarea.html'</code>
+: ;* <code>template_name</code>：<code>'django/forms/widgets/textarea.html'</code>
-;* Renders as: <code>&lt;textarea&gt;...&lt;/textarea&gt;</code>
+;* 呈现为：<code>&lt;textarea&gt;...&lt;/textarea&gt;</code>
@@ 第780行： / 第637行： @@
 <span id="selector-widgets"></span>
-=== Selector and checkbox widgets ===
+=== 选择器和复选框小部件 ===
-These widgets make use of the HTML elements <code>&lt;select&gt;</code>,
+这些小部件使用 HTML 元素 <code>&lt;select&gt;</code>、<code>&lt;input type=&quot;checkbox&quot;&gt;</code> 和 <code>&lt;input type=&quot;radio&quot;&gt;</code>。
-<code>&lt;input type=&quot;checkbox&quot;&gt;</code>, and <code>&lt;input type=&quot;radio&quot;&gt;</code>.
-Widgets that render multiple choices have an <code>option_template_name</code> attribute
+呈现多个选项的小部件具有 <code>option_template_name</code> 属性，该属性指定用于呈现每个选项的模板。 例如，对于 [[#django.forms.Select|Select]] 小部件，<code>select_option.html</code> 为 <code>&lt;select&gt;</code> 渲染 <code>&lt;option&gt;</code>。
-that specifies the template used to render each choice. For example, for the
-[[#django.forms.Select|<code>Select</code>]] widget, <code>select_option.html</code> renders the <code>&lt;option&gt;</code> for a
-<code>&lt;select&gt;</code>.
 <div id="checkboxinput" class="section">
-==== <code>CheckboxInput</code> ====
+==== CheckboxInput ====
 <dl>
-<dt>''class'' <code>CheckboxInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">CheckboxInput</span></span></dt>
 <dd><ul>
-<li><p><code>input_type</code>: <code>'checkbox'</code></p></li>
+<li><p><code>input_type</code>：<code>'checkbox'</code></p></li>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/checkbox.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/checkbox.html'</code></p></li>
-<li><p>Renders as: <code>&lt;input type=&quot;checkbox&quot; ...&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;input type=&quot;checkbox&quot; ...&gt;</code></p></li></ul>
-<p>Takes one optional argument:</p>
+<p>采用一个可选参数：</p>
 <dl>
-<dt><code>check_test</code></dt>
+<dt><span class="sig-name descname"><span class="pre">check_test</span></span></dt>
-<dd><p>A callable that takes the value of the <code>CheckboxInput</code> and returns
+<dd><p>如果应选中该值的复选框，则采用 <code>CheckboxInput</code> 的值并返回 <code>True</code> 的可调用对象。</p></dd></dl>
-<code>True</code> if the checkbox should be checked for that value.</p></dd></dl>
 </dd></dl>
@@ 第812行： / 第664行： @@
 <div id="select" class="section">
-==== <code>Select</code> ====
+==== Select ====
 <dl>
-<dt>''class'' <code>Select</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">Select</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/select.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/select.html'</code></p></li>
-<li><p><code>option_template_name</code>: <code>'django/forms/widgets/select_option.html'</code></p></li>
+<li><p><code>option_template_name</code>：<code>'django/forms/widgets/select_option.html'</code></p></li>
-<li><p>Renders as: <code>&lt;select&gt;&lt;option ...&gt;...&lt;/select&gt;</code></p></li></ul>
+<li><p>呈现为：<code>&lt;select&gt;&lt;option ...&gt;...&lt;/select&gt;</code></p></li></ul>
 <dl>
-<dt><code>choices</code></dt>
+<dt><span class="sig-name descname"><span class="pre">choices</span></span></dt>
-<dd><p>This attribute is optional when the form field does not have a
+<dd><p>当表单字段没有 <code>choices</code> 属性时，此属性是可选的。 如果是，它会在 [[../fields#django.forms|Field]] 上更新属性时覆盖您在此处设置的任何内容。</p></dd></dl>
-<code>choices</code> attribute. If it does, it will override anything you set
-here when the attribute is updated on the [[../fields#django.forms|<code>Field</code>]].</p></dd></dl>
 </dd></dl>
@@ 第832行： / 第682行： @@
 <div id="nullbooleanselect" class="section">
-==== <code>NullBooleanSelect</code> ====
+==== NullBooleanSelect ====
 <dl>
-<dt>''class'' <code>NullBooleanSelect</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">NullBooleanSelect</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/select.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/select.html'</code></p></li>
-<li><p><code>option_template_name</code>: <code>'django/forms/widgets/select_option.html'</code></p></li></ul>
+<li><p><code>option_template_name</code>：<code>'django/forms/widgets/select_option.html'</code></p></li></ul>
-<p>Select widget with options 'Unknown', 'Yes' and 'No'</p></dd></dl>
+<p>选择带有“未知”、“是”和“否”选项的小部件</p></dd></dl>
@@ 第846行： / 第696行： @@
 <div id="selectmultiple" class="section">
-==== <code>SelectMultiple</code> ====
+==== SelectMultiple ====
 <dl>
-<dt>''class'' <code>SelectMultiple</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">SelectMultiple</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/select.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/select.html'</code></p></li>
-<li><p><code>option_template_name</code>: <code>'django/forms/widgets/select_option.html'</code></p></li></ul>
+<li><p><code>option_template_name</code>：<code>'django/forms/widgets/select_option.html'</code></p></li></ul>
-<p>Similar to [[#django.forms.Select|<code>Select</code>]], but allows multiple selection:
+<p>类似于 [[#django.forms.Select|Select]]，但允许多选：<code>&lt;select multiple&gt;...&lt;/select&gt;</code></p></dd></dl>
-<code>&lt;select multiple&gt;...&lt;/select&gt;</code></p></dd></dl>
@@ 第861行： / 第710行： @@
 <div id="radioselect" class="section">
-==== <code>RadioSelect</code> ====
+==== RadioSelect ====
 <dl>
-<dt>''class'' <code>RadioSelect</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">RadioSelect</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/radio.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/radio.html'</code></p></li>
-<li><p><code>option_template_name</code>: <code>'django/forms/widgets/radio_option.html'</code></p></li></ul>
+<li><p><code>option_template_name</code>：<code>'django/forms/widgets/radio_option.html'</code></p></li></ul>
-<p>Similar to [[#django.forms.Select|<code>Select</code>]], but rendered as a list of radio buttons within
+<p>类似于 [[#django.forms.Select|Select]]，但呈现为 <code>&lt;li&gt;</code> 标签内的单选按钮列表：</p>
-<code>&lt;li&gt;</code> tags:</p>
 <div class="highlight-html notranslate">
 <div class="highlight">
-<pre>&lt;ul&gt;
+<syntaxhighlight lang="html"><ul>
-   &lt;li&gt;&lt;input type=&quot;radio&quot; name=&quot;...&quot;&gt;&lt;/li&gt;
+   <li><input type="radio" name="..."></li>
    ...
-&lt;/ul&gt;</pre>
+</ul></syntaxhighlight>
 </div>
 </div>
-<p>For more granular control over the generated markup, you can loop over the
+<p>要对生成的标记进行更精细的控制，您可以在模板中的单选按钮上循环。 假设表单 <code>myform</code> 的字段 <code>beatles</code> 使用 <code>RadioSelect</code> 作为其小部件：</p>
-radio buttons in the template. Assuming a form <code>myform</code> with a field
-<code>beatles</code> that uses a <code>RadioSelect</code> as its widget:</p>
 <div class="highlight-html+django notranslate">
 <div class="highlight">
-<pre>{% for radio in myform.beatles %}
+<syntaxhighlight lang="html+django">{% for radio in myform.beatles %}
-&lt;div class=&quot;myradio&quot;&gt;
+<div class="myradio">
      {{ radio }}
-&lt;/div&gt;
+</div>
-{% endfor %}</pre>
+{% endfor %}</syntaxhighlight>
 </div>
 </div>
-<p>This would generate the following HTML:</p>
+<p>这将生成以下 HTML：</p>
 <div class="highlight-html notranslate">
 <div class="highlight">
-<pre>&lt;div class=&quot;myradio&quot;&gt;
+<syntaxhighlight lang="html"><div class="myradio">
-     &lt;label for=&quot;id_beatles_0&quot;&gt;&lt;input id=&quot;id_beatles_0&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;john&quot; required&gt; John&lt;/label&gt;
+     <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
-&lt;/div&gt;
+</div>
-&lt;div class=&quot;myradio&quot;&gt;
+<div class="myradio">
-     &lt;label for=&quot;id_beatles_1&quot;&gt;&lt;input id=&quot;id_beatles_1&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;paul&quot; required&gt; Paul&lt;/label&gt;
+     <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
-&lt;/div&gt;
+</div>
-&lt;div class=&quot;myradio&quot;&gt;
+<div class="myradio">
-     &lt;label for=&quot;id_beatles_2&quot;&gt;&lt;input id=&quot;id_beatles_2&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;george&quot; required&gt; George&lt;/label&gt;
+     <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
-&lt;/div&gt;
+</div>
-&lt;div class=&quot;myradio&quot;&gt;
+<div class="myradio">
-     &lt;label for=&quot;id_beatles_3&quot;&gt;&lt;input id=&quot;id_beatles_3&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;ringo&quot; required&gt; Ringo&lt;/label&gt;
+     <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
-&lt;/div&gt;</pre>
+</div></syntaxhighlight>
 </div>
 </div>
-<p>That included the <code>&lt;label&gt;</code> tags. To get more granular, you can use each
+<p>其中包括 <code>&lt;label&gt;</code> 标签。 要获得更详细的信息，您可以使用每个单选按钮的 <code>tag</code>、<code>choice_label</code> 和 <code>id_for_label</code> 属性。 例如，这个模板…</p>
-radio button's <code>tag</code>, <code>choice_label</code> and <code>id_for_label</code> attributes.
-For example, this template...</p>
 <div class="highlight-html+django notranslate">
 <div class="highlight">
-<pre>{% for radio in myform.beatles %}
+<syntaxhighlight lang="html+django">{% for radio in myform.beatles %}
-     &lt;label for=&quot;{{ radio.id_for_label }}&quot;&gt;
+     <label for="{{ radio.id_for_label }}">
          {{ radio.choice_label }}
-         &lt;span class=&quot;radio&quot;&gt;{{ radio.tag }}&lt;/span&gt;
+         <span class="radio">{{ radio.tag }}</span>
-     &lt;/label&gt;
+     </label>
-{% endfor %}</pre>
+{% endfor %}</syntaxhighlight>
 </div>
 </div>
-<p>...will result in the following HTML:</p>
+<p>...将产生以下 HTML：</p>
 <div class="highlight-html notranslate">
 <div class="highlight">
-<pre>&lt;label for=&quot;id_beatles_0&quot;&gt;
+<syntaxhighlight lang="html"><label for="id_beatles_0">
      John
-     &lt;span class=&quot;radio&quot;&gt;&lt;input id=&quot;id_beatles_0&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;john&quot; required&gt;&lt;/span&gt;
+     <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
-&lt;/label&gt;
+</label>
-&lt;label for=&quot;id_beatles_1&quot;&gt;
+<label for="id_beatles_1">
      Paul
-     &lt;span class=&quot;radio&quot;&gt;&lt;input id=&quot;id_beatles_1&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;paul&quot; required&gt;&lt;/span&gt;
+     <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
-&lt;/label&gt;
+</label>
-&lt;label for=&quot;id_beatles_2&quot;&gt;
+<label for="id_beatles_2">
      George
-     &lt;span class=&quot;radio&quot;&gt;&lt;input id=&quot;id_beatles_2&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;george&quot; required&gt;&lt;/span&gt;
+     <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
-&lt;/label&gt;
+</label>
-&lt;label for=&quot;id_beatles_3&quot;&gt;
+<label for="id_beatles_3">
      Ringo
-     &lt;span class=&quot;radio&quot;&gt;&lt;input id=&quot;id_beatles_3&quot; name=&quot;beatles&quot; type=&quot;radio&quot; value=&quot;ringo&quot; required&gt;&lt;/span&gt;
+     <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
-&lt;/label&gt;</pre>
+</label></syntaxhighlight>
 </div>
 </div>
-<p>If you decide not to loop over the radio buttons -- e.g., if your template
+<p>如果您决定不循环使用单选按钮——例如，如果您的模板包含 <code>{{ myform.beatles }}</code>——它们将在带有 <code>&lt;li&gt;</code> 标签的 <code>&lt;ul&gt;</code> 中输出，如上所述。</p>
-includes <code>{{ myform.beatles }}</code> -- they'll be output in a <code>&lt;ul&gt;</code> with
+<p>外部 <code>&lt;ul&gt;</code> 容器接收小部件的 <code>id</code> 属性（如果已定义），否则接收 [[../api#django.forms.BoundField|BoundField.auto_id]]。</p>
-<code>&lt;li&gt;</code> tags, as above.</p>
+<p>在单选按钮上循环时，<code>label</code> 和 <code>input</code> 标签分别包含 <code>for</code> 和 <code>id</code> 属性。 每个单选按钮都有一个 <code>id_for_label</code> 属性来输出元素的 ID。</p></dd></dl>
-<p>The outer <code>&lt;ul&gt;</code> container receives the <code>id</code> attribute of the widget,
-if defined, or [[../api#django.forms.BoundField|<code>BoundField.auto_id</code>]] otherwise.</p>
-<p>When looping over the radio buttons, the <code>label</code> and <code>input</code> tags include
-<code>for</code> and <code>id</code> attributes, respectively. Each radio button has an
-<code>id_for_label</code> attribute to output the element's ID.</p></dd></dl>
@@ 第978行： / 第817行： @@
 <div id="checkboxselectmultiple" class="section">
-==== <code>CheckboxSelectMultiple</code> ====
+==== CheckboxSelectMultiple ====
 <dl>
-<dt>''class'' <code>CheckboxSelectMultiple</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">CheckboxSelectMultiple</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/checkbox_select.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/checkbox_select.html'</code></p></li>
-<li><p><code>option_template_name</code>: <code>'django/forms/widgets/checkbox_option.html'</code></p></li></ul>
+<li><p><code>option_template_name</code>：<code>'django/forms/widgets/checkbox_option.html'</code></p></li></ul>
-<p>Similar to [[#django.forms.SelectMultiple|<code>SelectMultiple</code>]], but rendered as a list of checkboxes:</p>
+<p>类似于 [[#django.forms.SelectMultiple|SelectMultiple]]，但呈现为复选框列表：</p>
 <div class="highlight-html notranslate">
 <div class="highlight">
-<pre>&lt;ul&gt;
+<syntaxhighlight lang="html"><ul>
-   &lt;li&gt;&lt;input type=&quot;checkbox&quot; name=&quot;...&quot; &gt;&lt;/li&gt;
+   <li><input type="checkbox" name="..." ></li>
    ...
-&lt;/ul&gt;</pre>
+</ul></syntaxhighlight>
 </div>
 </div>
-<p>The outer <code>&lt;ul&gt;</code> container receives the <code>id</code> attribute of the widget,
+<p>外部 <code>&lt;ul&gt;</code> 容器接收小部件的 <code>id</code> 属性（如果已定义），否则接收 [[../api#django.forms.BoundField|BoundField.auto_id]]。</p></dd></dl>
-if defined, or [[../api#django.forms.BoundField|<code>BoundField.auto_id</code>]] otherwise.</p></dd></dl>
-Like [[#django.forms.RadioSelect|<code>RadioSelect</code>]], you can loop over the individual checkboxes for the
+与 [[#django.forms.RadioSelect|RadioSelect]] 一样，您可以遍历小部件选项的各个复选框。 与 [[#django.forms.RadioSelect|RadioSelect]] 不同，如果该字段是必需的，则复选框将不包含 <code>required</code> HTML 属性，因为浏览器验证将要求选中所有复选框，而不是至少选中一个。
-widget's choices. Unlike [[#django.forms.RadioSelect|<code>RadioSelect</code>]], the checkboxes won't include the
-<code>required</code> HTML attribute if the field is required because browser validation
-would require all checkboxes to be checked instead of at least one.
-When looping over the checkboxes, the <code>label</code> and <code>input</code> tags include
+当循环复选框时，<code>label</code> 和 <code>input</code> 标签分别包含 <code>for</code> 和 <code>id</code> 属性。 每个复选框都有一个 <code>id_for_label</code> 属性来输出元素的 ID。
-<code>for</code> and <code>id</code> attributes, respectively. Each checkbox has an
-<code>id_for_label</code> attribute to output the element's ID.
@@ 第1,017行： / 第850行： @@
 <div id="file-upload-widgets" class="section">
-<span id="id5"></span>
+<span id="id13"></span>
-=== File upload widgets ===
+=== 文件上传小工具 ===
 <div id="fileinput" class="section">
-==== <code>FileInput</code> ====
+==== FileInput ====
-; ''class'' <code>FileInput</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">FileInput</span></span>
-: ;* <code>template_name</code>: <code>'django/forms/widgets/file.html'</code>
+: ;* <code>template_name</code>：<code>'django/forms/widgets/file.html'</code>
-;* Renders as: <code>&lt;input type=&quot;file&quot; ...&gt;</code>
+;* 呈现为：<code>&lt;input type=&quot;file&quot; ...&gt;</code>
@@ 第1,032行： / 第865行： @@
 <div id="clearablefileinput" class="section">
-==== <code>ClearableFileInput</code> ====
+==== ClearableFileInput ====
-; ''class'' <code>ClearableFileInput</code>
+; ''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">ClearableFileInput</span></span>
-: ;* <code>template_name</code>: <code>'django/forms/widgets/clearable_file_input.html'</code>
+: ;* <code>template_name</code>：<code>'django/forms/widgets/clearable_file_input.html'</code>
-;* Renders as: <code>&lt;input type=&quot;file&quot; ...&gt;</code> with an additional checkbox input to clear the field's value, if the field is not required and has initial data.
+;* 呈现为：<code>&lt;input type=&quot;file&quot; ...&gt;</code> 带有额外的复选框输入以清除该字段的值，如果该字段不是必需的并且具有初始数据。
@@ 第1,044行： / 第877行： @@
 <div id="composite-widgets" class="section">
-<span id="id6"></span>
+<span id="id14"></span>
-=== Composite widgets ===
+=== 复合小部件 ===
 <div id="multiplehiddeninput" class="section">
-==== <code>MultipleHiddenInput</code> ====
+==== MultipleHiddenInput ====
 <dl>
-<dt>''class'' <code>MultipleHiddenInput</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">MultipleHiddenInput</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/multiple_hidden.html'</code></p></li>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/multiple_hidden.html'</code></p></li>
-<li><p>Renders as: multiple <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> tags</p></li></ul>
+<li><p>呈现为：多个 <code>&lt;input type=&quot;hidden&quot; ...&gt;</code> 标签</p></li></ul>
-<p>A widget that handles multiple hidden widgets for fields that have a list
+<p>处理具有值列表的字段的多个隐藏小部件的小部件。</p></dd></dl>
-of values.</p></dd></dl>
@@ 第1,064行： / 第896行： @@
 <div id="splitdatetimewidget" class="section">
-==== <code>SplitDateTimeWidget</code> ====
+==== SplitDateTimeWidget ====
 <dl>
-<dt>''class'' <code>SplitDateTimeWidget</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">SplitDateTimeWidget</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/splitdatetime.html'</code></p></li></ul>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/splitdatetime.html'</code></p></li></ul>
-<p>Wrapper (using [[#django.forms.MultiWidget|<code>MultiWidget</code>]]) around two widgets: [[#django.forms.DateInput|<code>DateInput</code>]]
+<p>包装器（使用 [[#django.forms.MultiWidget|MultiWidget]]）围绕两个小部件：[[#django.forms.DateInput|DateInput]] 表示日期，[[#django.forms.TimeInput|TimeInput]] 表示时间。 必须与 [[../fields#django.forms|SplitDateTimeField]] 而不是 [[../fields#django.forms|DateTimeField]] 一起使用。</p>
-for the date, and [[#django.forms.TimeInput|<code>TimeInput</code>]] for the time. Must be used with
+<p><code>SplitDateTimeWidget</code> 有几个可选参数：</p>
-[[../fields#django.forms|<code>SplitDateTimeField</code>]] rather than [[../fields#django.forms|<code>DateTimeField</code>]].</p>
-<p><code>SplitDateTimeWidget</code> has several optional arguments:</p>
 <dl>
-<dt><code>date_format</code></dt>
+<dt><span class="sig-name descname"><span class="pre">date_format</span></span></dt>
-<dd><p>Similar to [[#django.forms.DateInput.format|<code>DateInput.format</code>]]</p></dd></dl>
+<dd><p>类似于 [[#django.forms.DateInput.format|DateInput.format]]</p></dd></dl>
 <dl>
-<dt><code>time_format</code></dt>
+<dt><span class="sig-name descname"><span class="pre">time_format</span></span></dt>
-<dd><p>Similar to [[#django.forms.TimeInput.format|<code>TimeInput.format</code>]]</p></dd></dl>
+<dd><p>类似于 [[#django.forms.TimeInput.format|TimeInput.format]]</p></dd></dl>
 <dl>
-<dt><code>date_attrs</code></dt>
+<dt><span class="sig-name descname"><span class="pre">date_attrs</span></span></dt>
 <dd></dd></dl>
 <dl>
-<dt><code>time_attrs</code></dt>
+<dt><span class="sig-name descname"><span class="pre">time_attrs</span></span></dt>
-<dd><p>Similar to [[#django.forms.Widget.attrs|<code>Widget.attrs</code>]]. A dictionary containing HTML
+<dd><p>类似于 [[#django.forms.Widget.attrs|Widget.attrs]]。 包含要分别在呈现的 [[#django.forms.DateInput|DateInput]] 和 [[#django.forms.TimeInput|TimeInput]] 小部件上设置的 HTML 属性的字典。 如果未设置这些属性，则使用 [[#django.forms.Widget.attrs|Widget.attrs]] 代替。</p></dd></dl>
-attributes to be set on the rendered [[#django.forms.DateInput|<code>DateInput</code>]] and
-[[#django.forms.TimeInput|<code>TimeInput</code>]] widgets, respectively. If these attributes aren't
-set, [[#django.forms.Widget.attrs|<code>Widget.attrs</code>]] is used instead.</p></dd></dl>
 </dd></dl>
@@ 第1,099行： / 第926行： @@
 <div id="splithiddendatetimewidget" class="section">
-==== <code>SplitHiddenDateTimeWidget</code> ====
+==== SplitHiddenDateTimeWidget ====
 <dl>
-<dt>''class'' <code>SplitHiddenDateTimeWidget</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">SplitHiddenDateTimeWidget</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/splithiddendatetime.html'</code></p></li></ul>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/splithiddendatetime.html'</code></p></li></ul>
-<p>Similar to [[#django.forms.SplitDateTimeWidget|<code>SplitDateTimeWidget</code>]], but uses [[#django.forms.HiddenInput|<code>HiddenInput</code>]] for
+<p>类似于 [[#django.forms.SplitDateTimeWidget|SplitDateTimeWidget]]，但使用 [[#django.forms.HiddenInput|HiddenInput]] 作为日期和时间。</p></dd></dl>
-both date and time.</p></dd></dl>
@@ 第1,113行： / 第939行： @@
 <div id="selectdatewidget" class="section">
-==== <code>SelectDateWidget</code> ====
+==== SelectDateWidget ====
 <dl>
-<dt>''class'' <code>SelectDateWidget</code></dt>
+<dt>''<span class="pre">class</span>'' <span class="sig-name descname"><span class="pre">SelectDateWidget</span></span></dt>
 <dd><ul>
-<li><p><code>template_name</code>: <code>'django/forms/widgets/select_date.html'</code></p></li></ul>
+<li><p><code>template_name</code>：<code>'django/forms/widgets/select_date.html'</code></p></li></ul>
-<p>Wrapper around three [[#django.forms.Select|<code>Select</code>]] widgets: one each for
+<p>环绕三个 [[#django.forms.Select|Select]] 小部件：每个月、日和年各一个。</p>
-month, day, and year.</p>
+<p>采用几个可选参数：</p>
-<p>Takes several optional arguments:</p>
 <dl>
-<dt><code>years</code></dt>
+<dt><span class="sig-name descname"><span class="pre">years</span></span></dt>
-<dd><p>An optional list/tuple of years to use in the &quot;year&quot; select box.
+<dd><p>在“年份”选择框中使用的可选年份列表/元组。 默认值为包含当前年份和未来 9 年的列表。</p></dd></dl>
-The default is a list containing the current year and the next 9 years.</p></dd></dl>
 <dl>
-<dt><code>months</code></dt>
+<dt><span class="sig-name descname"><span class="pre">months</span></span></dt>
-<dd><p>An optional dict of months to use in the &quot;months&quot; select box.</p>
+<dd><p>在“月份”选择框中使用的可选月份字典。</p>
-<p>The keys of the dict correspond to the month number (1-indexed) and
+<p>dict 的键对应于月份编号（1-indexed），值是显示的月份：</p>
-the values are the displayed months:</p>
 <div class="highlight-default notranslate">
 <div class="highlight">
-<pre>MONTHS = {
+<syntaxhighlight lang="python">MONTHS = {
 :_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
 :_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
 :_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec')
-}</pre>
+}</syntaxhighlight>
 </div>
@@ 第1,148行： / 第971行： @@
 <dl>
-<dt><code>empty_label</code></dt>
+<dt><span class="sig-name descname"><span class="pre">empty_label</span></span></dt>
-<dd><p>If the [[../fields#django.forms|<code>DateField</code>]] is not required,
+<dd><p>如果不需要 [[../fields#django.forms|DateField]]，则 [[#django.forms.SelectDateWidget|SelectDateWidget]] 将在列表顶部有一个空选项（默认为 <code>---</code>）。 您可以使用 <code>empty_label</code> 属性更改此标签的文本。 <code>empty_label</code> 可以是 <code>string</code>、<code>list</code> 或 <code>tuple</code>。 使用字符串时，所有选择框都会有一个带有此标签的空选项。 如果 <code>empty_label</code> 是 3 个字符串元素的 <code>list</code> 或 <code>tuple</code>，选择框将有自己的自定义标签。 标签应按此顺序 <code>('year_label', 'month_label', 'day_label')</code>。</p>
-[[#django.forms.SelectDateWidget|<code>SelectDateWidget</code>]] will have an empty choice at the top of the
-list (which is <code>---</code> by default). You can change the text of this
-label with the <code>empty_label</code> attribute. <code>empty_label</code> can be a
-<code>string</code>, <code>list</code>, or <code>tuple</code>. When a string is used, all select
-boxes will each have an empty choice with this label. If <code>empty_label</code>
-is a <code>list</code> or <code>tuple</code> of 3 string elements, the select boxes will
-have their own custom label. The labels should be in this order
-<code>('year_label', 'month_label', 'day_label')</code>.</p>
 <div class="highlight-python notranslate">
 <div class="highlight">
-<pre># A custom empty label with string
+<syntaxhighlight lang="python"># A custom empty label with string
-field1 = forms.DateField(widget=SelectDateWidget(empty_label=&quot;Nothing&quot;))
+field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))
 # A custom empty label with tuple
 field1 = forms.DateField(
      widget=SelectDateWidget(
-         empty_label=(&quot;Choose Year&quot;, &quot;Choose Month&quot;, &quot;Choose Day&quot;),
+         empty_label=("Choose Year", "Choose Month", "Choose Day"),
      ),
-)</pre>
+)</syntaxhighlight>
 </div>
@@ 第1,183行： / 第998行： @@
 </div>
+</div>
+<div class="clearer">
 </div>
-[[Category:Django 3.1.x 中文文档]]
+[[Category:Django 3.1.x 文档]]