Поля формы ¶

классField ( ** kwargs ) ¶

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

Field.clean( значение ) ¶

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

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

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

Каждый конструктор класса 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'

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

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

`label` ¶

Field.label¶

Параметр label позволяет указать удобную для поля метку. Это значение используется, когда поле Field отображается в форме Form .

Как объяснялось в разделе «Просмотр форм в HTML» выше, метка по умолчанию для поля Field создается из имени поля путем преобразования всех подчеркиваний в пробелы и использования первой буквы с большой буквы. Присвойте значение, label если это поведение по умолчанию не дает подходящего результата.

Вот полный пример реализации формы 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)
<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>
<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

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

`initial` ¶

Field.initial¶

Параметр initial используется для указания начального значения, которое будет использоваться при отображении HTML поля в 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)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

Вам может быть интересно, почему мы просто не передаем словарь начальных значений в параметре data при отображении формы? Проблема с этим решением заключается в том, что оно вызывает проверку данных, и тогда результат 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)
<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>
<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required></td></tr>
<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>

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

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

>>> 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())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>

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

`help_text` ¶

Field.help_text¶

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

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

Вот полный пример реализации формы 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.as_table())
<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>
<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>
>>> print(f.as_ul()))
<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>
<li>Message: <input type="text" name="message" required></li>
<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>
<li>Cc myself: <input type="checkbox" name="cc_myself"></li>
>>> print(f.as_p())
<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>
<p>Message: <input type="text" name="message" required></p>
<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>
<p>Cc myself: <input type="checkbox" name="cc_myself"></p>

`error_messages` ¶

Field.error_messages¶

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

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

А вот собственное сообщение об ошибке:

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

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

`validators` ¶

Field.validators¶

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

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

`localize` ¶

Field.localize¶

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

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

`disabled` ¶

Field.disabled¶

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

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

`has_changed()` ¶

Field.has_changed() ¶

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

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

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

Конечно, в библиотеке форм есть ряд классов, Field представляющих наиболее распространенные потребности в валидации. В этом разделе описывается каждое встроенное поле в Django.

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

`BooleanField` ¶

классBooleanField ( ** kwargs ) ¶

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

Заметка

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

`CharField` ¶

класс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` ¶

классChoiceField ( ** kwargs ) ¶

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

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

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

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

`TypedChoiceField` ¶

классTypedChoiceField ( ** kwargs ) ¶

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

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

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

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

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

`DateField` ¶

классDateField ( ** kwargs ) ¶

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

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

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

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

`DateTimeField` ¶

класс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 если USE_L10N есть False , или из активного формата локали DATETIME_INPUT_FORMATS и DATE_INPUT_FORMATS ключей, если локализация включена. См. Также локализацию формата .

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

Добавлена поддержка синтаксического анализа строки даты ISO 8601 (включая необязательный часовой пояс).

Был добавлен откат по DATE_INPUT_FORMATS умолчанию input_formats .

`DecimalField` ¶

классDecimalField ( ** kwargs ) ¶

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

Сообщения об ошибках 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¶: Максимально допустимое количество десятичных знаков.

`DurationField` ¶

классDurationField ( ** kwargs ) ¶

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

Принимает любой формат, parse_duration() поддерживающий сканирование.

`EmailField` ¶

классEmailField ( ** kwargs ) ¶

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

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

`FileField` ¶

классFileField ( ** kwargs ) ¶

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

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

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

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

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

`FilePathField` ¶

класс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` ¶

классFloatField ( ** kwargs ) ¶

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

Принимает два необязательных параметра для проверки max_value и min_value . Эти параметры управляют диапазоном значений, разрешенных в этом поле.

`ImageField` ¶

классImageField ( ** kwargs ) ¶

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

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

При использовании поля 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', <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` ¶

классIntegerField ( ** kwargs ) ¶

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

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

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

max_value¶

min_value¶

Эти параметры управляют диапазоном значений, разрешенных в этом поле.

`JSONField` ¶

классJSONField ( кодировщик = Нет , декодер = Нет , ** kwargs ) ¶

Новое в Django 3.1.

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

Виджет по умолчанию: Textarea
Пустое значение: '' (пустая строка)
Нормализуется до: представления значения JSON в Python (обычно в виде a dict , list gold None ), В ЗАВИСИМОСТИ ОТ ' JSONField.decoder .
Проверяет, является ли данное значение допустимым JSON.
Сообщения об ошибках: Ключи required ,invalid

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

encoder¶

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

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

decoder¶

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

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

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

Заметка

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

Удобные формы

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

`GenericIPAddressField` ¶

классGenericIPAddressField ( ** kwargs ) ¶

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

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

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

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

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

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

`MultipleChoiceField` ¶

классMultipleChoiceField ( ** kwargs ) ¶

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

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

Требуется дополнительный обязательный параметр choices , например for ChoiceField .

