Виджеты¶

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

Если вы хотите, чтобы один экземпляр виджета отличался от другого, вам нужно будет указать дополнительные атрибуты в момент инстанцирования объекта виджета и назначения его полю формы (и, возможно, добавить некоторые правила в ваши 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)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

На реальной веб-странице вы, вероятно, не захотите, чтобы все виджеты выглядели одинаково. Возможно, вам понадобится более крупный элемент ввода для комментария, а виджету „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)
>>> f.as_table()
<tr><th>Name:</th><td><input type="text" name="name" class="special" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" size="40" required></td></tr>

Вы также можете установить 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 поля. Возвращает None, если 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_required_attribute(initial)[исходный код]¶

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

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

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

Changed in Django 3.1:

В старых версиях True возвращалось для FileInput, когда было установлено initial.

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>.

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

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