Настройка экземпляров виджета¶

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

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

from django import forms

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

This form will include three default TextInput widgets, with default rendering – no CSS class, no extra attributes. This means that the input boxes provided for each widget will be rendered exactly the same:

>>> 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 добавит дополнительные атрибуты в генерируемый HTML код:

>>> 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) для более глубокой настройки их внешнего вида и поведения.

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

Эти методы требуют некоторого объёма продвинутого кода и подробно описаны в руководстве по ресурсам форм.

Виджеты¶

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">'

If you assign a value of True or False to an attribute, it will be rendered as an HTML5 boolean attribute:

>>> 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)¶

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

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 None if an ID isn’t available.

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

render(name, value, attrs=None, renderer=None)¶

Отрисовывает виджет в HTML, используя заданный модуль визуализации. Если рендерер имеет значение Нет, используется рендерер из настройки FORM_RENDERER.

value_from_datadict(data, files, name)¶

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

value_omitted_from_data(data, files, name)¶

Принимает словарь данных и имя виджета, возвращает значения для этого виджета. Возвращает None, если значение не предоставлено.

Результат метода влияет на то, вернется ли поле в форме модели к значению по умолчанию <topics-modelform-save>.

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

use_required_attribute(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:

In older versions, True was returned for FileInput when initial was set.

SelectDateWidget¶

class MultiWidget(widgets, attrs=None)¶

Виджет, который состоит из множества виджетов. Класс MultiWidget предназначен для поля MultiValueField.

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

widgets¶

An iterable containing the widgets needed. For example:

>>> 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">'

You may provide a dictionary in order to specify custom suffixes for the name attribute on each subwidget. In this case, for each (key, widget) pair, the key will be appended to the name of the widget in order to generate the attribute value. You may provide the empty string ('') for a single key, in order to suppress the suffix for one widget. For example:

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

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

Обязательный метод decompress() разбивает значение datetime.date на значение дня, месяца и года для каждого виджета. Следует отметить, что метод обрабатывает случай, когда value равно None.

Стандартная реализация метода value_from_datadict() возвращает список значений для каждого Widget. Это полезно при использовании MultiWidget совместно с MultiValueField, но так как мы желаем использовать этот виджет совместно с DateField, который принимает единственное значение, мы переопределили этот метод для соединения данных всех подчинённых виджетов в datetime.date. Метод получает данные из словаря POST, создаёт и проверяет дату. Если она проходит проверку, мы возвращаем строку, в противном случае возвращаем пустую строку, что заставляет form.is_valid вернуть False.

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

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

Виджеты выбора и отметки¶

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

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

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

Сложные виджеты¶