Поля форм

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

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

Метка

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)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>

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

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)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>

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

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="https://")
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>

Вы можете подумать, почему бы просто не передать словарь начальных значений как данные при отображении формы? Ну, если вы сделаете это, вы запустите проверку, и в выходных данных HTML будут включены любые ошибки проверки:

>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
...
>>> default_data = {"name": "Your name", "url": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
  <input type="text" name="name" value="Your name" required>
</div>
<div>Url:
  <ul class="errorlist"><li>Enter a valid URL.</li></ul>
  <input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
  <ul class="errorlist"><li>This field is required.</li></ul>
  <input type="text" name="comment" required aria-invalid="true">
</div>

Вот почему начальные значения отображаются только для несвязанных форм. Для связанных форм выходные данные HTML будут использовать привязанные данные.

Также обратите внимание, что начальные значения не используются как «падение» данные при проверке, если значение конкретного поля не задано. Начальные значения только предназначены для начального отображения формы:

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback 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())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>

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

Виджет

Field.widget

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

Текст помощи

Field.help_text

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

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

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

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

Когда у поля есть текст помощи, он ассоциируется со своим вводом с помощью атрибута aria-describedby HTML. Если виджет отображается в <fieldset>, то aria-describedby добавляется к этому элементу, иначе он добавляется к <input> виджета:

>>> from django import forms
>>> class UserForm(forms.Form):
...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>

При добавлении пользовательского атрибута aria-describedby, убедитесь, что также включен id элемента help_text (если используется) в желаемой последовательности. Для пользователей с экраном чтения описания будут читаться в порядке их появления внутри aria-describedby:

>>> class UserForm(forms.Form):
...     username = forms.CharField(
...         max_length=255,
...         help_text="e.g., user@example.com",
...         widget=forms.TextInput(
...             attrs={"aria-describedby": "custom-description id_username_helptext"},
...         ),
...     )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>

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

Field.error_messages

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

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

И вот пользовательское сообщение об ошибке:

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

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

Валидаторы

Field.validators

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

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

Локализация

Field.localize

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

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

Отключено

Field.disabled

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

Имя шаблона

Field.template_name

Аргумент template_name позволяет использовать пользовательский шаблон, когда поле отображается с помощью as_field_group(). По умолчанию это значение установлено в "django/forms/field.html". Может быть изменено для каждого поля, переопределяя этот атрибут, или, в более общем плане, переопределяя шаблон по умолчанию, см. также Переопределение встроенных шаблонов полей.

Класс связанного поля

Field.bound_field_class

Атрибут bound_field_class позволяет переопределить Form.bound_field_class на уровне поля.

has_changed()

Field.has_changed() [source]

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

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

BooleanField

class BooleanField(**kwargs) [source]

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

Примечание

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

CharField

class CharField(**kwargs) [source]

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

Разрешает следующие необязательные аргументы для валидации:

max_length

min_length

Если указаны, эти аргументы гарантируют, что строка имеет максимальную или минимальную длину.

strip

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

empty_value

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

ChoiceField

class ChoiceField(**kwargs) [source]

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

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

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

choices [source]

Список 2-кортежей, используемых в качестве вариантов для этого поля, тип перечисления или вызываемый объект, возвращающий такой список. Этот аргумент принимает те же форматы, что и аргумент choices поля модели. См. документацию о вариантах поля модели для получения более подробной информации. Если аргумент является вызываемым объектом, он оценивается каждый раз при инициализации формы поля, а также во время рендеринга. По умолчанию – пустой список.

Тип варианта

Это поле нормализует варианты к строкам, поэтому, если варианты необходимы в других типах данных, таких как целые числа или булевы значения, рассмотрите использование TypedChoiceField вместо него.

DateField

class DateField(**kwargs) [source]

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

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

input_formats

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

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

DateTimeField

class DateTimeField(**kwargs) [source]

• Виджет по умолчанию: 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, или из DATETIME_INPUT_FORMATS и DATE_INPUT_FORMATS, если локализация отключена. См. также локализация форматов.

DecimalField

class DecimalField(**kwargs) [source]

• По умолчанию виджет: 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. Если min_value также задано, оно добавляется в качестве смещения для определения соответствия шага.

DurationField

class DurationField(**kwargs) [source]

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

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

EmailField

class EmailField(**kwargs) [source]

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

Имеет необязательные аргументы max_length, min_length и empty_value, которые работают так же, как и для CharField. Аргумент max_length по умолчанию равен 320 (см. RFC 3696 Раздел 3).

FileField

class FileField(**kwargs) [source]

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

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

Дополнительную информацию об объекте UploadedFile см. в документации по загрузке файлов.

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

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

FilePathField

class FilePathField(**kwargs) [source]

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

Поле позволяет выбирать файлы в определенной директории. Оно принимает пять дополнительных аргументов; только path является обязательным:

path

Абсолютный путь к директории, содержимое которой вы хотите перечислить. Эта директория должна существовать.

recursive

Если False (по умолчанию), только непосредственное содержимое path будет предложено в качестве вариантов. Если True, директория будет рекурсивно пройдена и все поддиректории будут перечислены как варианты.

match

Шаблон регулярного выражения; только файлы с именами, соответствующими этому выражению, будут разрешены в качестве вариантов.

allow_files

Необязательно. Либо True, либо False. По умолчанию True. Указывает, должны ли файлы в указанном месте включаться в список. Либо это, либо allow_folders должно быть True.

allow_folders

