Поля форм

class Field(**kwargs) [source]

При создании класса Form, важнейшей частью является определение полей формы. Каждое поле имеет собственную логику валидации и несколько дополнительных «хуков».

Field.clean(value) [source]

Хотя основной способ использования классов Field — в классах Form, вы также можете их инстанцировать и использовать напрямую, чтобы лучше понять их работу. Каждый экземпляр Field имеет метод clean(), который принимает один аргумент и либо поднимает исключение django.forms.ValidationError, либо возвращает очищенное значение:

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
'foo@example.com'
>>> f.clean('invalid email address')
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

Основные аргументы полей

Каждый конструктор класса Field принимает, как минимум, эти аргументы. Некоторые классы Field принимают дополнительные, специфичные для поля аргументы, но следующие всегда должны приниматься:

Обязательность

Field.required

По умолчанию, каждый класс Field предполагает, что значение обязательно. Поэтому, если вы передадите пустое значение — либо None, либо пустую строку ("" ) — то clean() поднимет исключение ValidationError.

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean('foo')
'foo'
>>> f.clean('')
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(' ')
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

Чтобы указать, что поле не обязательно, передайте required=False в конструктор Field.

>>> f = forms.CharField(required=False)
>>> f.clean('foo')
'foo'
>>> f.clean('')
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

Если у Field есть required=False, и вы передаёте clean() пустое значение, то clean() вернёт нормализованное пустое значение, а не поднимет исключение ValidationError. Для CharField, это будет пустая строка Юникода. Для других классов Field, это может быть None. (Это зависит от поля).

У виджетов обязательных полей формы есть атрибут required HTML. Чтобы отключить его, установите атрибут Form.use_required_attribute в False. Атрибут required не включён в формы наборов форм, потому что проверка браузера может быть некорректной при добавлении и удалении наборов форм.

Новое в Django 1.10:

Добавлена поддержка атрибута required HTML.

Метка

Field.label

Аргумент label позволяет указать «человеко-понятную» метку для этого поля. Она используется, когда поле Field отображается в Form.

Как объяснялось в разделе «Вывод форм в HTML», метка по умолчанию для Field генерируется из имени поля путём преобразования всех нижних подчеркиваний в пробелы и верхнего регистра первой буквы. Укажите label, если это поведение не приводит к адекватной метке.

Вот полный пример Form, который реализует label для двух его полей. Мы указали auto_id=False для упрощения вывода:

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label='Your name')
...     url = forms.URLField(label='Your website', required=False)
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Your name:</th><td><input type="text" name="name" required /></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr>

Суффикс метки

Field.label_suffix

Аргумент label_suffix позволяет переопределить label_suffix формы для каждого поля:

>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')
>>> f = ContactForm(label_suffix='?')
>>> print(f.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required /></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required /></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required /></p>

Начальное значение

Field.initial

Аргумент initial позволяет указать начальное значение, используемое при отображении этого Field в не связанной Form.

Для указания динамических начальных данных см. параметр Form.initial.

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

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial='Your name')
...     url = forms.URLField(initial='http://')
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" required /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr>

Вы, возможно, думаете: а почему бы не передать словарь начальных значений как данные при отображении формы? В таком случае вы вызовете валидацию, и в HTML-выводе будут отображаться любые ошибки валидации:

>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
>>> default_data = {'name': 'Your name', 'url': 'http://'}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required /></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required /></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required /></td></tr>

Вот почему значения initial отображаются только для несвязанных форм. Для связанных форм HTML-вывод будет использовать связанные данные.

Также обратите внимание, что значения initial не используются как «резервные» данные в валидации, если значение определённого поля не задано. Значения initial предназначены только для начального отображения формы:

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial='Your name')
...     url = forms.URLField(initial='http://')
...     comment = forms.CharField()
>>> data = {'name': '', 'url': '', 'comment': 'Foo'}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}

Вместо константы вы также можете передать любой вызываемый объект:

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required /><td></tr>

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

Аргумент widget позволяет указать класс Widget для использования при отображении этого Field. См. Виджеты для получения дополнительной информации.

