Поля формы¶

class Field(**kwargs)[исходный код]¶

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

Field.clean(value)[исходный код]¶

Хотя основной способ использования классов Field - это классы Form, вы также можете инстанцировать их и использовать напрямую, чтобы лучше понять, как они работают. Каждый экземпляр Field имеет метод clean(), который принимает один аргумент и либо вызывает исключение django.core.exceptions.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 это вернет empty_value, которое по умолчанию будет пустой строкой. Для других классов Field это может быть None. (Это зависит от конкретного поля).

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

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

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

`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" 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']

В разделе built-in Field classes ниже каждый Field определяет ключи сообщения об ошибке, которые он использует.

`validators`¶

Field.validators¶

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

Более подробную информацию см. в validators documentation.

`localize`¶

Field.localize¶

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

Для получения дополнительной информации см. документацию format localization.

`disabled`¶

Field.disabled¶

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

Проверка, изменились ли данные поля¶

`has_changed()`¶

Field.has_changed()[исходный код]¶

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

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

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

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

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

`BooleanField`¶

class BooleanField(**kwargs)[исходный код]¶

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

Примечание

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

`CharField`¶

class CharField(**kwargs)[исходный код]¶

Виджет по умолчанию: 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)[исходный код]¶

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

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

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

choices¶: Либо iterable из 2-кортежей, которые будут использоваться в качестве вариантов для этого поля, либо enumeration вариантов, либо итерабель, возвращающая такую итерабель. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. Более подробную информацию см. в model field reference documentation on choices. Если аргумент является вызываемой переменной, он оценивается каждый раз при инициализации формы поля, а также во время рендеринга. По умолчанию используется пустой список.

`DateField`¶

class DateField(**kwargs)[исходный код]¶

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

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

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

Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из DATE_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали DATE_INPUT_FORMATS, если локализация включена. См. также format localization.

`DateTimeField`¶

class DateTimeField(**kwargs)[исходный код]¶

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

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

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

Поле всегда принимает строки в формате ISO 8601 в виде дат или аналогичных, распознаваемых parse_datetime(). Некоторые примеры:

* '2006-10-25 14:30:59'
* '2006-10-25T14:30:59'
* '2006-10-25 14:30'
* '2006-10-25T14:30'
* '2006-10-25T14:30Z'
* '2006-10-25T14:30+02:00'
* '2006-10-25'

Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из DATETIME_INPUT_FORMATS и DATE_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали DATETIME_INPUT_FORMATS и ключей DATE_INPUT_FORMATS, если локализация включена. См. также format localization.

`DecimalField`¶

class DecimalField(**kwargs)[исходный код]¶

Виджет по умолчанию: NumberInput, если Field.localize - False, иначе TextInput.
Пустое значение: None
Нормализуется до: A 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)[исходный код]¶

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

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

`EmailField`¶

class EmailField(**kwargs)[исходный код]¶

Виджет по умолчанию: EmailInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует EmailValidator для проверки того, что заданное значение является действительным адресом электронной почты, используя умеренно сложное регулярное выражение.
Клавиши сообщений об ошибках: required, invalid

Имеет три необязательных аргумента max_length, min_length и empty_value, которые работают так же, как и для CharField.

`FileField`¶

class FileField(**kwargs)[исходный код]¶

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

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

Чтобы узнать больше об объекте UploadedFile, смотрите file uploads documentation.

Когда вы используете FileField в форме, вы также должны помнить о bind the file data to the form.

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

`FilePathField`¶

class FilePathField(**kwargs)[исходный код]¶

Виджет по умолчанию: Select
Пустое значение: '' (пустая строка).
Нормализуется до: Строка.
Проверяет наличие выбранного варианта в списке вариантов.
Клавиши сообщений об ошибках: 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)[исходный код]¶

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

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

`GenericIPAddressField`¶

class GenericIPAddressField(**kwargs)[исходный код]¶

Поле, содержащее либо 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'.

`ImageField`¶

class ImageField(**kwargs)[исходный код]¶

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

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

Когда вы используете ImageField на форме, вы также должны помнить о bind the file data to the form.

После очистки и проверки поля объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки того, является ли файл действительным изображением. Pillow закрывает базовый дескриптор файла после проверки изображения, поэтому, хотя атрибуты, не относящиеся к данным изображения, такие как format, height и width, доступны, методы, обращающиеся к базовым данным изображения, такие как getdata() или getpixel(), не могут быть использованы без повторного открытия файла. Например:

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
...     img = forms.ImageField()
>>> file_data = {'img': SimpleUploadedFile('test.png', <file data>)}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data['img']
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>

Кроме того, UploadedFile.content_type будет обновлен типом содержимого изображения, если Pillow сможет его определить, в противном случае он будет установлен в None.

`IntegerField`¶

class IntegerField(**kwargs)[исходный код]¶

Виджет по умолчанию: 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¶: Они управляют диапазоном значений, допустимых в поле.

`JSONField`¶

class JSONField(encoder=None, decoder=None, **kwargs)[исходный код]¶

Поле, которое принимает данные в кодировке JSON для JSONField.

Виджет по умолчанию: Textarea
Пустое значение: None
Нормализуется до: Python-представление значения JSON (обычно в виде dict, list или None), в зависимости от JSONField.decoder.
Проверяет, что заданное значение является допустимым JSON.
Клавиши сообщений об ошибках: required, invalid

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

encoder¶

Подкласс json.JSONEncoder для сериализации типов данных, не поддерживаемых стандартным сериализатором JSON (например, datetime.datetime или UUID). Например, вы можете использовать класс DjangoJSONEncoder.

По умолчанию используется json.JSONEncoder.

decoder¶

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

decoder может использоваться для проверки ввода. Если во время десериализации возникает ошибка json.JSONDecodeError, то возникает ошибка ValidationError.

По умолчанию используется json.JSONDencoder.

Примечание

Если вы используете ModelForm, будут использованы encoder и decoder из JSONField.

Удобные для пользователя формы

JSONField в большинстве случаев не очень удобен для пользователя. Однако это полезный способ форматирования данных из виджета на стороне клиента для отправки на сервер.

`MultipleChoiceField`¶

class MultipleChoiceField(**kwargs)[исходный код]¶

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

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

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

`NullBooleanField`¶

class NullBooleanField(**kwargs)[исходный код]¶

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

NullBooleanField можно использовать с такими виджетами, как Select или RadioSelect, предоставив виджет choices:

NullBooleanField(
    widget=Select(
        choices=[
            ('', 'Unknown'),
            (True, 'Yes'),
            (False, 'No'),
        ]
    )
)

`RegexField`¶

class RegexField(**kwargs)[исходный код]¶

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

Принимает один необходимый аргумент:

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

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

strip¶: По умолчанию имеет значение False. Если включено, отсечение будет применяться перед проверкой regex.

`SlugField`¶

class SlugField(**kwargs)[исходный код]¶

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

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

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

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

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

`TimeField`¶

class TimeField(**kwargs)[исходный код]¶

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

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

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

Если аргумент input_formats не указан, форматы ввода по умолчанию берутся из TIME_INPUT_FORMATS, если USE_L10N является False, или из активного формата локали TIME_INPUT_FORMATS, если локализация включена. См. также format localization.

`TypedChoiceField`¶

class TypedChoiceField(**kwargs)[исходный код]¶

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

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

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

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

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

`TypedMultipleChoiceField`¶

class TypedMultipleChoiceField(**kwargs)[исходный код]¶

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

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

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

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

`URLField`¶

class URLField(**kwargs)[исходный код]¶

Виджет по умолчанию: URLInput
Пустое значение: То, что вы указали как empty_value.
Нормализуется до: Строка.
Использует URLValidator для проверки того, что заданное значение является действительным URL.
Клавиши сообщений об ошибках: required, invalid

Имеет три необязательных аргумента max_length, min_length и empty_value, которые работают так же, как и для CharField.

`UUIDField`¶

class UUIDField(**kwargs)[исходный код]¶

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

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

Немного сложные встроенные `Field` классы¶

`ComboField`¶

class ComboField(**kwargs)[исходный код]¶

Виджет по умолчанию: 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)[исходный код]¶

Виджет по умолчанию: 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)[исходный код]¶

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

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

`SplitDateTimeField`¶

class SplitDateTimeField(**kwargs)[исходный код]¶

Виджет по умолчанию: 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, и ModelMultipleChoiceField имеют атрибут iterator, который определяет класс, используемый для итерации по набору запросов при генерации вариантов. Подробности см. в разделе Итерация выбора отношений.

`ModelChoiceField`¶

class ModelChoiceField(**kwargs)[исходный код]¶

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

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

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

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

queryset¶: Объект модели QuerySet>, из которого берутся варианты выбора для поля и который используется для проверки выбора пользователя. Он оценивается при отображении формы.

ModelChoiceField also takes several optional arguments:

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), если ModelChoiceField является обязательным и имеет начальное значение по умолчанию, или widget установлен в RadioSelect, а аргумент blank является False.

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>

blank¶: При использовании виджета RadioSelect этот необязательный булев аргумент определяет, будет ли создан пустой выбор. По умолчанию blank равен False, в этом случае пустой выбор не создается.

ModelChoiceField также имеет атрибут:

iterator¶: Класс итератора, используемый для генерации вариантов полей из queryset. По умолчанию ModelChoiceIterator.

Метод __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

Changed in Django 4.0:

Добавлена поддержка содержания %(value)s в сообщении об ошибке invalid_choice.

`ModelMultipleChoiceField`¶

class ModelMultipleChoiceField(**kwargs)[исходный код]¶

Виджет по умолчанию: SelectMultiple
Пустое значение: Пустое QuerySet (self.queryset.none())
Нормализуется до: A QuerySet экземпляров модели.
Проверяет, что каждый идентификатор из заданного списка значений существует в наборе запросов.
Клавиши сообщений об ошибках: required, invalid_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.

ModelMultipleChoiceField также имеет атрибут:

iterator¶: То же самое, что и ModelChoiceField.iterator.

Итерация выбора отношений¶

По умолчанию ModelChoiceField и ModelMultipleChoiceField используют ModelChoiceIterator для генерации своего поля choices.

При итерации ModelChoiceIterator выдает 2 кортежа выбора, содержащие экземпляры ModelChoiceIteratorValue в качестве первого элемента value в каждом выборе. ModelChoiceIteratorValue оборачивает значение выбора, сохраняя ссылку на исходный экземпляр модели, которая может быть использована в пользовательских реализациях виджетов, например, для добавления data-* attributes к элементам <option>.

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

from django.db import models

class Topping(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(decimal_places=2, max_digits=6)

    def __str__(self):
        return self.name

class Pizza(models.Model):
    topping = models.ForeignKey(Topping, on_delete=models.CASCADE)

Вы можете использовать подкласс виджета Select для включения значения Topping.price в качестве HTML-атрибута data-price для каждого элемента <option>:

from django import forms

class ToppingSelect(forms.Select):
    def create_option(self, name, value, label, selected, index, subindex=None, attrs=None):
        option = super().create_option(name, value, label, selected, index, subindex, attrs)
        if value:
            option['attrs']['data-price'] = value.instance.price
        return option

class PizzaForm(forms.ModelForm):
    class Meta:
        model = Pizza
        fields = ['topping']
        widgets = {'topping': ToppingSelect}

Это отобразит Pizza.topping select как:

<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>

Для более продвинутого использования вы можете подкласс ModelChoiceIterator, чтобы настроить выбор получаемого кортежа.

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)¶

Класс по умолчанию, назначенный атрибуту iterator в ModelChoiceField и ModelMultipleChoiceField. Итерабельность, которая дает выбор из 2 кортежей из набора запросов.

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

field¶: Экземпляр ModelChoiceField или ModelMultipleChoiceField для итерации и получения вариантов.

ModelChoiceIterator имеет следующий метод:

__iter__()¶: Выдает 2 кортежа выбора в формате (value, label), используемом в ChoiceField.choices. Первый элемент value является экземпляром ModelChoiceIteratorValue.

`ModelChoiceIteratorValue`¶

class ModelChoiceIteratorValue(value, instance)¶

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

value¶: Значение выбора. Это значение используется для отображения атрибута value элемента HTML <option>.

instance¶: Экземпляр модели из набора запросов. К этому экземпляру можно обращаться в пользовательских реализациях ChoiceWidget.create_option() для настройки отображаемого HTML.

ModelChoiceIteratorValue имеет следующий метод:

__str__()¶: Возвращает value в виде строки для отображения в HTML.

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

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

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

API форм

Функции формы модели

Вернуться на верх

Поля формы¶

Аргументы по основному полю¶

required¶

label¶

label_suffix¶

initial¶

widget¶

help_text¶

error_messages¶

validators¶

localize¶

disabled¶

Проверка, изменились ли данные поля¶

has_changed()¶

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

BooleanField¶

CharField¶

ChoiceField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FilePathField¶

FloatField¶

GenericIPAddressField¶

ImageField¶

IntegerField¶

JSONField¶

MultipleChoiceField¶

NullBooleanField¶

RegexField¶

SlugField¶

TimeField¶

TypedChoiceField¶

TypedMultipleChoiceField¶

URLField¶

UUIDField¶

Немного сложные встроенные Field классы¶

ComboField¶

MultiValueField¶

SplitDateTimeField¶

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

ModelChoiceField¶

ModelMultipleChoiceField¶

Итерация выбора отношений¶

ModelChoiceIterator¶

ModelChoiceIteratorValue¶

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

Django 4.0

Содержание

Дополнительно

Вы здесь:

`required`¶

`label`¶

`label_suffix`¶

`initial`¶

`widget`¶

`help_text`¶

`error_messages`¶

`validators`¶

`localize`¶

`disabled`¶

`has_changed()`¶

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

`BooleanField`¶

`CharField`¶

`ChoiceField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FilePathField`¶

`FloatField`¶

`GenericIPAddressField`¶

`ImageField`¶

`IntegerField`¶

`JSONField`¶

`MultipleChoiceField`¶

`NullBooleanField`¶

`RegexField`¶

`SlugField`¶

`TimeField`¶

`TypedChoiceField`¶

`TypedMultipleChoiceField`¶

`URLField`¶

`UUIDField`¶

Немного сложные встроенные `Field` классы¶

`ComboField`¶

`MultiValueField`¶

`SplitDateTimeField`¶

`ModelChoiceField`¶

`ModelMultipleChoiceField`¶

`ModelChoiceIterator`¶

`ModelChoiceIteratorValue`¶