Виджеты¶

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

Если вы хотите, чтобы один экземпляр виджета отличался от другого, вам нужно будет указать дополнительные атрибуты в момент инстанцирования объекта виджета и назначения его полю формы (и, возможно, добавить некоторые правила в ваши 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>

On a real web page, you probably don’t want every widget to look the same. You might want a larger input element for the comment, and you might want the „name“ widget to have some special CSS class. It is also possible to specify the „type“ attribute to take advantage of the new HTML5 input types. To do this, you use the Widget.attrs argument when creating the widget:

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_)[исходный код]¶

Returns the HTML ID attribute of this widget for use by a <label>, given the ID of the field. Returns an empty string if an ID isn’t available.

Этот хук необходим, поскольку некоторые виджеты имеют несколько элементов 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¶

New in Django Development version.

Атрибут, определяющий, должен ли виджет быть сгруппирован в <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)[исходный код]¶

In addition to the 'widget' key described in Widget.get_context(), MultiWidget adds a widget['subwidgets'] key.

Их можно зациклить в шаблоне виджета:

{% 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)

The constructor creates several Select widgets in a list. The super() method uses this list to set up the widget.

Необходимый метод 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>.

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

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