Текст справки

Field.help_text

Аргумент help_text позволяет указать описательный текст для этого Field. Если вы предоставите help_text, он будет отображаться рядом с Field при отображении Field одним из удобных методов Form (например, as_ul()).

Как и в атрибуте help_text модели поля, это значение не экранируется HTML в автоматически сгенерированных формах.

Вот полный пример Form, который реализует help_text для двух его полей. Мы указали auto_id=False для упрощения вывода:

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
...     message = forms.CharField()
...     sender = forms.EmailField(help_text='A valid email address, please.')
...     cc_myself = forms.BooleanField(required=False)
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required /><br /><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required /></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required /><br />A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required /> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required /></li>
<li>Sender: <input type="email" name="sender" required /> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required /> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required /></p>
<p>Sender: <input type="email" name="sender" required /> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself" /></p>

Сообщения об ошибках

Field.error_messages

Аргумент error_messages позволяет переопределить сообщения по умолчанию, которые будет поднимать поле. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые вы хотите переопределить. Например, вот сообщение об ошибке по умолчанию:

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

А вот и пользовательское сообщение об ошибке:

>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

В разделе «Встроенные классы полей» ниже, каждый Field определяет используемые ключи сообщений об ошибках.

Валидаторы

Field.validators

Аргумент validators позволяет предоставить список функций валидации для этого поля.

См. документацию по валидаторам для получения дополнительной информации.

Локализация

Field.localize

Аргумент localize включает локализованный вывод данных ввода формы, а также рендеринг вывода.

См. документацию по форматированию локализации для получения дополнительной информации.

Отключено

Field.disabled

Булевый аргумент disabled, при установке в значение True, отключает поле формы с помощью атрибута disabled HTML, чтобы оно не было редактируемым для пользователей. Даже если пользователь подменит значение поля, отправленное на сервер, оно будет проигнорировано в пользу значения из начальных данных формы.

Проверка изменений данных поля

Изменились ли данные?

Field.has_changed() [source]

Метод has_changed() используется для определения, изменилось ли значение поля с момента его начального значения. Возвращает True или False.

См. документацию по Form.has_changed() для получения дополнительной информации.

Встроенные классы `Field`

Библиотека forms поставляется с набором классов Field, которые представляют распространённые потребности в валидации. В этом разделе документировано каждое встроенное поле.

Для каждого поля мы описываем виджет по умолчанию, если вы не указываете widget. Мы также указываем значение, возвращаемое при вводе пустого значения (см. раздел о required выше для понимания его значения).

`BooleanField`

class BooleanField(**kwargs) [source]

Значение по умолчанию виджета: CheckboxInput
Пустое значение: False
Нормализуется до: Python True или False значение.
Проверяет, что значение равно True (например, чекбокс отмечен), если у поля есть required=True.
Ключи сообщений об ошибках: required

Примечание

Поскольку все подклассы Field имеют required=True по умолчанию, условие валидации здесь важно. Если вы хотите включить в форму boolean, который может быть True или False (например, отмеченный или не отмеченный чекбокс), вы должны помнить, чтобы передать required=False при создании BooleanField.

`CharField`

class CharField(**kwargs) [source]

Значение по умолчанию виджета: TextInput
Пустое значение: то, что вы указали в качестве empty_value.
Нормализуется до: объекта Unicode.
Проверяет max_length или min_length, если они указаны. В противном случае все вводимые данные валидны.
Ключи сообщений об ошибках: required, max_length, min_length

Имеет три необязательных аргумента для валидации:

max_length

min_length

Если указаны, эти аргументы гарантируют, что строка не превышает или не меньше заданной длины.

strip: Если True (по умолчанию), значение будет очищено от начальных и конечных пробелов.

empty_value: Новое в Django 1.11.

Значение, используемое для представления «пустого». По умолчанию — пустая строка.

`ChoiceField`

class ChoiceField(**kwargs) [source]

Значение по умолчанию виджета: Select
Пустое значение: '' (пустая строка)
Нормализуется до: объекта Unicode.
Проверяет, что заданное значение присутствует в списке вариантов.
Ключи сообщений об ошибках: required, invalid_choice

