Поля форм

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. (Это варьируется в зависимости от поля.)

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

Метка

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, отключает поле формы с помощью атрибута HTML disabled, чтобы оно не редактировалось пользователями. Даже если пользователь изменяет значение поля, отправляемого на сервер, оно будет проигнорировано в пользу значения из начальных данных формы.

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

Изменено

Field.has_changed() [source]

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

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

Встроенные классы полей

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

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

Поле булевого типа

class BooleanField(**kwargs) [source]

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

Примечание

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

Поле символьной строки

class CharField(**kwargs) [source]

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

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

max_length

min_length

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

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

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

`ChoiceField`

class ChoiceField(**kwargs) [source]

Значение по умолчанию виджета: Select
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Проверяет, что заданное значение существует в списке вариантов.
Ключи сообщений об ошибках: 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.
Проверяет, что заданное значение является десятичным. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Начальные и конечные пробелы игнорируются.
Ключи сообщений об ошибках: 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. Значение должно находиться между datetime.timedelta.min и datetime.timedelta.max.
Ключи сообщений об ошибках: required, invalid, overflow.

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

`EmailField`

class EmailField(**kwargs) [source]

Значение по умолчанию виджета: EmailInput
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Использует EmailValidator для проверки того, что заданное значение является корректным электронным адресом, используя достаточно сложную регулярную выражение.
Ключи сообщений об ошибках: 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
Нормализуется до: Строки.
Проверяет, что выбранный элемент существует в списке элементов.
Ключи сообщений об ошибках: 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.
Проверяет, что заданное значение — это число с плавающей точкой. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Разрешается начальный и конечный пробелы, как в функции Python float().
Ключи сообщений об ошибках: required, invalid, max_value, min_value

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

`ImageField`

class ImageField(**kwargs) [source]

Значение по умолчанию виджета: ClearableFileInput
Пустое значение: None
Нормализуется до: объекта UploadedFile, который объединяет содержимое файла и имя файла в один объект.
Проверяет, были ли привязаны данные файла к форме. Также использует FileExtensionValidator для проверки того, что расширение файла поддерживается 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.
Проверяет, что заданное значение — целое число. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Разрешаются начальные и конечные пробелы, как в функции 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки. 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
Пустое значение: [] (пустой список)
Нормализуется до: Список строк.
Проверяет, что каждое значение в заданном списке значений существует в списке вариантов.
Ключи сообщений об ошибках: 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Использует RegexValidator для проверки, соответствует ли заданное значение определённому регулярному выражению.
Ключи сообщений об ошибках: required, invalid

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

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

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

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

`SlugField`

class SlugField(**kwargs) [source]

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

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

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

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

`TimeField`

class TimeField(**kwargs) [source]

Поле по умолчанию: TimeInput
Пустое значение: 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Использует URLValidator для проверки того, что заданное значение является допустимым 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
Пустое значение: '' (пустая строка)
Нормализуется до: Строки.
Проверяет заданное значение на соответствие каждому из полей, указанных в качестве аргумента к 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, **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().__init__(
            error_messages=error_messages, fields=fields,
            require_all_fields=False, **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().__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

По умолчанию виджет 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__() модели будет вызываться для генерации строковых представлений объектов для использования в вариантах выбора поля. Чтобы обеспечить настраиваемые представления, следует создать подкласс 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())
Нормализуется в: Набор экземпляров модели.
Проверяет, что каждый id в заданном списке значений существует в наборе запросов.
Ключи сообщений об ошибках: 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/2.1/ref/forms/fields/

Поля форм

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

Требовательность

Метка

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

Исходное значение

Виджет

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

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

Валидаторы

Локализация

Отключено

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

Изменено

Встроенные классы полей

Поле булевого типа

Поле символьной строки

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

Создание настраиваемых полей

`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`