Поля форм

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

У виджетов обязательных полей формы есть атрибут required HTML. Установите атрибут 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>

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

`widget`

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

`help_text`

Field.help_text

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

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

Вот полный пример Form, который реализует help_text для двух его полей. Мы задали auto_id=False для упрощения вывода:

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text='100 characters max.')
...     message = forms.CharField()
...     sender = forms.EmailField(help_text='A valid email address, please.')
...     cc_myself = forms.BooleanField(required=False)
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>

`error_messages`

Field.error_messages

Аргумент error_messages позволяет переопределить сообщения по умолчанию, которые будет выдавать поле. Передайте словарь с ключами, соответствующими сообщениям об ошибках, которые вы хотите переопределить. Например, вот сообщение об ошибке по умолчанию:

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

А вот настраиваемое сообщение об ошибке:

>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})
>>> name.clean('')
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

В разделе «Встроенные классы полей» ниже каждый Field определяет используемые ключи сообщений об ошибках.

`validators`

Field.validators

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

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

`localize`

Field.localize

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

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

`disabled`

Field.disabled

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

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

`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: Либо итерируемый объект из 2-кортежей, используемых в качестве вариантов для данного поля, перечисление вариантов или вызываемый объект, который возвращает такой итерируемый объект. Этот аргумент принимает такие же форматы, как аргумент 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 ключа, если локализация включена. См. также локализация форматов.

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

`DecimalField`

class DecimalField(**kwargs)

По умолчанию виджет: NumberInput, когда Field.localize равно False, иначе TextInput.
Пустое значение: None
Нормализуется до: Python decimal.
Проверяет, что заданное значение является десятичным. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Использует StepValueValidator, если step_size задан. Пробелы в начале и конце значения игнорируются.
Ключи сообщений об ошибках: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size.

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

step_size: Ограничение допустимых значений до целого кратного step_size.

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

Добавлен аргумент step_size.

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

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

max_value

min_value: Эти параметры контролируют диапазон допустимых значений в поле.

step_size: Новое в Django 4.1.

Ограничивает допустимые входные данные целым кратным значению step_size.

`GenericIPAddressField`

class GenericIPAddressField(**kwargs)

Поле, содержащее IP-адрес версии 4 или 6.

Значение по умолчанию виджета: 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 в форме, также необходимо привязать данные файла к форме.

После очистки и проверки поля объект 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 integer.
Проверяет, что заданное значение является целым числом. Использует MaxValueValidator и MinValueValidator, если max_value и min_value заданы. Использует StepValueValidator, если step_size задано. Разрешает начальные и конечные пробелы, как в функции Python int().
Ключи сообщений об ошибках: required, invalid, max_value, min_value, step_size

Сообщения об ошибках max_value, min_value и step_size могут содержать %(limit_value)s, которое будет заменено соответствующим пределом.

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

max_value

min_value: Эти параметры контролируют диапазон допустимых значений в поле.

step_size: Новое в Django 4.1.

Ограничивает допустимые входные данные целым кратным значению step_size.

`JSONField`

class JSONField(encoder=None, decoder=None, **kwargs)

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

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

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

encoder

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

Значение по умолчанию: json.JSONEncoder.

decoder

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

Декодер может использоваться для проверки входных данных. Если при десериализации возникает исключение json.JSONDecodeError, то будет возбуждено исключение ValidationError.

Значение по умолчанию: json.JSONDecoder.

Примечание

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

`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 при включённой локализации. См. также форматирование локализации.

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

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

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

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

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

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

empty_label

По умолчанию виджет <select>, используемый ModelChoiceField, будет иметь пустой выбор в верхней части списка. Вы можете изменить текст этого метки (по умолчанию "---------") с помощью атрибута empty_label, или полностью отключить пустую метку, установив empty_label в None.

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

Обратите внимание, что пустой выбор не создается (независимо от значения empty_label), если требуется 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

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

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

`ModelMultipleChoiceField`

class ModelMultipleChoiceField(**kwargs)

Значение по умолчанию виджета: SelectMultiple
Пустое значение: пустой список (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.

Итерация по выборам связей

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

При итерации ModelChoiceIterator возвращает пары значений, содержащие экземпляры ModelChoiceIteratorValue в качестве первого элемента каждого варианта. 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 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 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.

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

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

Поля форм

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

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

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

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