Сообщение об ошибке «invalid_choice» может содержать %(value)s, которое будет заменено выбранным вариантом.

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

choices: Итерируемый объект (например, список или кортеж) из 2-х кортежей, используемых в качестве вариантов для этого поля, или вызываемый объект, возвращающий такой итерируемый объект. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. Более подробную информацию см. в документации по выбору поля модели. Если аргумент является вызываемым объектом, он вычисляется каждый раз, когда инициализируется форма поля. По умолчанию — пустой список.

`TypedChoiceField`

class TypedChoiceField(**kwargs) [source]

Точно так же, как и ChoiceField, за исключением того, что TypedChoiceField принимает два дополнительных аргумента, coerce и empty_value.

Значение по умолчанию виджета: Select
Пустое значение: то, что вы указали в качестве empty_value.
Нормализуется до: значения типа, заданного аргументом coerce.
Проверяет, что заданное значение присутствует в списке вариантов и может быть преобразовано.
Ключи сообщений об ошибках: required, invalid_choice

Принимает дополнительные аргументы:

coerce: Функция, которая принимает одно значение и возвращает преобразованное значение. Примеры включают встроенные int, float, bool и другие типы. По умолчанию — функция идентификации. Обратите внимание, что преобразование происходит после проверки входных данных, поэтому возможно преобразовать в значение, отсутствующее в choices.

empty_value: Значение, используемое для представления «пустого». По умолчанию — пустая строка; None — ещё один распространённый выбор здесь. Обратите внимание, что это значение не будет преобразовано функцией, заданной в аргументе coerce, поэтому выберите его соответствующим образом.

`DateField`

class DateField(**kwargs) [source]

Значение по умолчанию виджета: DateInput
Пустое значение: None
Нормализуется до: объекта Python datetime.date.
Проверяет, что заданное значение является datetime.date, datetime.datetime или строкой, отформатированной в определенном формате даты.
Ключи сообщений об ошибках: required, invalid

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

input_formats: Список форматов, используемых для попытки преобразования строки в объект корректной даты datetime.date.

Если аргумент input_formats не предоставлен, значения форматов по умолчанию:

['%Y-%m-%d',      # '2006-10-25'
 '%m/%d/%Y',      # '10/25/2006'
 '%m/%d/%y']      # '10/25/06'

Кроме того, если вы укажете USE_L10N=False в своих настройках, следующие значения также будут включены в форматы по умолчанию:

['%b %d %Y',      # 'Oct 25 2006'
 '%b %d, %Y',     # 'Oct 25, 2006'
 '%d %b %Y',      # '25 Oct 2006'
 '%d %b, %Y',     # '25 Oct, 2006'
 '%B %d %Y',      # 'October 25 2006'
 '%B %d, %Y',     # 'October 25, 2006'
 '%d %B %Y',      # '25 October 2006'
 '%d %B, %Y']     # '25 October, 2006'

См. также локализацию форматов.

`DateTimeField`

class DateTimeField(**kwargs) [source]

Значение по умолчанию виджета: DateTimeInput
Пустое значение: None
Нормализуется до: объекта Python datetime.datetime.
Проверяет, что заданное значение является datetime.datetime, datetime.date или строкой, отформатированной в определенном формате даты и времени.
Ключи сообщений об ошибках: required, invalid

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

input_formats: Список форматов, используемых для попытки преобразования строки в объект корректной даты и времени datetime.datetime.

Если аргумент input_formats не предоставлен, значения форматов по умолчанию:

['%Y-%m-%d %H:%M:%S',    # '2006-10-25 14:30:59'
 '%Y-%m-%d %H:%M',       # '2006-10-25 14:30'
 '%Y-%m-%d',             # '2006-10-25'
 '%m/%d/%Y %H:%M:%S',    # '10/25/2006 14:30:59'
 '%m/%d/%Y %H:%M',       # '10/25/2006 14:30'
 '%m/%d/%Y',             # '10/25/2006'
 '%m/%d/%y %H:%M:%S',    # '10/25/06 14:30:59'
 '%m/%d/%y %H:%M',       # '10/25/06 14:30'
 '%m/%d/%y']             # '10/25/06'

