Поля форм

class Field [source]

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

Field.clean(value) [source]

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

Метка

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="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* 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>

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

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

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

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

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

aria-describedby был добавлен для ассоциации help_text с его вводом.

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

Добавлена поддержка aria-describedby для <fieldset>.

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

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

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

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

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

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

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

`BooleanField`

class BooleanField(**kwargs) [source]

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

Примечание

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

`CharField`

class CharField(**kwargs) [source]

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

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

max_length

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

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

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

`ChoiceField`

class ChoiceField(**kwargs) [source]

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

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

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

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

Тип выбора

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

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

Была добавлена поддержка отображений и использование типов перечисления непосредственно в choices.

`DateField`

class DateField(**kwargs) [source]

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

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

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

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

`DateTimeField`

class DateTimeField(**kwargs) [source]

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

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

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

Поле всегда принимает строки в формате даты ISO 8601 или похожих, распознаваемых parse_datetime(). Вот некоторые примеры:

'2006-10-25 14:30:59'
'2006-10-25T14:30:59'
'2006-10-25 14:30'
'2006-10-25T14:30'
'2006-10-25T14:30Z'
'2006-10-25T14:30+02:00'
'2006-10-25'

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

`DecimalField`

class DecimalField(**kwargs) [source]

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

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

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

max_value

min_value: Они управляют диапазоном значений, разрешенных в поле, и должны быть заданы как decimal.Decimal.

max_digits: Максимальное количество цифр (перед и после десятичной точки, без учёта ведущих нулей) допустимое в значении.

decimal_places: Максимальное количество десятичных знаков.

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

`DurationField`

class DurationField(**kwargs) [source]

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

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

`EmailField`

class EmailField(**kwargs) [source]

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

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

`FileField`

class FileField(**kwargs) [source]

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

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

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

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

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

`FilePathField`

class FilePathField(**kwargs) [source]

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

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

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

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

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

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

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

`FloatField`

class FloatField(**kwargs) [source]

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

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

max_value

min_value: Они контролируют диапазон значений, разрешенных в поле.

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

`GenericIPAddressField`

class GenericIPAddressField(**kwargs) [source]

Поле, содержащее 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) [source]

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

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

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

После очистки и проверки поля, объект UploadedFile будет иметь дополнительное атрибут image, содержащий экземпляр Pillow Image, используемый для проверки того, что файл является допустимым изображением. Pillow закрывает дескриптор файла после проверки изображения, поэтому, хотя доступны атрибуты, не связанные с изображением, такие как format, height, и width, методы, которые обращаются к данным исходного изображения, такие как getdata() или getpixel(), не могут быть использованы без повторного открытия файла. Например:

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
...     img = forms.ImageField()
...
>>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data["img"]
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>

Кроме того, UploadedFile.content_type будет обновлён с типом контента изображения, если Pillow может определить его, в противном случае он будет установлен в None.

`IntegerField`

class IntegerField(**kwargs) [source]

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

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

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

max_value

min_value: Они контролируют диапазон значений, разрешенных в поле.

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

`JSONField`

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

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

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

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

encoder

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

По умолчанию json.JSONEncoder.

decoder

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

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

По умолчанию json.JSONDecoder.

Примечание

Если используется ModelForm, будут использоваться encoder и decoder из JSONField.

Формы удобные для пользователя

JSONField в большинстве случаев не особенно удобны для пользователя. Однако это полезный способ форматирования данных с клиентского виджета для отправки на сервер.

`MultipleChoiceField`

class MultipleChoiceField(**kwargs) [source]

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

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

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

`NullBooleanField`

class NullBooleanField(**kwargs) [source]

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

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

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

`RegexField`

class RegexField(**kwargs) [source]

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

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

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

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

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

`SlugField`

class SlugField(**kwargs) [source]

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

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

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

allow_unicode: Булево значение, указывающее полю принимать символы Unicode в дополнение к ASCII символам. По умолчанию False.

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

`TimeField`

class TimeField(**kwargs) [source]

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

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

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

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

`TypedChoiceField`

class TypedChoiceField(**kwargs) [source]

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

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

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

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

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

`TypedMultipleChoiceField`

class TypedMultipleChoiceField(**kwargs) [source]

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

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

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

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

`URLField`

class URLField(**kwargs) [source]

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

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

assume_scheme: Новое в 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) [source]

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

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

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

`ComboField`

class ComboField(**kwargs) [source]

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

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

fields

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

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

`MultiValueField`

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

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

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

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

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

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

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

require_all_fields

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

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

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

from django.core.validators import RegexValidator


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

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

compress(data_list) [source]

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

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

`SplitDateTimeField`

class SplitDateTimeField(**kwargs) [source]

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

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

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

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

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

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

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

Для представления отношений между моделями доступны два поля: ModelChoiceField и 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) [source]

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

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

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

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

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

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

empty_label

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

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

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

Обратите внимание, что пустой вариант не создается (независимо от значения empty_label) если ModelChoiceField требуется и имеет значение по умолчанию, или widget задан как RadioSelect и аргумент blank имеет значение False.

to_field_name

Этот необязательный аргумент используется для указания поля, которое будет использоваться в качестве значения вариантов в виджете поля. Убедитесь, что это уникальное поле для модели, иначе выбранное значение может соответствовать более чем одному объекту. По умолчанию он установлен на None, в этом случае используется первичный ключ каждого объекта. Например:

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

что даст:

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

и:

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

что даст:

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

blank: При использовании виджета RadioSelect, этот необязательный булевый аргумент определяет, создается ли пустой вариант. По умолчанию blank имеет значение False, в этом случае пустой вариант не создается.

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

iterator: Класс итератора, используемый для генерации вариантов поля из queryset. По умолчанию, ModelChoiceIterator.

Метод __str__() модели будет вызван для генерации строковых представлений объектов для использования в вариантах поля. Чтобы предоставить настраиваемые представления, подклассифицируйте ModelChoiceField и переопределите label_from_instance. Этот метод получит объект модели и должен вернуть строку, подходящую для его представления. Например:

from django.forms import ModelChoiceField


class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

`ModelMultipleChoiceField`

class ModelMultipleChoiceField(**kwargs) [source]

Значение по умолчанию виджета: 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 возвращает пары кортежей (choices), содержащие экземпляры 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) [source]

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

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

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

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

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

`ModelChoiceIteratorValue`

class ModelChoiceIteratorValue(value, instance) [source]

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

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

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

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

__str__() [source]: Возвращает 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.1/ref/forms/fields/

Поля форм

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

Требование

Метка

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

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

Вьюга

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

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

Валидаторы

Локализация

Отключено

Имя шаблона

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

Изменено

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

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

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

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