Виджеты

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

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

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

from django import forms


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

В этой форме для полей имени и комментария будут использоваться виджеты TextInput, а для поля URL — виджет URLInput. Для каждого используется стандартное представление — без класса 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")

Если поле не объявлено непосредственно в форме (например, если это поле ModelForm), можно использовать атрибут 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) [исходный код]

Этот абстрактный класс нельзя отобразить, но он предоставляет базовый атрибут 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_) [исходный код]

Возвращает HTML-атрибут ID этого виджета для использования в <label> с учетом ID поля. Если ID недоступен, возвращается пустая строка.

Этот метод необходим, поскольку некоторые виджеты содержат несколько HTML-элементов и, следовательно, несколько идентификаторов. В таком случае этот метод должен возвращать значение ID, соответствующее первому идентификатору в тегах виджета.

render(name, value, attrs=None, renderer=None) [исходный код]

Преобразует виджет в HTML с помощью указанного средства отображения. Если renderer равен None, используется средство отображения из настройки FORM_RENDERER.

value_from_datadict(data, files, name) [исходный код]

Получив словарь данных и имя этого виджета, возвращает его значение. files может содержать данные из request.FILES. Если значение не было передано, возвращается None. Также обратите внимание: value_from_datadict может вызываться несколько раз при обработке данных формы. Поэтому, если вы переопределяете этот метод и добавляете затратную обработку, механизм кеширования нужно реализовать самостоятельно.

value_omitted_from_data(data, files, name) [исходный код]

Получив словари data и files и имя этого виджета, возвращает признак наличия данных или файлов для виджета.

Результат этого метода влияет на то, будет ли поле ModelForm использовать значение по умолчанию.

Особые случаи — CheckboxInput, CheckboxSelectMultiple и SelectMultiple: они всегда возвращают False, поскольку неотмеченный флажок и невыбранный элемент <select multiple> не попадают в данные отправленной HTML-формы, поэтому нельзя определить, отправлял ли пользователь значение.

use_fieldset

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

use_required_attribute(initial) [исходный код]

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

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

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

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', описанному в 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>.

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

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