Поля форм

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

`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" /></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" /></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" /></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" /></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></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" /></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" /></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" /></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" /></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" /></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" /><td></tr>

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

`widget`

Field.widget

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

`help_text`

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" /><br /><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" /><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" /> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" /></li>
<li>Sender: <input type="email" name="sender" /> 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" /> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" /></p>
<p>Sender: <input type="email" name="sender" /> 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

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

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

`has_changed()`

Field.has_changed() [source]

Этот метод был переименован из _has_changed().

Метод 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: Если True (значение по умолчанию), значение будет очищено от начальных и конечных пробелов.

`ChoiceField`

class ChoiceField(**kwargs) [source]

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

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

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

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

Возможность передавать вызываемый объект в 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 содержащий экземпляр Image из Pillow, используемый для проверки того, был ли файл действительным изображением. Кроме того, UploadedFile.content_type будет обновлен с типом содержимого изображения, если Pillow может его определить, в противном случае он будет установлен в None.

Атрибуты image и content_type , описанные в предыдущем абзаце, были добавлены.

`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. Если включено, удаление пробелов будет применено перед проверкой регулярного выражения.

Устаревшая с версии 1.8: Необязательный аргумент error_message также принимается для обратной совместимости, но будет удален в Django 1.10. Предпочтительный способ предоставления сообщения об ошибке - использование аргумента error_messages, передавая словарь с 'invalid' как ключом и сообщением об ошибке как значением.

`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

По умолчанию виджет <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)

Обратите внимание, что если ModelChoiceField требуется и имеет значение по умолчанию, пустой выбор не создается (независимо от значения 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.9/ref/forms/fields/

Поля форм

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

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

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

has_changed()

Встроенные классы 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

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

`required`

`label`

`label_suffix`

`initial`

`widget`

`help_text`

`error_messages`

`validators`

`localize`

`disabled`

`has_changed()`

Встроенные классы `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`