Поля формы

класс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конструктор класса принимает по крайней мере эти аргументы. Некоторые Fieldклассы принимают дополнительные аргументы, зависящие от поля, но всегда следует принимать следующее:

required

Field.required

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

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

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

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

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

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

label

Field.label

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

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

Вот полный пример, Formкоторый реализуется labelдля двух его полей. Мы указали, auto_id=Falseчтобы упростить вывод:

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label='Your name')
...     url = forms.URLField(label='Your website', required=False)
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<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Аргумент позволяет задать начальное значение для использования при визуализации этого Fieldв несвязанной Form.

Чтобы указать динамические начальные данные, см. Form.initialПараметр.

Вариант использования для этого - когда вы хотите отобразить «пустую» форму, в которой поле инициализируется определенным значением. Например:

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial='Your name')
...     url = forms.URLField(initial='http://')
...     comment = forms.CharField()
>>> f = CommentForm(auto_id=False)
>>> print(f)
<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>

Вы можете подумать, а почему бы просто не передать словарь начальных значений в виде данных при отображении формы? Что ж, если вы это сделаете, вы активируете проверку, и вывод 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>

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

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

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

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

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
>>> print(DateForm())
<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>

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

widget

Field.widget

widgetАргумент позволяет указать Widgetкласс использования при визуализации этого Field. См. Виджеты для получения дополнительной информации.

help_text

Field.help_text

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

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

Вот полный пример, Formкоторый реализуется help_textдля двух его полей. Мы указали, auto_id=Falseчтобы упростить вывод:

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

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

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

has_changed()

Field.has_changed()

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

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

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

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

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

BooleanField

классBooleanField ( ** kwargs )
  • Виджет по умолчанию: CheckboxInput
  • Пустое значение: False
  • Нормализуется до: Python Trueили Falseзначения.
  • Проверяет, что значение равно True(например, флажок установлен), если поле имеет 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, except TypedChoiceFieldпринимает два дополнительных аргумента, coerceи empty_value.

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

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

coerce

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

empty_value

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

DateField

классDateField ( ** kwargs )
  • Виджет по умолчанию: DateInput
  • Пустое значение: None
  • Нормализуется до: datetime.dateобъекта Python .
  • Проверяет, является ли данное значение либо строкой 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
  • Нормализуется до: datetime.datetimeобъекта Python .
  • Проверяет, является ли данное значение либо строкой 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
  • Пустое значение: все, что вы указали как empty_value.
  • Нормализуется до: строки.
  • Используется EmailValidatorдля проверки того, что данное значение является допустимым адресом электронной почты, с использованием умеренно сложного регулярного выражения.
  • Ключи сообщений об ошибках: required,invalid

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

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 закрывает базовый дескриптор файла после проверки изображения, поэтому, пока доступны атрибуты данных, не относящиеся к изображению, такие как 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
  • Пустое значение: None
  • Нормализует к: представлению А Python значения JSON (обычно в виде dict, listили None), в зависимости от того JSONField.decoder.
  • Проверяет, является ли данное значение допустимым JSON.
  • Ключи сообщений об ошибках: required,invalid

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

encoder

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

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

decoder

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

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

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

Примечание

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

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

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

GenericIPAddressField

классGenericIPAddressField ( ** kwargs )

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

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

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

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

protocol

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

unpack_ipv4

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

MultipleChoiceField

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

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

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

TypedMultipleChoiceField

классTypedMultipleChoiceField ( ** kwargs )

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

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

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

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

NullBooleanField

классNullBooleanField ( ** kwargs )
  • Виджет по умолчанию: NullBooleanSelect
  • Пустое значение: None
  • Нормализует к: питон True, Falseили Noneзначение.
  • Ничего не проверяет (т. Е. Никогда не поднимает a ValidationError).

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

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

RegexField

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

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

regex

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

Кроме того, требуется max_length, min_length, stripи empty_value которые работают так же , как они делают для CharField.

strip

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

SlugField

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

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

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

allow_unicode

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

empty_value

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

TimeField

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

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

input_formats

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

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

URLField

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

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

UUIDField

классUUIDField ( ** kwargs )
  • Виджет по умолчанию: TextInput
  • Пустое значение: None
  • Нормализуется до: 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
  • Нормализуется до: datetime.datetimeобъекта Python .
  • Проверяет, что заданное значение является 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для итерации и получения вариантов выбора.

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

__iter__()

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

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

В более старых версиях первым valueэлементом в кортеже выбора является само fieldзначение, а не ModelChoiceIteratorValueэкземпляр. В большинстве случаев это прокси прозрачно, но, если вам нужно само fieldзначение, используйте ModelChoiceIteratorValue.valueвместо этого атрибут.

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 ©2021 All rights reserved