`TypedMultipleChoiceField` ¶

классTypedMultipleChoiceField ( ** kwargs ) ¶

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

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

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

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

`NullBooleanField` ¶

классNullBooleanField ( ** kwargs ) ¶

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

`RegexField` ¶

классRegexField ( ** kwargs ) ¶

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

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

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

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

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

`SlugField` ¶

классSlugField ( ** kwargs ) ¶

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

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

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

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

`TimeField` ¶

классTimeField ( ** kwargs ) ¶

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

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

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

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

`URLField` ¶

классURLField ( ** kwargs ) ¶

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

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

max_length¶

min_length¶

Эти параметры такие же, как CharField.max_length и CharField.min_length .

`UUIDField` ¶

классUUIDField ( ** kwargs ) ¶

Компонент по умолчанию: TextInput
Пустое значение: '' (пустая строка)
Нормализован к: объекту UUID .
Сообщения об ошибках: Ключи required ,invalid

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

`Field` Более сложные встроенные классы полей ¶

`ComboField` ¶

классComboField ( ** kwargs ) ¶

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

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

fields¶

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

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

`MultiValueField` ¶

classMultiValueField ( 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( список_данных ) ¶

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

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

`SplitDateTimeField` ¶

класс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` ¶

классModelChoiceField ( ** kwargs ) ¶

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

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

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

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>

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

классModelMultipleChoiceField ( ** kwargs ) ¶

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

Не рекомендуется с версии 3.1: list Сообщение является устаревшим, используйте invalid_list вместо этого.

Повторение выбора отношений ¶

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

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

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

from django.db import models

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

    def __str__(self):
        return self.name

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

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

from django import forms

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

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

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

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

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

`ModelChoiceIterator` ¶

классModelChoiceIterator ( поле ) ¶

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

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

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

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

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

Изменено в Django 3.1:
В более старых версиях первым value элементом в кортеже выбора является само field значение, а не ModelChoiceIteratorValue экземпляр.

`ModelChoiceIteratorValue` ¶

классModelChoiceIteratorValue ( значение , экземпляр ) ¶

Новое в Django 3.1.

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

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

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() .

3.2
Версия документации: 3.1

Поля формы ¶ window.yaContextCb.push(()=>{ Ya.Context.AdvManager.render({ renderTo: 'yandex_rtb_R-A-2008230-3', blockId: 'R-A-2008230-3' }) })

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

required ¶

label ¶

label_suffix ¶

initial ¶

widget ¶

help_text ¶

error_messages ¶

validators ¶

localize ¶

disabled ¶

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

has_changed() ¶

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

BooleanField ¶

CharField ¶

ChoiceField ¶

TypedChoiceField ¶

DateField ¶

DateTimeField ¶

DecimalField ¶

DurationField ¶

EmailField ¶

FileField ¶

FilePathField ¶

FloatField ¶

ImageField ¶

IntegerField ¶

JSONField ¶

GenericIPAddressField ¶

MultipleChoiceField ¶

TypedMultipleChoiceField ¶

NullBooleanField ¶

RegexField ¶

SlugField ¶

TimeField ¶

URLField ¶

UUIDField ¶

Field Более сложные встроенные классы полей ¶

ComboField ¶

MultiValueField ¶

SplitDateTimeField ¶

Поля, посвященные отношениям ¶

ModelChoiceField ¶

ModelMultipleChoiceField ¶

Повторение выбора отношений ¶

ModelChoiceIterator ¶

ModelChoiceIteratorValue ¶

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

Резюме

Просматривать

Вы здесь :

Поля формы ¶

`required` ¶

`label` ¶

`label_suffix` ¶

`initial` ¶

`widget` ¶

`help_text` ¶

`error_messages` ¶

`validators` ¶

`localize` ¶

`disabled` ¶

`has_changed()` ¶

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

`BooleanField` ¶

`CharField` ¶

`ChoiceField` ¶

`TypedChoiceField` ¶

`DateField` ¶

`DateTimeField` ¶

`DecimalField` ¶

`DurationField` ¶

`EmailField` ¶

`FileField` ¶

`FilePathField` ¶

`FloatField` ¶

`ImageField` ¶

`IntegerField` ¶

`JSONField` ¶

`GenericIPAddressField` ¶

`MultipleChoiceField` ¶

`TypedMultipleChoiceField` ¶

`NullBooleanField` ¶

`RegexField` ¶

`SlugField` ¶

`TimeField` ¶

`URLField` ¶

`UUIDField` ¶

`Field` Более сложные встроенные классы полей ¶

`ComboField` ¶

`MultiValueField` ¶

`SplitDateTimeField` ¶

`ModelChoiceField` ¶

`ModelMultipleChoiceField` ¶

`ModelChoiceIterator` ¶

`ModelChoiceIteratorValue` ¶