См. также локализацию форматов.

`DecimalField`

class DecimalField(**kwargs) [source]

По умолчанию виджет: NumberInput, когда Field.localize является False, в противном случае TextInput.
Пустое значение: None
Нормализуется до: Python decimal.
Проверяет, что заданное значение является десятичным. Пробелы в начале и конце игнорируются.
Ключи сообщений об ошибках: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits

Сообщения об ошибках max_value и min_value могут содержать %(limit_value)s, которое будет заменено соответствующим пределом. Аналогично, сообщения об ошибках max_digits, max_decimal_places и max_whole_digits могут содержать %(max)s.

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

max_value

min_value: Они контролируют диапазон допустимых значений поля и должны быть предоставлены в виде decimal.Decimal значений.

max_digits: Максимальное количество цифр (перед и после десятичной точки, без ведущих нулей) разрешенных в значении.

decimal_places: Максимальное количество десятичных знаков, разрешенных.

`DurationField`

class DurationField(**kwargs) [source]

По умолчанию виджет: TextInput
Пустое значение: None
Нормализуется до: Python timedelta.
Проверяет, что заданное значение — это строка, которая может быть преобразована в timedelta.
Ключи сообщений об ошибках: required, invalid.

Принимает любой формат, понятный parse_duration().

`EmailField`

class EmailField(**kwargs) [source]

По умолчанию виджет: EmailInput
Пустое значение: '' (пустая строка)
Нормализуется до: объект Unicode.
Проверяет, что заданное значение является корректным адресом электронной почты, используя умеренно сложную регулярную выражение.
Ключи сообщений об ошибках: required, invalid

Имеет два необязательных аргумента для проверки, max_length и min_length. Если они предоставлены, эти аргументы гарантируют, что строка не превышает или не меньше заданной длины.

`FileField`

class FileField(**kwargs) [source]

По умолчанию виджет: ClearableFileInput
Пустое значение: None
Нормализуется до: объект UploadedFile, который объединяет содержимое файла и имя файла в один объект.
Может проверять, что непустые данные файла были привязаны к форме.
Ключи сообщений об ошибках: required, invalid, missing, empty, max_length

Имеет два необязательных аргумента для проверки, max_length и allow_empty_file. Если они предоставлены, эти аргументы гарантируют, что имя файла не превышает заданной длины, и что проверка пройдёт даже если содержимое файла пустое.

Дополнительную информацию об объекте UploadedFile можно найти в документации по загрузке файлов.

При использовании FileField в форме не забудьте также привязать данные файла к форме.

Ошибка max_length относится к длине имени файла. В сообщении об ошибке для этого ключа %(max)d будет заменено максимальной длиной имени файла, а %(length)d — текущей длиной имени файла.

`FilePathField`

class FilePathField(**kwargs) [source]

По умолчанию виджет: Select
Пустое значение: None
Нормализуется до: строка Unicode
Проверяет, что выбранный элемент существует в списке вариантов.
Ключи сообщений об ошибках: required, invalid_choice

Поле позволяет выбирать файлы внутри определённой директории. Оно принимает пять дополнительных аргументов; только path является обязательным:

path: Полный путь к директории, содержимое которой нужно отобразить в списке. Директория должна существовать.

recursive: Если False (по умолчанию), то в списке будут только прямые элементы директории path. Если True, то директория будет рекурсивно пройдена, и все элементы вложенных директорий будут отображены в списке.

match: Шаблон регулярного выражения; только файлы, имена которых соответствуют этому выражению, будут разрешены в качестве вариантов.

allow_files: Необязательно. Либо True, либо False. По умолчанию True. Указывает, должны ли файлы в указанном месте включаться в список. Либо это, либо allow_folders должно быть True.

allow_folders: Необязательно. Либо True, либо False. По умолчанию False. Указывает, должны ли папки в указанном месте включаться в список. Либо это, либо allow_files должно быть True.

