Поля форм

class Field [исходный код]

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

Field.clean(value) [исходный код]

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

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

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

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

`required`

Field.required

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

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

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

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

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

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

`label`

Field.label

Аргумент label позволяет указать «понятную пользователю» метку этого поля. Она отображается, когда Field выводится в Form.

Как объясняется в разделе Вывод форм в виде HTML, метка Field по умолчанию формируется из имени поля: все символы подчёркивания заменяются пробелами, а первая буква становится заглавной. Укажите label, если метка по умолчанию получается неподходящей.

Ниже приведён полный пример Form, в котором для двух полей реализован label. Чтобы упростить вывод, мы указали auto_id=False:

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label="Your name")
...     url = forms.URLField(label="Your website", required=False)
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<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>

`label_suffix`

Field.label_suffix

Аргумент label_suffix позволяет переопределить label_suffix формы отдельно для каждого поля:

>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")
...
>>> f = ContactForm(label_suffix="?")
>>> print(f)
<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>

`initial`

Field.initial

Аргумент initial позволяет указать начальное значение, используемое при отображении этого Field в несвязанной Form.

Сведения о задании динамических начальных данных см. в описании параметра Form.initial.

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

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="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>

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

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

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

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

`help_text`

Field.help_text

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

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

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

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text="100 characters max.")
...     message = forms.CharField()
...     sender = forms.EmailField(help_text="A valid email address, please.")
...     cc_myself = forms.BooleanField(required=False)
...
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f)
<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>

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

`error_messages`

Field.error_messages

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

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

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

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

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

`validators`

Field.validators

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

Дополнительные сведения см. в документации по валидаторам.

`localize`

Field.localize

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

Дополнительные сведения см. в документации по локализации форматов.

`disabled`

Field.disabled

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

`template_name`

Field.template_name

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

`bound_field_class`

Field.bound_field_class

Добавлено в Django 5.2.

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

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

`has_changed()`

Field.has_changed() [исходный код]

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

Дополнительные сведения см. в Form.has_changed.

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

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

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

`BooleanField`

class BooleanField(**kwargs) [исходный код]

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

Примечание

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

`CharField`

class CharField(**kwargs) [исходный код]

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

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

max_length

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

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

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

`ChoiceField`

class ChoiceField(**kwargs) [исходный код]

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

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

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

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

Тип вариантов

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

`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. Если задано step_size, использует StepValueValidator. Пробелы в начале и в конце игнорируются.
Ключи сообщений об ошибках: 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, раздел 3).

`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. Если задано step_size, использует StepValueValidator. Пробелы в начале и в конце допускаются, как и в функции 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, max_length

Нормализация адресов IPv6 следует разделу 2.2 RFC 4291, раздел 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, отображённые в IPv6, например ::ffff:192.0.2.1. Если этот параметр включён, такой адрес будет распакован до 192.0.2.1. По умолчанию отключён. Может использоваться только если protocol установлен в 'both'.

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

`ImageField`

class ImageField(**kwargs) [исходный код]

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

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

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

После очистки и проверки поля объект UploadedFile получит дополнительный атрибут image, содержащий экземпляр Image из Pillow, использованный для проверки корректности изображения. После проверки изображения 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. Допускаются пробелы в начале и конце, как и в функции int() языка Python.
Ключи сообщений об ошибках: 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, который на самом деле был строкой, случайно оказавшейся в том же формате, что и формат для datetimes.

Для проверки входных данных можно использовать 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: Логическое значение, указывающее, должно ли поле принимать буквы Юникода наряду с буквами 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: Схема, предполагаемая для URL, в которых она не указана. По умолчанию — "https". Например, если assume_scheme имеет значение "https", а заданное значение — "example.com", нормализованным значением будет "https://example.com".

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

Для подкласса MultiValueField можно задать сообщение об ошибке incomplete по умолчанию или определить отдельные сообщения для каждого поля. Например:

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, который используется для создания вариантов выбора. При проверке формы эти поля помещают в словарь cleaned_data формы либо один объект модели (в случае ModelChoiceField), либо несколько объектов модели (в случае ModelMultipleChoiceField).

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

`ModelChoiceField`

class ModelChoiceField(**kwargs) [исходный код]

Виджет по умолчанию: Select
Пустое значение: None
Нормализуется до: экземпляра модели.
Проверяет, что заданный идентификатор существует в queryset.
Ключи сообщений об ошибках: 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) [исходный код]

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

`ModelChoiceIterator`

class ModelChoiceIterator(field) [исходный код]

Класс по умолчанию, назначаемый атрибуту iterator полей ModelChoiceField и ModelMultipleChoiceField. Итерируемый объект, выдающий варианты выбора в виде 2-элементных кортежей из queryset.

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

field: Экземпляр ModelChoiceField или ModelMultipleChoiceField, по которому выполняется перебор для выдачи вариантов выбора.

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

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

`ModelChoiceIteratorValue`

class ModelChoiceIteratorValue(value, instance) [исходный код]

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

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

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

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

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

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

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

Также можно настроить способ доступа к полю, переопределив bound_field_class, или переопределить Field.get_bound_field(), если для создания BoundField нужна большая гибкость:

Field.get_bound_field(form, field_name) [исходный код]: Принимает экземпляр Form и имя поля. Возвращённый экземпляр BoundField будет использоваться при обращении к полю в шаблоне.

Примеры переопределения BoundField см. в разделе Настройка BoundField.

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

Поля форм

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

required

label

label_suffix

initial

widget

help_text

error_messages

validators

localize

disabled

template_name

bound_field_class

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

has_changed()

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

BooleanField

CharField

ChoiceField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FilePathField

FloatField

GenericIPAddressField

ImageField

IntegerField

JSONField

MultipleChoiceField

NullBooleanField

RegexField

SlugField

TimeField

TypedChoiceField

TypedMultipleChoiceField

URLField

UUIDField

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

ComboField

MultiValueField

SplitDateTimeField

Поля для работы со связями

ModelChoiceField

ModelMultipleChoiceField

Перебор вариантов выбора для связей

ModelChoiceIterator

ModelChoiceIteratorValue

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

`required`

`label`

`label_suffix`

`initial`

`widget`

`help_text`

`error_messages`

`validators`

`localize`

`disabled`

`template_name`

`bound_field_class`

`has_changed()`

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

`BooleanField`

`CharField`

`ChoiceField`

`DateField`

`DateTimeField`

`DecimalField`

`DurationField`

`EmailField`

`FileField`

`FilePathField`

`FloatField`

`GenericIPAddressField`

`ImageField`

`IntegerField`

`JSONField`

`MultipleChoiceField`

`NullBooleanField`

`RegexField`

`SlugField`

`TimeField`

`TypedChoiceField`

`TypedMultipleChoiceField`

`URLField`

`UUIDField`

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

`ComboField`

`MultiValueField`

`SplitDateTimeField`

`ModelChoiceField`

`ModelMultipleChoiceField`

`ModelChoiceIterator`

`ModelChoiceIteratorValue`