Поля форм

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

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

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

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

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

Изменено

Field.has_changed()

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

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

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

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

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

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

class BooleanField(**kwargs)

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

Примечание

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

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

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

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

`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 в случае включения локализации. Также см. локализация форматов.

`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 в случае включения локализации. Также см. локализация форматов.

Изменено в Django 3.1:

Добавлена поддержка разбора строк даты в формате ISO 8601 (включая необязательную временную зону).

Добавлена поддержка обратного соответствия на DATE_INPUT_FORMATS в значениях по умолчанию input_formats.

`DecimalField`

class DecimalField(**kwargs)

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

Значение по умолчанию виджета: TextInput
Пустое значение: None
Нормализуется до: 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 можно найти в документации по загрузке файлов.

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

Ошибка 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’s float() функции.
Ключи сообщений об ошибках: required, invalid, max_value, min_value

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

`ImageField`

class ImageField(**kwargs)

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

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

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

После очистки и проверки поля, объект 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)

Новое в Django 3.1.

Поле, принимающее закодированные в 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, который на самом деле был строкой, которая просто оказалась в том же формате, который выбран для datetime.

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

По умолчанию json.JSONDecoder.

Примечание

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

Формы для пользователя

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

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

`MultipleChoiceField`

class MultipleChoiceField(**kwargs)

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

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

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

`TypedMultipleChoiceField`

class TypedMultipleChoiceField(**kwargs)

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

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

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

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

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

`SlugField`

class SlugField(**kwargs)

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

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

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

allow_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 ключа, если локализация включена. См. также форматирование локализации.

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

Slightly complex built-in `Field` classes

`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

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

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

`ModelMultipleChoiceField`

class ModelMultipleChoiceField(**kwargs)

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

Устаревшее с версии 3.1: Сообщение list устарело, используйте invalid_list вместо него.

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

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

При итерации ModelChoiceIterator возвращает пары кортежей с выбором, содержащие экземпляры ModelChoiceIteratorValue в качестве первого value элемента каждого выбора. ModelChoiceIteratorValue оборачивает значение выбора, сохраняя при этом ссылку на исходный экземпляр модели, которую можно использовать в реализации пользовательских виджетов, например, для добавления атрибутов data-* к <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 Pizza.topping для каждого <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 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. Итерируемый объект, который возвращает пары кортежей с выбором из набора результатов запроса.

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

field: Экземпляр ModelChoiceField или ModelMultipleChoiceField для итерации и возвращения выбора.

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

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

Изменено в Django 3.1:
В более ранних версиях первый value элемент в кортеже выбора — это само значение field, а не экземпляр ModelChoiceIteratorValue. В большинстве случаев это прозрачно, но если вам нужно само значение field, используйте атрибут ModelChoiceIteratorValue.value вместо этого.

`ModelChoiceIteratorValue`

class ModelChoiceIteratorValue(value, instance)

Новое в Django 3.1.

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

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().

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

Поля форм

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

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

Метка

Приставка к метке

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

Виджет

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

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

Валидаторы

Локализация

Отключено

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

Изменено

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

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

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

ChoiceField

TypedChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

ImageField

IntegerField

JSONField

GenericIPAddressField

MultipleChoiceField

TypedMultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

URLField

UUIDField

Slightly complex built-in Field classes

ComboField

MultiValueField

SplitDateTimeField

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

ModelChoiceField

ModelMultipleChoiceField

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

ModelChoiceIterator

ModelChoiceIteratorValue

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

`ChoiceField`

`TypedChoiceField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FilePathField`

`FloatField`

`ImageField`

`IntegerField`

`JSONField`

`GenericIPAddressField`

`MultipleChoiceField`

`TypedMultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`URLField`

`UUIDField`

Slightly complex built-in `Field` classes

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`

`ModelChoiceIterator`

`ModelChoiceIteratorValue`