`FloatField`

class FloatField(**kwargs) [source]

По умолчанию виджет: NumberInput при Field.localize False, в противном случае TextInput.
Пустое значение: None
Нормализуется до: Python float.
Проверяет, что заданное значение является числом с плавающей точкой. Пробелы в начале и конце разрешены, как в функции Python float().
Ключи сообщений об ошибках: required, invalid, max_value, min_value

Принимает два необязательных аргумента для проверки, max_value и min_value. Они контролируют диапазон разрешенных значений в поле.

`ImageField`

class ImageField(**kwargs) [source]

По умолчанию виджет: ClearableFileInput
Пустое значение: None
Нормализуется до: Объект UploadedFile , который объединяет содержимое файла и имя файла в один объект.
Проверяет, что данные файла привязаны к форме, и что файл имеет формат изображения, понятный Pillow.
Ключи сообщений об ошибках: required, invalid, missing, empty, invalid_image

Использование поля ImageField требует, чтобы библиотека Pillow была установлена с поддержкой используемых вами форматов изображений. Если при загрузке изображения возникает ошибка corrupt image, это обычно означает, что Pillow не понимает его формат. Для исправления этого установите соответствующую библиотеку и переустановите Pillow.

При использовании поля ImageField в форме, вы также должны помнить о привязке данных файла к форме.

После очистки и проверки поля, объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки, был ли файл допустимым изображением. Кроме того, UploadedFile.content_type будет обновлён с типом содержимого изображения, если Pillow сможет его определить, в противном случае он будет установлен на значение None.

`IntegerField`

class IntegerField(**kwargs) [source]

По умолчанию виджет: NumberInput, если Field.localize — False, иначе TextInput.
Пустое значение: None
Нормализуется до: Целого числа Python или длинного целого числа.
Проверяет, что данное значение является целым числом. Разрешаются начальные и конечные пробелы, как в функции Python int().
Ключи сообщений об ошибках: required, invalid, max_value, min_value

Сообщения об ошибках max_value и min_value могут содержать %(limit_value)s, которые будут заменены соответствующим пределом.

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

max_value

min_value

Они контролируют диапазон допустимых значений поля.

`GenericIPAddressField`

class GenericIPAddressField(**kwargs) [source]

Поле, содержащее IPv4 или IPv6 адрес.

По умолчанию виджет: TextInput
Пустое значение: '' (пустая строка)
Нормализуется до: Объект Unicode. IPv6 адреса нормализуются, как описано ниже.
Проверяет, что данное значение является допустимым IP адресом.
Ключи сообщений об ошибках: required, invalid

Нормализация IPv6 адресов следует RFC 4291#section-2.2 раздел 2.2, включая использование формата IPv4, предложенного в абзаце 3 этого раздела, например, ::ffff:192.0.2.0. Например, 2001:0::0:01 будет нормализован до 2001::1, а ::ffff:0a0a:0a0a до ::ffff:10.10.10.10. Все символы преобразуются в нижний регистр.

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

protocol: Ограничивает допустимые входные данные указанным протоколом. Допустимые значения: both (по умолчанию), IPv4 или IPv6. Сопоставление регистронезависимое.

unpack_ipv4: Распаковывает IPv4 адреса, такие как ::ffff:192.0.2.1. Если этот параметр включен, этот адрес будет распакован до 192.0.2.1. По умолчанию выключен. Может использоваться только при protocol установлено на 'both'.

`MultipleChoiceField`

class MultipleChoiceField(**kwargs) [source]

По умолчанию виджет: SelectMultiple
Пустое значение: [] (пустой список)
Нормализуется до: Список объектов Unicode.
Проверяет, что каждое значение в данном списке значений существует в списке вариантов.
Ключи сообщений об ошибках: required, invalid_choice, invalid_list

Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено выбранным вариантом.

Принимает один дополнительный обязательный аргумент, choices, как для ChoiceField.

`TypedMultipleChoiceField`

class TypedMultipleChoiceField(**kwargs) [source]

