Поля форм

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 принимают дополнительные аргументы, специфичные для поля, но следующие всегда должны приниматься:

`required`

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, это будет пустая строка Unicode. Для других классов Field, это может быть None. (Это варьируется в зависимости от поля.)

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

Новое в Django 1.10:

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

`label`

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>

`label_suffix`

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>

`initial`

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 позволяет указать класс Widget для использования при отрисовке этого поля Field. См. Виджеты для получения дополнительной информации.

`help_text`

Field.help_text

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

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

Вот полный пример 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>

`error_messages`

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 определяет ключи сообщений об ошибках, которые он использует.

`validators`

Field.validators

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

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

`localize`

Field.localize

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

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

`disabled`

Field.disabled

Новое в Django 1.9:

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

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

`has_changed()`

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, условие валидации здесь важно. Если вы хотите включить в форму булево значение, которое может быть True или False (например, галочка установлена или снята), вы должны помнить о передаче required=False при создании поля BooleanField.

`CharField`

class CharField(**kwargs) [source]

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

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

max_length

min_length

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

strip: Новое в Django 1.9.

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

Поле выбора

class ChoiceField(**kwargs) [source]

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

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

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

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

Тип поля выбора

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, поэтому выберите его соответствующим образом.

Поле даты

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'

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

Поле даты и времени

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'

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

Поле десятичной дроби

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: Максимальное количество десятичных знаков.

Поле продолжительности

class DurationField(**kwargs) [source]

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

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

Поле электронной почты

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.
Проверяет, что заданное значение является 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, сопоставленные с IPv6, например, ::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: Добавлено в Django 1.9.

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

`SlugField`

class SlugField(**kwargs) [source]

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

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

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

allow_unicode: Добавлено в Django 1.9.

Булево значение, указывающее полю принимать Unicode буквы помимо ASCII букв. По умолчанию False.

`TimeField`

class TimeField(**kwargs) [source]

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

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

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

Если аргумент 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.

Slightly complex built-in `Field` classes

`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
Нормализуется до: Экземпляра модели.
Проверяет, что заданный id существует в наборе запросов.
Ключи сообщений об ошибках: required, invalid_choice

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

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

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

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

empty_label

По умолчанию виджет <select> используемый в 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.10/ref/forms/fields/

Поля форм

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

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

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

has_changed()

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

BooleanField

CharField

Поле выбора

Тип поля выбора

Поле даты

Поле даты и времени

Поле десятичной дроби

Поле продолжительности

Поле электронной почты

FileField

FilePathField

FloatField

ImageField

IntegerField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

Slightly complex built-in Field classes

ComboField

MultiValueField

SplitDateTimeField

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

ModelChoiceField

ModelMultipleChoiceField

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

`required`

`label`

`label_suffix`

`initial`

`widget`

`help_text`

`error_messages`

`validators`

`localize`

`disabled`

`has_changed()`

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

`BooleanField`

`CharField`

`FileField`

`FilePathField`

`FloatField`

`ImageField`

`IntegerField`

`GenericIPAddressField`

`MultipleChoiceField`

`TypedMultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`URLField`

`UUIDField`

Slightly complex built-in `Field` classes

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`