Виджеты

Стиль экземпляров виджетов

Если вы хотите, чтобы один экземпляр виджета выглядел по-другому, вам нужно указать дополнительные атрибуты во время создания объекта виджета и присвоения его полю формы (и, возможно, добавить некоторые правила в ваши файлы CSS).

Например, рассмотрим следующую форму:

from django import forms


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

Эта форма будет включать виджеты TextInput для полей «Имя» и «Комментарий» и виджет URLInput для поля «url». Каждый из них имеет рендеринг по умолчанию — нет CSS класса, нет дополнительных атрибутов:

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

На реальной веб-странице вы, вероятно, захотите это настроить. Возможно, вы захотите больший элемент ввода для комментария, и, возможно, вы захотите, чтобы виджет «Имя» имел специальный CSS класс. Также возможно указать атрибут «type», чтобы использовать другой тип ввода HTML5. Для этого используйте аргумент Widget.attrs при создании виджета:

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

Вы также можете изменить виджет в определении формы:

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

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

Или, если поле не объявлено непосредственно в форме (например, поля формы модели), вы можете использовать атрибут Form.fields:

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

Django затем включит дополнительные атрибуты в рендерный вывод:

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

Вы также можете установить HTML id с помощью attrs. См. BoundField.id_for_label для примера.

Стиль классов виджетов

С виджетами можно добавить ресурсы (css и javascript) и более глубоко настроить их внешний вид и поведение.

Вкратце, вам нужно будет создать подкласс виджета и либо определить внутренний класс «Media», либо создать свойство «media».

Эти методы связаны со сравнительно сложным программированием на Python и подробно описаны в руководстве по теме Ресурсы форм.

Widget

class Widget(attrs=None) [source]

Этот абстрактный класс не может быть отображен, но предоставляет базовый атрибут attrs. Вы также можете реализовать или переопределить метод render() в пользовательских виджетах.

attrs

Словарь, содержащий HTML-атрибуты, которые нужно установить для отображаемого виджета.

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

Если вы присвоите значение True или False атрибуту, оно будет отображено как булевый атрибут HTML5:

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

supports_microseconds

Атрибут, который по умолчанию равен True. Если он установлен в False, часть микросекунд значений datetime и time будет установлена в 0.

format_value(value) [source]

Очищает и возвращает значение для использования во виджете шаблона. value не гарантируется, что будет допустимым вводом, поэтому подклассы должны реализовывать защитный код.

get_context(name, value, attrs) [source]

Возвращает словарь значений для использования при рендеринге шаблона виджета. По умолчанию словарь содержит единственный ключ, 'widget', который представляет собой представление виджета, содержащее следующие ключи:

• 'name': Имя поля из аргумента name.
• 'is_hidden': Логическое значение, указывающее, скрыт ли виджет.
• 'required': Логическое значение, указывающее, требуется ли поле для этого виджета.
• 'value': Значение, возвращаемое format_value().
• 'attrs': HTML-атрибуты, которые нужно установить для отображаемого виджета. Объединение атрибута attrs и аргумента attrs.
• 'template_name': Значение self.template_name.

Подклассы Widget могут предоставлять пользовательские значения контекста, переопределяя этот метод.

id_for_label(id_) [source]

Возвращает атрибут HTML ID этого виджета для использования <label>, учитывая 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, потому что неотмеченный флажок и невыбранный <select multiple> не отображаются в данных отправки HTML-формы, поэтому неизвестно, предоставил ли пользователь значение.

use_fieldset

Атрибут, определяющий, нужно ли группировать виджет в <fieldset> с <legend> при рендеринге. По умолчанию равен False, но равен True, когда виджет содержит несколько тегов <input>, таких как CheckboxSelectMultiple, RadioSelect, MultiWidget, SplitDateTimeWidget и SelectDateWidget.

use_required_attribute(initial) [source]

Учитывая значение initial поля формы, возвращает, может ли виджет быть отображён с атрибутом required HTML. Формы используют этот метод вместе с Field.required и Form.use_required_attribute для определения, отображать ли атрибут required для каждого поля.

По умолчанию возвращает False для скрытых виджетов и True в противном случае. Особые случаи - FileInput и ClearableFileInput, которые возвращают False, если initial установлено, и CheckboxSelectMultiple, которое всегда возвращает False, потому что проверка браузера потребовала бы проверки всех флажков вместо хотя бы одного.

Переопределите этот метод в пользовательских виджетах, которые несовместимы с проверкой браузера. Например, виджет WYSIWYG-редактора текста, поддерживаемый скрытым элементом textarea, может всегда возвращать False, чтобы избежать проверки браузера для скрытого поля.

MultiWidget

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

Виджет, составленный из нескольких виджетов. MultiWidget работает в паре с MultiValueField.

MultiWidget имеет один обязательный аргумент:

widgets

Итерируемый объект, содержащий необходимые виджеты. Например:

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

Можно предоставить словарь для указания пользовательских суффиксов для атрибута name каждого подвиджета. В этом случае для каждой (key, widget) пары ключ будет добавлен к name виджета для генерации значения атрибута. Можно предоставить пустую строку ('') для единственного ключа, чтобы подавить суффикс для одного виджета. Например:

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

И один обязательный метод:

decompress(value) [source]

Этот метод принимает единственное «сжатое» значение из поля и возвращает список «расшифрованных» значений. Входное значение можно считать валидным, но не обязательно непустым.

Этот метод должен быть реализован подклассом, и поскольку значение может быть пустым, реализация должна быть защищённой.

Причина «расшифровки» заключается в необходимости «разделить» объединённое значение поля формы на значения для каждого виджета.

Пример — как SplitDateTimeWidget преобразует значение datetime в список с датой и временем, разделёнными на два отдельных значения:

from django.forms import MultiWidget


class SplitDateTimeWidget(MultiWidget):
    # ...

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

Подсказка

Обратите внимание, что MultiValueField имеет дополнительный метод compress() с обратной задачей — объединить очищенные значения всех полей-членов в одно.

Он предоставляет некоторый пользовательский контекст:

get_context(name, value, attrs) [source]

В дополнение к ключу 'widget', описанному в Widget.get_context(), 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 на значения дня, месяца и года, соответствующие каждому виджету. Если была выбрана недействительная дата, например, 30 февраля, DateField передаёт этому методу строку вместо этого, поэтому её необходимо разобрать. Конечный return обрабатывает случаи, когда value равно None, что означает, что у нас нет никаких значений по умолчанию для наших подвиджетов.

По умолчанию реализация value_from_datadict() возвращает список значений, соответствующих каждому Widget. Это подходит при использовании с MultiWidget и MultiValueField. Но так как мы хотим использовать этот виджет с DateField, которая принимает одно значение, мы переопределили этот метод. Реализация здесь объединяет данные из подвиджетов в строку в формате, ожидаемом DateField.

Виджеты для ввода текста

Эти виджеты используют HTML-элементы input и textarea.

Элементы управления выборами и флажками

Эти виджеты используют HTML-элементы <select>, <input type="checkbox"> и <input type="radio">.

Виджеты, отображающие несколько вариантов, имеют атрибут option_template_name, который определяет шаблон для отображения каждого варианта. Например, для виджета Select, select_option.html отображает <option> для <select>.

Виджеты загрузки файлов

Составные виджеты