--- title: "部件" version: 6.0 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/6.0/ref/forms/widgets/ canonical: https://djangodocs.dev/zh-hans/6.0/ref/forms/widgets/ --- # 部件 部件是 Django 对 HTML 输入元素的表示。部件处理 HTML 的渲染，以及从对应于部件的 GET／POST 字典中提取数据。 内置部件生成的 HTML 使用 HTML5 语法，目标是 ``。例如，它使用布尔属性，如 `checked` 而不是 XHTML 风格的 `checked='checked'`。 > **Tip** > > 部件不应该与 [表单字段](/zh-hans/6.0/ref/forms/fields/) 混淆。表单字段处理输入验证的逻辑，直接在模板中使用。小组件处理 HTML 表单输入元素在网页上的渲染和原始提交数据的提取。然而，部件确实需要 [分配](#widget-to-field) 到表单字段。 ## 指定部件 每当你在表单中指定一个字段时，Django 会使用一个默认的部件来显示数据类型。要想知道哪个字段使用的是哪个部件，请看 [内置 Field 类](/zh-hans/6.0/ref/forms/fields/#built-in-fields) 的文档。 但是，如果你想为一个字段使用不同的部件，你可以在字段定义中使用 [`widget`](/zh-hans/6.0/ref/forms/fields/#django.forms.Field.widget) 参数。例如： ``` from django import forms class CommentForm(forms.Form): name = forms.CharField() url = forms.URLField() comment = forms.CharField(widget=forms.Textarea) ``` 这将指定一个带有注释的表单，该表单使用一个较大的 [`Textarea`](#django.forms.Textarea) 部件，而不是默认的 [`TextInput`](#django.forms.TextInput) 部件。 ## 为部件设置参数 许多部件都有可选的额外参数；它们可以在字段上定义部件时进行设置。在下面的例子中， [`years`](#django.forms.SelectDateWidget.years) 属性被设置为 [`SelectDateWidget`](#django.forms.SelectDateWidget)： ``` 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, ) ``` 请参阅 [内置部件](#built-in-widgets)，了解更多关于哪些部件可用以及它们接受哪些参数的信息。 ## 自定义部件实例 当 Django 将一个部件渲染成 HTML 时，它只渲染了非常少的标记——Django 不会添加类名，或任何其他部件的特定属性。这意味着，例如，所有的 [`TextInput`](#django.forms.TextInput) 部件在你的网页上看起来都是一样的。 有两种方法来定制部件： [每个部件实例](#styling-widget-instances) 和 [每个部件类](#styling-widget-classes)。 ### 样式化部件实例 如果你想让一个部件实例看起来与另一个不同，你需要在实例化部件对象并将其分配给表单字段时指定额外的属性（也许还需要在你的 CSS 文件中添加一些规则）。 例如，采取以下表单： ``` from django import forms class CommentForm(forms.Form): name = forms.CharField() url = forms.URLField() comment = forms.CharField() ``` 此表单将包括用于 name 和 comment 字段的 [`TextInput`](#django.forms.TextInput) 小部件，以及用于 url 字段的 [`URLInput`](#django.forms.URLInput) 小部件。每个都有默认的渲染 —— 没有 CSS 类，没有额外的属性： ```pycon >>> f = CommentForm(auto_id=False) >>> print(f)
Name:
Url:
Comment:
``` 在真实的网页上，你可能想要自定义这些。你可能希望评论的输入元素更大，并且你可能希望 'name' 小部件具有一些特殊的 CSS 类。还可以指定 'type' 属性以使用不同的 HTML5 输入类型。为此，你可以在创建小部件时使用 [`Widget.attrs`](#django.forms.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`](/zh-hans/6.0/ref/forms/api/#django.forms.Form.fields) 属性： ``` class CommentForm(forms.ModelForm): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.fields["name"].widget.attrs.update({"class": "special"}) self.fields["comment"].widget.attrs.update(size="40") ``` Django 会将额外的属性包含在渲染的输出中： ``` >>> f = CommentForm(auto_id=False) >>> print(f)
Name:
Url:
Comment:
``` 你也可以使用 [`attrs`](#django.forms.Widget.attrs) 设置 HTML `id`。参见 [`BoundField.id_for_label`](/zh-hans/6.0/ref/forms/api/#django.forms.BoundField.id_for_label) 的例子。 ### 样式化部件类 有了部件，就可以添加静态资源（`css` 和 `javascript`）并更深入地定制它们的外观和行为。 简而言之，你需要对部件进行子类化，并且 [定义一个内部“Media”类](/zh-hans/6.0/topics/forms/media/#assets-as-a-static-definition) 或者 [创建一个"media"属性](/zh-hans/6.0/topics/forms/media/#dynamic-property)。 这些方法涉及到一些高级的 Python 编程，在 [表单静态资源](/zh-hans/6.0/topics/forms/media/) 主题指南中有详细描述。 ## 基础部件类 基础部件类 [`Widget`](#django.forms.Widget) 和 [`MultiWidget`](#django.forms.MultiWidget) 被所有的 [内置部件](#built-in-widgets) 子类化，可以作为自定义部件的基础。 ### `Widget` #### `class Widget(attrs=None)` This abstract class cannot be rendered, but provides the basic attribute [`attrs`](#django.forms.Widget.attrs). You may also implement or override the [`render()`](#django.forms.Widget.render) method on custom widgets. #### `attrs` 包含要在渲染的部件上设置的 HTML 属性的字典。 ```pycon >>> from django import forms >>> name = forms.TextInput(attrs={"size": 10, "title": "Your name"}) >>> name.render("name", "A name") '' ``` 如果你将属性赋值为 `True` 或 `False`，它将被渲染为 HTML5 的布尔属性： ```pycon >>> 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`](https://docs.python.org/3/library/datetime.html#datetime.datetime) 和 [`time`](https://docs.python.org/3/library/datetime.html#datetime.time) 值的微秒部分将被设置为 `0`。 #### `format_value(value)` 清理并返回一个值，供部件模板使用。`value` 并不能保证是有效的输入，因此子类的实现应该是防御性的。 #### `get_context(name, value, attrs)` 返回渲染部件模板时要使用的值的字典。默认情况下，该字典包含一个键，`'widget'`，它是一个包含以下键的部件的字典表示： - `'name'`：`name` 参数中的字段名称。 - `'is_hidden'`：表示该部件是否被隐藏的布尔值。 - `'required'`：表示该部件是否需要该字段的布尔值。 - `'value'`：[`format_value()`](#django.forms.Widget.format_value) 返回的值。 - `'attrs'`：拟在渲染的部件上设置的 HTML 属性。[`attrs`](#django.forms.Widget.attrs) 属性和 `attrs` 参数的组合。 - `''template_name'`：`self.template_name` 的值。 `Widget` 子类可以通过覆盖该方法提供自定义上下文值。 #### `id_for_label(id_)` 根据字段的 ID 返回此小部件的 HTML ID 属性，供 `