Виджеты

Виджет — это представление Django для HTML-элемента ввода. Виджет обрабатывает рендеринг HTML и извлечение данных из словаря GET/POST, соответствующего виджету.

HTML, сгенерированный встроенными виджетами, использует синтаксис HTML5, ориентированный на <!DOCTYPE html>. Например, он использует булевы атрибуты, такие как checked, а не стиль XHTML checked='checked'.

Подсказка

Не следует путать виджеты с полями формы. Поля формы занимаются логикой валидации ввода и используются непосредственно в шаблонах. Виджеты занимаются рендерингом HTML-элементов ввода формы на веб-странице и извлечением сырых отправленных данных. Однако виджеты должны быть назначены полям формы.

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

Однако, если вы хотите использовать другой виджет для поля, вы можете использовать аргумент widget в определении поля. Например:

from django import forms

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

Это определит форму с комментарием, использующим виджет Textarea большего размера, а не виджет по умолчанию TextInput.

Установка аргументов для виджетов

Многие виджеты имеют необязательные дополнительные аргументы; они могут быть установлены при определении виджета в поле. В следующем примере атрибут years установлен для виджета SelectDateWidget:

from django import forms

BIRTH_YEAR_CHOICES = ['1980', '1981', '1982']
FAVORITE_COLORS_CHOICES = [
    ('blue', 'Blue'),
    ('green', 'Green'),
    ('black', 'Black'),
]

class SimpleForm(forms.Form):
    birth_year = forms.DateField(widget=forms.SelectDateWidget(years=BIRTH_YEAR_CHOICES))
    favorite_colors = forms.MultipleChoiceField(
        required=False,
        widget=forms.CheckboxSelectMultiple,
        choices=FAVORITE_COLORS_CHOICES,
    )

Дополнительную информацию о доступных виджетах и принимаемых ими аргументах см. в разделе Встроенные виджеты.

Виджеты, унаследованные от виджета `Select`

Виджеты, унаследованные от виджета Select, работают с выбором. Они предоставляют пользователю список вариантов для выбора. Разные виджеты представляют этот выбор по-разному; виджет Select сам использует представление HTML-списка <select>, а RadioSelect использует радиокнопки.

Select виджеты используются по умолчанию в полях ChoiceField. Выводимые в виджете варианты наследуются от поля ChoiceField, и изменение ChoiceField.choices обновит Select.choices. Например:

>>> from django import forms
>>> CHOICES = [('1', 'First'), ('2', 'Second')]
>>> choice_field = forms.ChoiceField(widget=forms.RadioSelect, choices=CHOICES)
>>> choice_field.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices
[('1', 'First'), ('2', 'Second')]
>>> choice_field.widget.choices = []
>>> choice_field.choices = [('1', 'First and only')]
>>> choice_field.widget.choices
[('1', 'First and only')]

Однако виджеты, которые предлагают атрибут choices, могут использоваться с полями, которые не основаны на выборе — например, с CharField — но рекомендуется использовать поле на основе ChoiceField, когда варианты присущи модели, а не просто представлению виджета.

Существует два способа настройки виджетов: по экземпляру виджета и по классу виджета.

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

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

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>

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

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

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

Базовые классы виджетов

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

Результат метода влияет на то, будет ли поле в форме модели возвращено к своему значению по умолчанию.

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

use_required_attribute(initial)

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

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

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

`MultiWidget`

class MultiWidget(widgets, attrs=None)

Виджет, состоящий из нескольких виджетов. MultiWidget тесно взаимодействует с MultiValueField.

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

widgets: Итерируемый объект, содержащий необходимые виджеты.

И один обязательный метод:

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(), 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 выполняется, когда value имеет значение None, что означает, что у нас нет значений по умолчанию для наших вложенных виджетов.

Реализация по умолчанию метода value_from_datadict() возвращает список значений, соответствующих каждому Widget. Это подходит при использовании с MultiWidget и MultiValueField. Но так как мы хотим использовать этот виджет с DateField, который принимает одно значение, мы переопределили этот метод. Реализация здесь объединяет данные из вложенных виджетов в строку в формате, ожидаемом DateField.

Встроенные виджеты

Django предоставляет представление всех основных HTML-виджетов, а также некоторые часто используемые группы виджетов в модуле django.forms.widgets, включая ввод текста, различные флажки и выпадающие списки, загрузку файлов и обработку многозначных вводов.

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

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

