Виджеты¶

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

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

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

from django import forms


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

Эта форма будет содержать три стандартных виджета TextInput с рендерингом по умолчанию - без 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>

На реальной веб-странице вы, вероятно, не захотите, чтобы все виджеты выглядели одинаково. Возможно, вам понадобится более крупный элемент ввода для комментария, а виджет „name“ будет иметь какой-то особый 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) и более глубоко настраивать их внешний вид и поведение.

В двух словах, вам нужно будет создать подкласс виджета и либо define a «Media» inner class, либо create a «media» property.

Эти методы предполагают несколько продвинутое программирование на Python и подробно описаны в руководстве по теме Form Assets.

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

Результат метода влияет на то, является ли поле в форме модели falls back to its default.

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

use_fieldset¶

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

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

Учитывая значение initial поля формы, возвращает, может ли виджет быть отображен с атрибутом required HTML. Формы используют этот метод вместе с 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>.

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

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