Поля форм

class Field(**kwargs)

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

Field.clean(value)

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

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

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

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

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

Field.required

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

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

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

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

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

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

Метка

Field.label

Аргумент label позволяет указать "человеко-понятную" метку для этого поля. Она используется при отображении поля в 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="http://")
...     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="http://" 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": "http://"}
>>> 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="http://" 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>

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

Также обратите внимание, что значения initial не используются в качестве "резервных" данных при валидации, если значение конкретного поля не указано. Значения initial только предназначены для начального отображения формы:

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="http://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fall back to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}

Вместо константы вы также можете передать любой вызываемый объект:

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
...
>>> print(DateForm())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>

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

Аргумент 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>

Когда у поля есть текст справки, а виджет не отображается в <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>

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

aria-describedby был добавлен, чтобы связать help_text с его вводом.

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

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

Новое в Django 5.0.

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

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

Изменилось ли

Field.has_changed()

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

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

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

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

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

`BooleanField`

class BooleanField(**kwargs)

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

Примечание

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

`CharField`

class CharField(**kwargs)

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

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

max_length

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

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

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

`ChoiceField`

class ChoiceField(**kwargs)

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

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

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

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

Тип выбора

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

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

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

`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. Аргумент max_length по умолчанию равен 320 (см. RFC 3696#section-3).

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

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

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

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

`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 или из 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, и еще один аргумент:

assume_scheme: Новое в Django 5.0.

Схема, предполагаемая для 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)

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

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

empty_label

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

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

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

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

queryset: Аналогично ModelChoiceField.queryset.

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

to_field_name: Аналогично ModelChoiceField.to_field_name.

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

iterator: Аналогично ModelChoiceField.iterator.

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

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

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

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

from django.db import models


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

    def __str__(self):
        return self.name


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

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

from django import forms


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


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

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

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

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

`ModelChoiceIterator`

class ModelChoiceIterator(field)

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

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

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

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

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

`ModelChoiceIteratorValue`

class ModelChoiceIteratorValue(value, instance)

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

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

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

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

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

Создание настраиваемых полей

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

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

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

Поля форм

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

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

Метка

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

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

Виджет

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

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

Валидаторы

Локализация

Отключено

Имя шаблона

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

Изменилось ли

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

BooleanField

CharField

ChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

GenericIPAddressField

ImageField

IntegerField

JSONField

MultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

TypedChoiceField

TypedMultipleChoiceField

URLField

UUIDField

Несколько сложные встроенные Field классы

ComboField

MultiValueField

SplitDateTimeField

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

ModelChoiceField

ModelMultipleChoiceField

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

ModelChoiceIterator

ModelChoiceIteratorValue

Создание настраиваемых полей

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

`BooleanField`

`CharField`

`ChoiceField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FilePathField`

`FloatField`

`GenericIPAddressField`

`ImageField`

`IntegerField`

`JSONField`

`MultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`TypedChoiceField`

`TypedMultipleChoiceField`

`URLField`

`UUIDField`

Несколько сложные встроенные `Field` классы

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`

`ModelChoiceIterator`

`ModelChoiceIteratorValue`