`TextInput`

class TextInput

input_type: 'text'
template_name: 'django/forms/widgets/text.html'
Отображается как: <input type="text" ...>

`NumberInput`

class NumberInput

input_type: 'number'
template_name: 'django/forms/widgets/number.html'
Отображается как: <input type="number" ...>

Обратите внимание, что не все браузеры поддерживают ввод локальных чисел в типах ввода number. Сам Django избегает их использования для полей, имеющих свойство localize, установленное в True.

`EmailInput`

class EmailInput

input_type: 'email'
template_name: 'django/forms/widgets/email.html'
Отображается как: <input type="email" ...>

`URLInput`

class URLInput

input_type: 'url'
template_name: 'django/forms/widgets/url.html'
Отображается как: <input type="url" ...>

`PasswordInput`

class PasswordInput

input_type: 'password'
template_name: 'django/forms/widgets/password.html'
Отображается как: <input type="password" ...>

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

render_value: Определяет, будет ли у виджета заполненное значение при повторном отображении формы после ошибки валидации (по умолчанию False).

`HiddenInput`

class HiddenInput

input_type: 'hidden'
template_name: 'django/forms/widgets/hidden.html'
Отображается как: <input type="hidden" ...>

Обратите внимание, что также существует виджет MultipleHiddenInput, который объединяет набор скрытых элементов ввода.

`DateInput`

class DateInput

input_type: 'text'
template_name: 'django/forms/widgets/date.html'
Отображается как: <input type="text" ...>

Принимает те же аргументы, что и TextInput, плюс один необязательный аргумент:

format: Формат, в котором будет отображаться начальное значение этого поля.

Если аргумент format не указан, используется формат по умолчанию, найденный в DATE_INPUT_FORMATS и учитывает Локализация форматов.

`DateTimeInput`

class DateTimeInput

input_type: 'text'
template_name: 'django/forms/widgets/datetime.html'
Отображается как: <input type="text" ...>

Принимает те же аргументы, что и TextInput, с одним дополнительным необязательным аргументом:

format: Формат, в котором будет отображаться начальное значение этого поля.

Если аргумент format не указан, используется первый формат, найденный в DATETIME_INPUT_FORMATS, и учитывается Локализация форматов.

По умолчанию, микросекундная часть значения времени всегда устанавливается в 0. Если требуются микросекунды, используйте подкласс с атрибутом supports_microseconds, установленным в True.

`TimeInput`

class TimeInput

input_type: 'text'
template_name: 'django/forms/widgets/time.html'
Отображается как: <input type="text" ...>

Принимает те же аргументы, что и TextInput, с одним дополнительным необязательным аргументом:

format: Формат, в котором будет отображаться начальное значение этого поля.

Если аргумент format не указан, используется первый формат, найденный в TIME_INPUT_FORMATS, и учитывается Локализация форматов.

Для обработки микросекунд, см. DateTimeInput.

`Textarea`

class Textarea

template_name: 'django/forms/widgets/textarea.html'
Отображается как: <textarea>...</textarea>

Виджеты выбора и флажков

Эти виджеты используют HTML-элементы <select>, <input type="checkbox">, и <input type="radio">.

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

`CheckboxInput`

class CheckboxInput

input_type: 'checkbox'
template_name: 'django/forms/widgets/checkbox.html'
Отображается как: <input type="checkbox" ...>

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

check_test: Вызываемый объект, который принимает значение CheckboxInput и возвращает True, если флажок должен быть отмечен для этого значения.

`Select`

class Select

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'
Отображается как: <select><option ...>...</select>

choices: Этот атрибут необязателен, когда у поля формы нет атрибута choices. Если он есть, он переопределит всё, что вы здесь задали, когда атрибут обновляется в Field.

`NullBooleanSelect`

class NullBooleanSelect

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'

Виджет выбора с вариантами «Неизвестно», «Да» и «Нет»

`SelectMultiple`

class SelectMultiple

template_name: 'django/forms/widgets/select.html'
option_template_name: 'django/forms/widgets/select_option.html'

Аналогично Select, но позволяет множественный выбор: <select multiple>...</select>

`RadioSelect`

class RadioSelect

template_name: 'django/forms/widgets/radio.html'
option_template_name: 'django/forms/widgets/radio_option.html'

Аналогично Select, но отображается как список радиокнопок внутри <li> тегов:

