--- title: "ウィジェット" version: 5.2 locale: ja source: https://docs.djangoproject.com/ja/5.2/ref/forms/widgets/ canonical: https://djangodocs.dev/ja/5.2/ref/forms/widgets/ --- # ウィジェット ウィジェットは、Django が HTML の input 要素の表現方法です。ウィジェットは、HTML のレンダリングをコントロールして、ウィジェットに合致する GET/POST ディクショナリからデータを取り出します。 Built-in widgets によって作られる HTML は、`` を対象とした HTML5 シンタックスを使います。たとえば、XHTML スタイルである `checked='checked'` よりも、`checked` といった boolean 属性を使います。 > **Tip** > > ウィジェットを [フォームフィールド](/ja/5.2/ref/forms/fields/) と混同しないでください。フォームフィールドは入力値の検証ロジックを扱い、テンプレート内で直接使用されます。ウィジェットはウェブページ上で input 要素から HTML の form をレンダリングし、submit された生データを取り出します。ウィジェットはフォームフィールドにアサイン ([assigned](#widget-to-field)) される必要があります。 ## ウィジェットを指定する フォーム上でフィールドを指定したときは、Django は描画されるデータのタイプに適したデフォルトのウィジェットを使用します。各フィールドで使われるウィジェットを調べるためには、 [ビルトインの Field クラス](/ja/5.2/ref/forms/fields/#built-in-fields) を参照してください。 しかし、フィールドに別のウィジェットを使用したい場合は、フィールド定義で [`widget`](/ja/5.2/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) ``` これは、comment のフォームに対して、デフォルトの [`TextInput`](#django.forms.TextInput) ウィジェットではなく、より大きなサイズの [`Textarea`](#django.forms.Textarea) ウィジェットを指定しています。 ## ウィジェットの引数を設定する 多くのウィジェットは、省略可能な追加の引数を持っています; これらは、フィールド上でウィジェットを定義する際にセットできます。以下の例では、[`SelectDateWidget`](#django.forms.SelectDateWidget) に対して [`years`](#django.forms.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, ) ``` 使用可能なウィジェットとそれぞれの引数の詳細については、[ビルトインのウィジェット](#built-in-widgets) を参照してください。 ## `Select` ウィジェットを継承したウィジェット [`Select`](#django.forms.Select) ウィジェットを継承したウィジェットは、選択肢を扱います。これらはユーザーに選択肢のリストを提示します。提示される選択肢はウィジェットによって異なります; [`Select`](#django.forms.Select) ウィジェット自体は、`
Url:
Comment:
``` 実際のウェブページでは、おそらくこれをカスタマイズしたいでしょう。コメント用には大きな入力要素を、名前用のウィジェットには特別な CSS クラスを指定したいかもしれません。また、HTML5 の異なる入力タイプを使用するために、 'type' 属性を指定することも可能です。これを行うには、ウィジェットを作成する際に [`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`](/ja/5.2/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`](/ja/5.2/ref/forms/api/#django.forms.BoundField.id_for_label) で例を参照してください。 ### ウィジェットのクラスにスタイルを設定する ウィジェットとともに、アセット (`css` や `javascript`) 、およびより詳細にカスタマイズされた見た目や動作を追加できます。 要するに、ウィジェットをサブクラス化して、 ["Media" 内部クラスの定義](/ja/5.2/topics/forms/media/#assets-as-a-static-definition) か ["media" プロパティの作成](/ja/5.2/topics/forms/media/#dynamic-property) のどちらかをする必要があります。 これらのメソッドにはやや高度なPythonプログラミングが含まれており、トピックガイド [フォームアセット](/ja/5.2/topics/forms/media/) で詳しく説明しています。 ## ウィジェットの base クラス [`Widget`](#django.forms.Widget) や [`MultiWidget`](#django.forms.MultiWidget) といった基本ウィジェットは、[ビルトインのウィジェット](#built-in-widgets) によってサブクラス化され、カスタムウィジェットのための基礎となります。 ### `ウィジェット` #### `class Widget(attrs=None)` この抽象クラスはレンダリングできませんが、基本的な属性 [`attrs`](#django.forms.Widget.attrs) を提供します。カスタムウィジェット上で [`render()`](#django.forms.Widget.render) を実行するかオーバーライドできます。 #### `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_)` このウィジェットのHTML ID属性を返します。これは、フィールドのIDをもとにして `