部件

Widget

class Widget(attrs=None)[source]

This abstract class cannot be rendered, but provides the basic attribute attrs. You may also implement or override the render() method on custom widgets.

attrs

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

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

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

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

supports_microseconds

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

format_value(value)[source]

清理并返回一个值，供部件模板使用。value 并不能保证是有效的输入，因此子类的实现应该是防御性的。

get_context(name, value, attrs)[source]

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

• 'name'：name 参数中的字段名称。

• 'is_hidden'：表示该部件是否被隐藏的布尔值。

• 'required'：表示该部件是否需要该字段的布尔值。

• 'value'：format_value() 返回的值。

• 'attrs'：拟在渲染的部件上设置的 HTML 属性。attrs 属性和 attrs 参数的组合。

• ''template_name'：self.template_name 的值。

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

id_for_label(id_)[source]

根据字段的 ID 返回此小部件的 HTML ID 属性，供 使用。如果没有可用的 ID，则返回空字符串。

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

render(name, value, attrs=None, renderer=None)[source]

使用给定的渲染器将部件渲染成 HTML。如果 renderer 为 None，则使用 FORM_RENDERER 设置中的渲染器。

value_from_datadict(data, files, name)[source]

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

value_omitted_from_data(data, files, name)[source]

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

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

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

use_fieldset

一个用于标识小部件在渲染时是否应该分组在一个带有

的

中的属性。默认为 False，但当小部件包含多个 标签时，例如 CheckboxSelectMultiple、RadioSelect、MultiWidget、SplitDateTimeWidget 和 SelectDateWidget 时，它为 True。

use_required_attribute(initial)[source]

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

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

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

MultiWidget

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

MultiWidget 与 MultiValueField 携手合作。

MultiWidget 有一个必要的参数：

widgets

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

>>> from django.forms import MultiWidget, TextInput
>>> widget = MultiWidget(widgets=[TextInput, TextInput])
>>> widget.render("name", ["john", "paul"])
''

你可以提供一个字典来指定每个子小部件的 name 属性的自定义后缀。在这种情况下，对于每个 (key, widget) 对，将将 key 添加到小部件的 name 中以生成属性值。你可以为一个小部件提供空字符串（''），以取消一个小部件的后缀。例如：

>>> widget = MultiWidget(widgets={"": TextInput, "last": TextInput})
>>> widget.render("name", ["john", "paul"])
''

还有一个必要的方法：

decompress(value)[source]

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

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

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

一个例子是 SplitDateTimeWidget 如何将一个 datetime 值变成一个列表，将日期和时间分成两个独立的值：

from django.forms import MultiWidget

class SplitDateTimeWidget(MultiWidget):
    # ...

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

Tip

请注意 MultiValueField 有一个补充方法 compress()，其职责与之相反——将所有成员字段的清理值合并为一个。

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

get_context(name, value, attrs)[source]

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

这些可以在部件模板中循环使用：

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

下面是一个例子，它子类为 MultiWidget，用于在不同的选择框中显示日期和年、月、日。这个部件的目的是与 DateField 而不是 MultiValueField 一起使用，因此我们实现了 value_from_datadict()：

from datetime import date
from django import forms

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

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

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

构造函数在一个列表中创建了几个 Select 部件。super() 方法使用这个列表来建立部件。

所需的方法 decompress() 将一个 datetime.date 的值分解成对应于每个部件的日、月、年的值。如果选择了一个无效的日期，比如不存在的 2 月 30 日，那么 DateField 就会把这个方法传给一个字符串代替，所以需要进行解析。最后的 return 处理的是 value 是 None 的时候，也就是说我们的子部件没有任何默认值。

value_from_datadict() 的默认实现是返回一个与每个 Widget 对应的值列表。这在使用 MultiWidget 与 MultiValueField` 时是合适的。但由于我们想将这个部件与一个 DateField 一起使用，它只取一个值，我们已经覆盖了这个方法。这里的实现将来自子部件的数据组合成一个字符串，其格式为 DateField 所期望的格式。

处理文本输入的部件

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

选择器和复选框部件

这些部件使用了 HTML 元素 、 type="checkbox"> 和 type="radio">。

呈现多个选择的部件有一个 option_template_name 属性，指定用于渲染每个选择的模板。例如，对于 Select 部件，select_option.html 会为

渲染 。