Компоненты формы («виджеты») ¶

Добавление стилей к экземплярам компонентов ¶

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

Например, на примере этой формы

from django import forms

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

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

На реальной веб-странице часто желательно отображать компоненты по-другому. Для поля комментария может потребоваться большая область ввода, а компонент «имя» может быть дополнен определенным классом CSS. Также можно определить атрибут «тип», чтобы воспользоваться преимуществами новых типов компонентов 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 ) и дополнительно настраивать их внешний вид и поведение.

Говоря коротко, необходимо создать подкласс компонента и либо определить интернет-класс «Медиа», либо создать свойство «медиа» .

Эти методы предполагают относительно продвинутое использование программирования на Python и подробно описаны в тематическом руководстве файлов приложений к формам .

Widget ¶

classWidget ( 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 не обязательно является допустимой записью, поэтому реализации подклассов должны программироваться с защитой.

get_context( имя , значение , атрибуты ) ¶

Возвращает словарь значений для использования при отрисовке шаблонов компонентов. По умолчанию словарь содержит единственный ключ ,, '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( имя , значение , attrs = None , renderer = None ) ¶

Создает компонент в HTML с использованием данного средства визуализации. Если renderer - None используется настройка движка рендеринга FORM_RENDERER .

value_from_datadict( данные , файлы , имя ) ¶

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

value_omitted_from_data( данные , файлы , имя ) ¶

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

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

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

use_required_attribute( начальная ) ¶

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

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

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

Изменено в Django 3.1:

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

MultiWidget ¶

classMultiWidget ( 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', 'lennon'])
'<input type="text" name="name" value="john"><input type="text" name="name_last" value="paul">'

А также обязательный метод:

decompress( значение ) ¶

Этот метод принимает одно "сжатое" значение из поля и возвращает список "распакованных" значений. Введенное значение можно считать действительным, но может быть пустым.

Этот метод должен быть реализован подклассом, и поскольку значение может быть пустым, реализация должна быть защитной.

Логика «декомпрессии» заключается в том, что необходимо «разбить» объединенное значение поля формы на отдельные значения для каждого компонента.

Пример, иллюстрирующий этот процесс, - это 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( имя , значение , атрибуты ) ¶

В дополнение к ключу, 'widget' описанному в Widget.get_context() , MultiValueWidget добавьте ключ 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 заключительных обрабатывает случай значение 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> .

Компоненты отправки файлов ¶

Несколько компонентов ¶