Поля формы

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

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

widget

Field.widget

Параметр widget используется для указания класса, который Widget будет использоваться при отрисовке HTML-кода этого элемента управления. См. « Компоненты формы» («виджеты») для получения дополнительной информации.

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

Copyright ©2020 All rights reserved