Подобно MultipleChoiceField, за исключением того, что TypedMultipleChoiceField принимает два дополнительных аргумента, coerce и empty_value.

По умолчанию виджет: SelectMultiple
Пустое значение: то, что вы задали как empty_value
Нормализуется до: Список значений типа, предоставленного аргументом coerce.
Проверяет, что заданные значения существуют в списке вариантов и могут быть приведены к нужному типу.
Ключи сообщений об ошибках: required, invalid_choice

Сообщение об ошибке invalid_choice может содержать %(value)s, которое будет заменено выбранным вариантом.

Принимает два дополнительных аргумента, coerce и empty_value, как для TypedChoiceField.

`NullBooleanField`

class NullBooleanField(**kwargs) [source]

По умолчанию виджет: NullBooleanSelect
Пустое значение: None
Нормализуется до: Python значение True, False или None.
Ничего не проверяет (т.е. никогда не вызывает ValidationError).

`RegexField`

class RegexField(**kwargs) [source]

По умолчанию виджет: TextInput
Пустое значение: '' (пустая строка)
Нормализуется до: Объект Unicode.
Проверяет, что данное значение соответствует определённому регулярному выражению.
Ключи сообщений об ошибках: required, invalid

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

regex: Регулярное выражение, заданное либо в виде строки, либо в виде скомпилированного объекта регулярного выражения.

Также принимает max_length, min_length, и strip, которые работают так же, как и для CharField.

strip: По умолчанию False. Если включено, перед проверкой регулярным выражением будет выполнено удаление пробелов.

`SlugField`

class SlugField(**kwargs) [source]

Значение по умолчанию для виджета: TextInput
Пустое значение: '' (пустая строка)
Нормализация: Объект Unicode.
Проверка: значение должно содержать только буквы, цифры, нижние подчеркивания и дефисы.
Сообщения об ошибках: required, invalid

Это поле предназначено для представления модели SlugField в формах.

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

allow_unicode: Логический параметр, определяющий, допускать ли Unicode-символы помимо ASCII. По умолчанию False.

`TimeField`

class TimeField(**kwargs) [source]

Значение по умолчанию для виджета: TextInput
Пустое значение: None
Нормализация: Объект Python datetime.time.
Проверка: заданное значение должно быть объектом времени datetime.time или строкой в определенном формате времени.
Ключи сообщений об ошибках: required, invalid

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

input_formats: Список форматов, используемых для преобразования строки в объект datetime.time.

Если аргумент input_formats не указан, используются следующие форматы ввода по умолчанию:

'%H:%M:%S',     # '14:30:59'
'%H:%M',        # '14:30'

`URLField`

class URLField(**kwargs) [source]

Значение по умолчанию для виджета: URLInput
Пустое значение: '' (пустая строка)
Нормализация: Объект Unicode.
Проверка: значение должно быть корректным URL.
Ключи сообщений об ошибках: required, invalid

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

max_length

min_length

Эти параметры аналогичны CharField.max_length и CharField.min_length.

`UUIDField`

class UUIDField(**kwargs) [source]

Значение по умолчанию для виджета: TextInput
Пустое значение: '' (пустая строка)
Нормализация: Объект UUID.
Ключи сообщений об ошибках: required, invalid

Это поле примет любой формат строки, который принимается в качестве аргумента hex конструктора UUID.

Несколько сложные встроенные `Field` классы

`ComboField`

class ComboField(**kwargs) [source]

Значение по умолчанию для виджета: TextInput
Пустое значение: '' (пустая строка)
Нормализация: Объект Unicode.
Проверка: значение проверяется по каждому полю, указанному аргументом ComboField.
Ключи сообщений об ошибках: required, invalid

Требуется один дополнительный аргумент:

fields

Список полей, которые используются для проверки значения поля (в указанном порядке).

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com')
'test@example.com'
>>> f.clean('longemailaddress@example.com')
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

`MultiValueField`

class MultiValueField(fields=(), **kwargs) [source]