<ul>
  <li><input type="radio" name="..."></li>
  ...
</ul>

Для более точного управления сгенерированным разметкой, вы можете перебрать радиокнопки в шаблоне. Предположим форму myform с полем beatles, которое использует RadioSelect в качестве виджета:

{% for radio in myform.beatles %}
<div class="myradio">
    {{ radio }}
</div>
{% endfor %}

Это сгенерирует следующий HTML:

<div class="myradio">
    <label for="id_beatles_0"><input id="id_beatles_0" name="beatles" type="radio" value="john" required> John</label>
</div>
<div class="myradio">
    <label for="id_beatles_1"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required> Paul</label>
</div>
<div class="myradio">
    <label for="id_beatles_2"><input id="id_beatles_2" name="beatles" type="radio" value="george" required> George</label>
</div>
<div class="myradio">
    <label for="id_beatles_3"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required> Ringo</label>
</div>

Включая <label> теги. Для более точного управления, вы можете использовать атрибуты каждой радиокнопки tag, choice_label и id_for_label. Например, этот шаблон…

{% for radio in myform.beatles %}
    <label for="{{ radio.id_for_label }}">
        {{ radio.choice_label }}
        <span class="radio">{{ radio.tag }}</span>
    </label>
{% endfor %}

…результатирует в следующем HTML:

<label for="id_beatles_0">
    John
    <span class="radio"><input id="id_beatles_0" name="beatles" type="radio" value="john" required></span>
</label>

<label for="id_beatles_1">
    Paul
    <span class="radio"><input id="id_beatles_1" name="beatles" type="radio" value="paul" required></span>
</label>

<label for="id_beatles_2">
    George
    <span class="radio"><input id="id_beatles_2" name="beatles" type="radio" value="george" required></span>
</label>

<label for="id_beatles_3">
    Ringo
    <span class="radio"><input id="id_beatles_3" name="beatles" type="radio" value="ringo" required></span>
</label>

Если вы решите не перебирать радиокнопки – например, если ваш шаблон включает {{ myform.beatles }} – они будут выведены в <ul> с <li> тегами, как выше.

Внешний <ul> контейнер получает атрибут id виджета, если он определён, или BoundField.auto_id в противном случае.

При переборе радиокнопок, label и input теги включают атрибуты for и id, соответственно. Каждая радиокнопка имеет атрибут id_for_label для вывода идентификатора элемента.

`CheckboxSelectMultiple`

class CheckboxSelectMultiple

template_name: 'django/forms/widgets/checkbox_select.html'
option_template_name: 'django/forms/widgets/checkbox_option.html'

Аналогично SelectMultiple, но отображается как список флажков:

<ul>
  <li><input type="checkbox" name="..." ></li>
  ...
</ul>

Внутренний <ul> контейнер получает атрибут id виджета, если он определён, или BoundField.auto_id в противном случае.

Как и RadioSelect, вы можете перебирать отдельные флажки для вариантов виджета. В отличие от RadioSelect, флажки не будут включать required HTML атрибут, если поле является обязательным, так как валидация браузера потребует отметки всех флажков вместо хотя бы одного.

При переборе флажков, label и input теги содержат атрибуты for и id, соответственно. Каждый флажок имеет атрибут id_for_label для вывода идентификатора элемента.

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

`FileInput`

class FileInput

template_name: 'django/forms/widgets/file.html'
Отображается как: <input type="file" ...>

`ClearableFileInput`

class ClearableFileInput

template_name: 'django/forms/widgets/clearable_file_input.html'
Отображается как: <input type="file" ...> с дополнительным флажком для очистки значения поля, если поле не обязательно и имеет начальные данные.

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

`MultipleHiddenInput`

class MultipleHiddenInput

template_name: 'django/forms/widgets/multiple_hidden.html'
Отображается как: несколько <input type="hidden" ...> тегов

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

`SplitDateTimeWidget`

class SplitDateTimeWidget

template_name: 'django/forms/widgets/splitdatetime.html'

Обёртка (используя MultiWidget) вокруг двух виджетов: DateInput для даты и TimeInput для времени. Должен использоваться с SplitDateTimeField, а не с DateTimeField.

SplitDateTimeWidget имеет несколько необязательных аргументов:

date_format: Аналогично DateInput.format

time_format: Аналогично TimeInput.format

date_attrs

