Поля форм

class Field(**kwargs)

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

Field.clean(value)

Хотя основной способ использования классов Field — это в классах Form, вы также можете создать их экземпляры и использовать напрямую, чтобы лучше понять их работу. Каждый экземпляр Field имеет метод clean(), который принимает один аргумент и либо вызывает исключение django.core.exceptions.ValidationError, либо возвращает очищенное значение:

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("foo@example.com")
'foo@example.com'
>>> f.clean("invalid email address")
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

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

Каждый конструктор класса Field принимает по меньшей мере эти аргументы. Некоторые классы Field принимают дополнительные аргументы, специфичные для поля, но следующие всегда должны приниматься:

`required`

Field.required

По умолчанию каждый класс Field предполагает, что значение обязательно, поэтому, если вы передадите пустое значение — либо None , либо пустую строку ("") — то clean() вызовет исключение ValidationError:

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(" ")
' '
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

Чтобы указать, что поле не является обязательным, передайте required=False в конструктор Field:

>>> f = forms.CharField(required=False)
>>> f.clean("foo")
'foo'
>>> f.clean("")
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

Если у Field есть required=False и вы передаёте clean() пустое значение, тогда clean() вернёт нормализованное пустое значение, а не вызовет ValidationError. Для CharField, это вернет empty_value, которое по умолчанию является пустой строкой. Для других классов Field, это может быть None. (Это зависит от поля.)

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

`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 не используются как «fallback» данные при валидации, если значение конкретного поля не задано. Значения 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. См. Widgets для получения дополнительной информации.

`help_text`

Field.help_text

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

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

Вот полный пример 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 полей, которые представляют распространённые потребности в валидации. Этот раздел описывает каждое встроенное поле.

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

Поле, содержащее IPv4 или IPv6 адрес.

Значение по умолчанию виджета: TextInput
Пустое значение: '' (пустая строка)
Нормализуется до: Строки. IPv6 адреса нормализуются, как описано ниже.
Проверяет, что заданное значение является корректным IP адресом.
Ключи сообщений об ошибках: required, invalid

Нормализация IPv6 адресов соответствует RFC 4291#section-2.2 раздел 2.2, включая использование IPv4 формата, предложенного в абзаце 3 этого раздела, как ::ffff:192.0.2.0. Например, 2001:0::0:01 нормализуется до 2001::1, и ::ffff:0a0a:0a0a до ::ffff:10.10.10.10. Все символы преобразуются в нижний регистр.

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

protocol: Ограничивает допустимые значения указанным протоколом. Допустимые значения: both (по умолчанию), IPv4 или IPv6. Сопоставление регистронезависимое.

unpack_ipv4: Распаковывает IPv4 адреса, такие как ::ffff:192.0.2.1. Если этот параметр включен, адрес будет распакован до 192.0.2.1. По умолчанию отключен. Может быть использован только при protocol равном 'both'.

`ImageField`

class ImageField(**kwargs)

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

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

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

После очистки и проверки поля, объект 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", b"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 указаны. Использует 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.

decoder может использоваться для валидации ввода. Если во время десериализации возникает 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

`ModelMultipleChoiceField`

class ModelMultipleChoiceField(**kwargs)

Значение по умолчанию виджета: SelectMultiple
Пустое значение: Пустой QuerySet (self.queryset.none())
Нормализуется в: Список экземпляров модели.
Проверяет, что каждый идентификатор в заданном списке значений существует в наборе запросов.
Ключи сообщений об ошибках: required, invalid_list, invalid_choice, invalid_pk_value

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

Позволяет выбрать один или несколько объектов модели, подходящих для представления связи «многие ко многим». Как и в случае с ModelChoiceField, вы можете использовать label_from_instance для настройки отображения объектов.

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

queryset: То же, что и ModelChoiceField.queryset.

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

to_field_name: То же, что и ModelChoiceField.to_field_name.

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

iterator: То же, что и ModelChoiceField.iterator.

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

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

При итерации ModelChoiceIterator возвращает пары значений-описаний, содержащие экземпляры 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__(): Возвращает пары значений-описаний в формате, используемом ChoiceField.choices. Первый элемент - экземпляр 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.2/ref/forms/fields/

Поля форм

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

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

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

has_changed()

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

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

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