Необязательно. Либо True, либо False. По умолчанию False. Указывает, должны ли папки в указанном месте включаться в список. Либо это, либо allow_files должно быть True.

FloatField

class FloatField(**kwargs) [source]

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

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

max_value

min_value

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

step_size

Ограничивает допустимые вводы целочисленными кратными значению step_size. Если min_value также задан, он добавляется как смещение для определения соответствия шагу.

GenericIPAddressField

class GenericIPAddressField(**kwargs) [source]

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

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

Нормализация адресов IPv6 следует Разделу 2.2 RFC 4291, включая использование формата 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'.

max_length

По умолчанию 39 и ведет себя так же, как и для CharField.

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

Значение по умолчанию для max_length было установлено в 39 символов.

ImageField

class ImageField(**kwargs) [source]

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

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

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

После очистки и проверки поля, объект UploadedFile будет иметь дополнительный атрибут image, содержащий экземпляр Pillow Image, используемый для проверки, являлся ли файл допустимым изображением. 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) [source]

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

Ограничивает допустимые вводы целочисленными кратными значению step_size. Если min_value также задан, он добавляется как смещение для определения соответствия шагу.

JSONField

class JSONField(encoder=None, decoder=None, **kwargs) [source]

Поле, которое принимает данные, закодированные в формате 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) [source]

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

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

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

NullBooleanField

class NullBooleanField(**kwargs) [source]

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

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

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

RegexField

class RegexField(**kwargs) [source]

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

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

regex

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

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

strip

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

SlugField

class SlugField(**kwargs) [source]

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

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

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

allow_unicode

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

empty_value

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

TimeField

class TimeField(**kwargs) [source]

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

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

input_formats

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

Если аргумент input_formats не указан, значения по умолчанию берутся из активного формата локализации по ключу TIME_INPUT_FORMATS или из TIME_INPUT_FORMATS при отключенной локализации. Также см. локализацию форматов.

TypedChoiceField

class TypedChoiceField(**kwargs) [source]

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

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

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

coerce

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

empty_value

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

TypedMultipleChoiceField

class TypedMultipleChoiceField(**kwargs) [source]

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

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

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

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

URLField

class URLField(**kwargs) [source]

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

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

assume_scheme

Схема, предполагаемая для URL без неё. По умолчанию "http". Например, если assume_scheme — "https", а заданное значение — "example.com", нормализованное значение будет "https://example.com".

Устарело начиная с версии 5.0: Значение по умолчанию для assume_scheme изменится с "http" на "https" в Django 6.0. Установите переходную настройку FORMS_URLFIELD_ASSUME_HTTPS в True, чтобы использовать "https" в цикле выпуска Django 5.x.

UUIDField

class UUIDField(**kwargs) [source]

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

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

ComboField

class ComboField(**kwargs) [source]

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

Требуется один дополнительный аргумент:

fields

Список полей, которые должны использоваться для проверки значения поля (в порядке их предоставления).

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean("test@example.com")
'test@example.com'
>>> f.clean("longemailaddress@example.com")
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

MultiValueField

class MultiValueField(fields=(), **kwargs) [source]

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

Агрегирует логику нескольких полей, которые вместе создают одно значение.

Это абстрактное поле и требует подклассирования. В отличие от полей с одиночным значением, подклассы MultiValueField не должны реализовывать clean(), а вместо этого - compress().

Требуется один дополнительный аргумент:

fields

Кортеж полей, значения которых очищаются и затем объединяются в одно значение. Каждое значение поля очищается соответствующим полем в fields – первое значение очищается первым полем, второе значение – вторым полем и т. д. После очистки всех полей список очищенных значений объединяется в одно значение с помощью compress().

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

require_all_fields

По умолчанию True, в этом случае будет поднята ошибка валидации required, если для какого-либо поля не указано значение.

При установке в False, атрибут Field.required можно установить в False для отдельных полей, чтобы сделать их необязательными. Если для требуемого поля не указано значение, будет поднята ошибка валидации incomplete.

Стандартное сообщение об ошибке incomplete можно определить в подклассе MultiValueField, или можно определить разные сообщения для каждого поля. Например:

from django.core.validators import RegexValidator


class PhoneField(MultiValueField):
    def __init__(self, **kwargs):
        # Define one message for all fields.
        error_messages = {
            "incomplete": "Enter a country calling code and a phone number.",
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={"incomplete": "Enter a country calling code."},
                validators=[
                    RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."),
                ],
            ),
            CharField(
                error_messages={"incomplete": "Enter a phone number."},
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")],
            ),
            CharField(
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")],
                required=False,
            ),
        )
        super().__init__(
            error_messages=error_messages,
            fields=fields,
            require_all_fields=False,
            **kwargs
        )

widget

Должен быть подклассом django.forms.MultiWidget. Значение по умолчанию – TextInput, что, вероятно, не очень полезно в этом случае.

compress(data_list) [source]

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

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

SplitDateTimeField

class SplitDateTimeField(**kwargs) [source]

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

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

input_date_formats

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

Если аргумент input_date_formats не предоставлен, используются стандартные форматы ввода для DateField.

input_time_formats

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

Если аргумент input_time_formats не предоставлен, используются стандартные форматы ввода для TimeField.

ModelChoiceField

class ModelChoiceField(**kwargs) [source]

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

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

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

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

queryset

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) [source]

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

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

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

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

queryset

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

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

to_field_name

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

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

iterator

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

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

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

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