time_attrs: Аналогично Widget.attrs. Словарь, содержащий атрибуты HTML, которые необходимо задать для рендеринга виджетов DateInput и TimeInput соответственно. Если эти атрибуты не заданы, используется Widget.attrs.

`SplitHiddenDateTimeWidget`

class SplitHiddenDateTimeWidget

template_name: 'django/forms/widgets/splithiddendatetime.html'

Аналогично SplitDateTimeWidget, но использует HiddenInput для даты и времени.

`SelectDateWidget`

class SelectDateWidget

template_name: 'django/forms/widgets/select_date.html'

Обёртка вокруг трёх виджетов Select: по одному для месяца, дня и года.

Принимает несколько необязательных аргументов:

years: Необязательный список/кортеж годов, используемых в выпадающем списке «год». По умолчанию используется список, содержащий текущий год и следующие 9 лет.

months

Необязательный словарь месяцев, используемых в выпадающем списке «месяц».

Ключи словаря соответствуют номеру месяца (индексируется с 1) и значениями являются отображаемые названия месяцев:

MONTHS = {
    1:_('jan'), 2:_('feb'), 3:_('mar'), 4:_('apr'),
    5:_('may'), 6:_('jun'), 7:_('jul'), 8:_('aug'),
    9:_('sep'), 10:_('oct'), 11:_('nov'), 12:_('dec')
}

empty_label

Если DateField не является обязательным, SelectDateWidget будет иметь пустой вариант в верхней части списка (по умолчанию он равен ---). Вы можете изменить текст этой метки с помощью атрибута empty_label. empty_label может быть string, list, или tuple. Когда используется строка, все выпадающие списки будут иметь по одному пустому выбору с этой меткой. Если empty_label представляет собой list или tuple из 3 строковых элементов, выпадающие списки будут иметь собственные пользовательские метки. Метки должны быть в этом порядке ('year_label', 'month_label', 'day_label').

# A custom empty label with string
field1 = forms.DateField(widget=SelectDateWidget(empty_label="Nothing"))

# A custom empty label with tuple
field1 = forms.DateField(
    widget=SelectDateWidget(
        empty_label=("Choose Year", "Choose Month", "Choose Day"),
    ),
)

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/3.0/ref/forms/widgets/

Виджеты

Указание виджетов

Установка аргументов для виджетов

Виджеты, унаследованные от виджета `Select`

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

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

Стиль классов виджетов

Базовые классы виджетов

`Widget`

`MultiWidget`

Встроенные виджеты

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

`TextInput`

`NumberInput`

`EmailInput`

`URLInput`

`PasswordInput`

`HiddenInput`

`DateInput`

`DateTimeInput`

`TimeInput`

`Textarea`

Виджеты выбора и флажков

`CheckboxInput`

`Select`

`NullBooleanSelect`

`SelectMultiple`

`RadioSelect`

`CheckboxSelectMultiple`

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

`FileInput`

`ClearableFileInput`

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

`MultipleHiddenInput`

`SplitDateTimeWidget`

`SplitHiddenDateTimeWidget`

`SelectDateWidget`

Виджеты

Указание виджетов

Установка аргументов для виджетов

Виджеты, унаследованные от виджета Select

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

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

Стиль классов виджетов

Базовые классы виджетов

Widget

MultiWidget

Встроенные виджеты

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

TextInput

NumberInput

EmailInput

URLInput

PasswordInput

HiddenInput

DateInput

DateTimeInput

TimeInput

Textarea

Виджеты выбора и флажков

CheckboxInput

Select

NullBooleanSelect

SelectMultiple

RadioSelect

CheckboxSelectMultiple

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

FileInput

ClearableFileInput

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

MultipleHiddenInput

SplitDateTimeWidget

SplitHiddenDateTimeWidget

SelectDateWidget

Виджеты, унаследованные от виджета `Select`

`Widget`

`MultiWidget`

`TextInput`

`NumberInput`

`EmailInput`

`URLInput`

`PasswordInput`

`HiddenInput`

`DateInput`

`DateTimeInput`

`TimeInput`

`Textarea`

`CheckboxInput`

`Select`

`NullBooleanSelect`

`SelectMultiple`

`RadioSelect`

`CheckboxSelectMultiple`

`FileInput`

`ClearableFileInput`

`MultipleHiddenInput`

`SplitDateTimeWidget`

`SplitHiddenDateTimeWidget`

`SelectDateWidget`