Значение по умолчанию для виджета: TextInput
Пустое значение: '' (пустая строка)
Нормализация: тип, возвращаемый методом compress подкласса.
Проверка: значение проверяется по каждому полю, указанному аргументом MultiValueField.
Ключи сообщений об ошибках: required, invalid, incomplete

Агрегирует логику нескольких полей, которые вместе создают одно значение.

Это абстрактное поле и должно быть расширено. В отличие от полей с одним значением, подклассы MultiValueField не должны реализовывать clean(), а реализовывать compress().

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

fields: Кортеж полей, значения которых очищаются и объединяются в одно значение. Каждое значение поля очищается соответствующим полем в fields — первое значение очищается первым полем, второе — вторым и т.д. После очистки всех полей список очищенных значений объединяется в одно значение с помощью compress().

Также принимает некоторые необязательные аргументы:

require_all_fields

По умолчанию True, в этом случае ошибка валидации required будет поднята, если не задано значение для любого поля.

При значении False, атрибут Field.required можно установить в False для отдельных полей, чтобы сделать их необязательными. Если для требуемого поля не задано значение, будет поднята ошибка валидации incomplete.

Сообщение об ошибке по умолчанию incomplete может быть определено в подклассе MultiValueField, или разные сообщения могут быть определены для каждого отдельного поля. Например:

from django.core.validators import RegexValidator

class PhoneField(MultiValueField):
    def __init__(self, *args, **kwargs):
        # Define one message for all fields.
        error_messages = {
            'incomplete': 'Enter a country calling code and a phone number.',
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={'incomplete': 'Enter a country calling code.'},
                validators=[
                    RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'),
                ],
            ),
            CharField(
                error_messages={'incomplete': 'Enter a phone number.'},
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')],
            ),
            CharField(
                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')],
                required=False,
            ),
        )
        super(PhoneField, self).__init__(
            error_messages=error_messages, fields=fields,
            require_all_fields=False, *args, **kwargs
        )

widget: Должен быть подклассом django.forms.MultiWidget. Значение по умолчанию — TextInput, что, вероятно, не очень полезно в данном случае.

compress(data_list) [source]

Принимает список допустимых значений и возвращает «сжатую» версию этих значений — в едином значении. Например, SplitDateTimeField — это подкласс, который объединяет поле времени и поле даты в объект datetime.

Этот метод должен быть реализован в подклассах.

`SplitDateTimeField`

class SplitDateTimeField(**kwargs) [source]

По умолчанию виджет: SplitDateTimeWidget
Пустое значение: None
Нормализуется в: Объект Python datetime.datetime.
Проверяет, что заданное значение является объектом datetime.datetime или строкой, отформатированной в определённом формате даты и времени.
Ключи сообщений об ошибках: required, invalid, invalid_date, invalid_time

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

input_date_formats: Список форматов, используемых для преобразования строки в допустимый объект datetime.date.

Если аргумент input_date_formats не указан, используются форматы ввода по умолчанию для DateField.

input_time_formats: Список форматов, используемых для преобразования строки в допустимый объект datetime.time.

Если аргумент input_time_formats не указан, используются форматы ввода по умолчанию для TimeField.

Поля, обрабатывающие отношения

Для представления отношений между моделями доступны два поля: ModelChoiceField и ModelMultipleChoiceField. Оба этих поля требуют единственный параметр queryset, который используется для создания вариантов для поля. При валидации формы эти поля поместят либо один объект модели (в случае ModelChoiceField) либо несколько объектов модели (в случае ModelMultipleChoiceField) в словарь cleaned_data формы.

Для более сложных случаев вы можете указать queryset=None, при объявлении поля формы, и затем заполнить queryset в методе __init__() формы:

class FooMultipleChoiceForm(forms.Form):
    foo_select = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super(FooMultipleChoiceForm, self).__init__(*args, **kwargs)
        self.fields['foo_select'].queryset = ...

`ModelChoiceField`

class ModelChoiceField(**kwargs) [source]

По умолчанию виджет: Select
Пустое значение: None
Нормализуется в: экземпляр модели.
Проверяет, что заданный идентификатор существует в наборе запросов.
Ключи сообщений об ошибках: required, invalid_choice

