Поля формы¶

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

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

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

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

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

Аргументы по основному полю¶

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

`required`¶

Field.required¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если поле содержит текст подсказки и виджет не отображается в <fieldset>, к <input> добавляется aria-describedby, чтобы связать его с текстом подсказки:

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

Changed in Django 5.0:

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

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

В разделе built-in Field classes ниже каждый Field определяет ключи сообщения об ошибке, которые он использует.

`validators`¶

Field.validators¶

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

Более подробную информацию см. в validators documentation.

`localize`¶

Field.localize¶

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

Для получения дополнительной информации см. документацию format localization.

`disabled`¶

Field.disabled¶

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

`template_name`¶

Field.template_name¶

New in Django 5.0.

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

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

`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¶: Либо iterable из 2-кортежей для использования в качестве вариантов для данного поля, enumeration type, либо вызываемый объект, возвращающий такой итерабельный объект. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. Более подробную информацию см. в model field reference documentation on choices. Если аргумент является вызываемым, он оценивается каждый раз при инициализации формы поля, а также во время рендеринга. По умолчанию используется пустой список.

Тип выбора

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

Changed in Django 5.0:

Добавлена поддержка сопоставлений и использования enumeration types непосредственно в choices.

`DateField`¶

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

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

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

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

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

`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, если локализация отключена. См. также format localization.

`DecimalField`¶

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

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

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

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

max_value¶

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

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

decimal_places¶: Максимально допустимое количество знаков после запятой.

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

`DurationField`¶

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

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

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

`EmailField`¶

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

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

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

Changed in Django 3.2.20:

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

`FileField`¶

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

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

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

Чтобы узнать больше об объекте UploadedFile, смотрите file uploads documentation.

Когда вы используете FileField в форме, вы также должны помнить о bind the file data to the form.

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

`FilePathField`¶

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

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

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

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

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

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

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

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

`FloatField`¶

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

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

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

max_value¶

min_value¶: Они управляют диапазоном значений, допустимых в поле.

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

`GenericIPAddressField`¶

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

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

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

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

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

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

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

`ImageField`¶

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

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

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

Когда вы используете ImageField на форме, вы также должны помнить о bind the file data to the form.

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

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

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

`IntegerField`¶

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

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

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

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

max_value¶

min_value¶: Они управляют диапазоном значений, допустимых в поле.

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

`JSONField`¶

class JSONField(encoder=None, decoder=None, **kwargs)[исходный код]¶

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

Виджет по умолчанию: Textarea
Пустое значение: None
Нормализуется до: Python-представление значения JSON (обычно в виде 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.JSONDencoder.

Примечание

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

`SlugField`¶

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

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

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

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

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

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

`TimeField`¶

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

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

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

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

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

`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¶: New in Django 5.0.

Схема, используемая для URL-адресов, не имеющих такой схемы. По умолчанию принимается значение "http". Например, если assume_scheme - это "https", а предоставленное значение - "example.com", то нормализованное значение будет "https://example.com".

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

`UUIDField`¶

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

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

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

Немного сложные встроенные `Field` классы¶

`ComboField`¶

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

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

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

fields¶

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

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

`MultiValueField`¶

class MultiValueField(fields=(), **kwargs)[исходный код]¶

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

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

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

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

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

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

require_all_fields¶

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

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

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

from django.core.validators import RegexValidator


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

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

compress(data_list)[исходный код]¶

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

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

`SplitDateTimeField`¶

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

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

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

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

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

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

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

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

Для представления отношений между моделями доступны два поля: ModelChoiceField и ModelMultipleChoiceField. Оба эти поля требуют одного параметра queryset, который используется для создания вариантов для поля. При проверке формы эти поля помещают либо один объект модели (в случае ModelChoiceField), либо несколько объектов модели (в случае ModelMultipleChoiceField) в словарь cleaned_data формы.

Для более сложного использования можно указать queryset=None при объявлении поля формы и затем заполнить queryset в методе __init__() формы:

class FooMultipleChoiceForm(forms.Form):
    foo_select = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["foo_select"].queryset = ...

И ModelChoiceField, и ModelMultipleChoiceField имеют атрибут iterator, который определяет класс, используемый для итерации по набору запросов при генерации вариантов. Подробности см. в разделе Итерация выбора отношений.

`ModelChoiceField`¶

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

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

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

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

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

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

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

empty_label¶

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

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

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

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

to_field_name¶

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

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

будет давать:

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

и:

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

будет давать:

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

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

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

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

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

from django.forms import ModelChoiceField


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

`ModelMultipleChoiceField`¶

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

Виджет по умолчанию: SelectMultiple
Пустое значение: Пустое QuerySet (self.queryset.none())
Нормализуется до: A 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-* attributes к элементам <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 как:

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

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

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)¶

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

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

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

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

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

`ModelChoiceIteratorValue`¶

class ModelChoiceIteratorValue(value, instance)¶

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

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

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

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

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

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

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

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

API форм

Функции формы модели

Вернуться на верх

Поля формы¶

Аргументы по основному полю¶

required¶

label¶

label_suffix¶

initial¶

widget¶

help_text¶

error_messages¶

validators¶

localize¶

disabled¶

template_name¶

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

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¶

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

Django 5.0

Содержание

Дополнительно

Вы здесь:

`required`¶

`label`¶

`label_suffix`¶

`initial`¶

`widget`¶

`help_text`¶

`error_messages`¶

`validators`¶

`localize`¶

`disabled`¶

`template_name`¶

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