Позволяет выбрать один объект модели, подходящий для представления внешнего ключа. Обратите внимание, что виджет по умолчанию для ModelChoiceField становится непрактичным, когда количество записей увеличивается. Не следует использовать его для более чем 100 элементов.

Требуется один аргумент:

queryset: Набор объектов модели, из которого выводятся варианты для поля и который используется для проверки выбора пользователя. Вычисляется при отображении формы.

ModelChoiceField также принимает два необязательных аргумента:

empty_label

По умолчанию виджет ModelChoiceField используемый в ModelChoiceField имеет пустой выбор в верхней части списка. Вы можете изменить текст этой метки (который по умолчанию "---------") с помощью атрибута empty_label, или полностью отключить пустую метку, установив empty_label в значение None.

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

Обратите внимание, что если требуется значение по умолчанию и имеет значение по умолчанию, пустой выбор не создаётся (независимо от значения empty_label).

to_field_name

Этот необязательный аргумент используется для указания поля, используемого в качестве значения вариантов в виджете поля. Убедитесь, что это уникальное поле для модели, иначе выбранное значение может соответствовать более чем одному объекту. По умолчанию он установлен в None, в этом случае будет использоваться первичный ключ каждого объекта. Например:

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

что даст:

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

и:

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

что даст:

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

Метод __str__ (__unicode__ на Python 2) модели будет вызван для генерации строковых представлений объектов для использования в вариантах поля; для предоставления настраиваемых представлений, следует подклассировать ModelChoiceField и переопределить label_from_instance. Этот метод получит объект модели и должен вернуть строку, подходящую для его представления. Например:

from django.forms import ModelChoiceField

class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

`ModelMultipleChoiceField`

class ModelMultipleChoiceField(**kwargs) [source]

По умолчанию виджет: SelectMultiple
Пустое значение: Пустой набор QuerySet (self.queryset.none())
Нормализуется в: набор экземпляров моделей.
Проверяет, что каждый идентификатор в заданном списке значений существует в наборе запросов.
Ключи сообщений об ошибках: required, list, invalid_choice, invalid_pk_value

Сообщение invalid_choice может содержать %(value)s, а сообщение invalid_pk_value может содержать %(pk)s, которые будут заменены соответствующими значениями.

Позволяет выбрать один или несколько объектов модели, подходящих для представления множественного отношения "многие ко многим". Как и в ModelChoiceField, вы можете использовать label_from_instance для настройки представлений объектов.

Требуется один аргумент:

queryset: То же, что и в ModelChoiceField.queryset.

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

to_field_name: То же, что и в ModelChoiceField.to_field_name.

Создание пользовательских полей

Если встроенные классы Field не удовлетворяют вашим потребностям, вы можете легко создать пользовательские классы Field. Для этого просто создайте подкласс django.forms.Field. Единственные требования — реализовать метод clean() и то, что метод __init__() должен принимать основные аргументы, упомянутые выше (required, label, initial, widget, help_text).

Вы также можете настроить способ доступа к полю, переопределив get_bound_field().

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

Поля форм

Основные аргументы полей

Обязательность

Метка

Суффикс метки

Начальное значение

Виджет

Текст справки

Сообщения об ошибках

Валидаторы

Локализация

Отключено

Проверка изменений данных поля

Изменились ли данные?

Встроенные классы Field

BooleanField

CharField

ChoiceField

TypedChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

ImageField

IntegerField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

Несколько сложные встроенные Field классы

ComboField

MultiValueField

SplitDateTimeField

Поля, обрабатывающие отношения

ModelChoiceField

ModelMultipleChoiceField

Создание пользовательских полей

Встроенные классы `Field`

`BooleanField`

`CharField`

`ChoiceField`

`TypedChoiceField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FilePathField`

`FloatField`

`ImageField`

`IntegerField`

`GenericIPAddressField`

`MultipleChoiceField`

`TypedMultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`URLField`

`UUIDField`

Несколько сложные встроенные `Field` классы

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`