Поля формы ¶
-
класс
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
(то есть, например, что флажок установлен) ifrequired=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
goldNone
), В ЗАВИСИМОСТИ ОТ '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
.
Удобные формы
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
, например forChoiceField
.- Компонент по умолчанию:
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
.- Компонент по умолчанию:
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
¶
-
class
MultiValueField
( fields = () , ** kwargs ) ¶ - Компонент по умолчанию:
TextInput
- Пустое значение:
''
(пустая строка) - Нормализован к: типу, возвращаемому методом
compress
подкласса. - Проверяет, что указанные значения действительны для каждого из полей, указанных в параметре
MultiValueField
. - Сообщения об ошибках: Ключи
required
,invalid
,incomplete
Агрегирует логику нескольких полей, которые создают одно общее значение.
Это поле абстрактное и должно быть унаследовано. В отличие от однозначных полей подклассы
MultiValueField
не должны реализовываться,clean()
а скорееcompress()
.Требуется дополнительный обязательный параметр:
-
fields
¶ Кортеж полей, значения которых очищаются, а затем объединяются в одно значение. Каждое значение в поле очищается соответствующим полем в
fields
- первое значение очищается первым полем, второе значение - вторым полем и т. Д. Когда все поля очищены, список этих значений объединяется в одно значение с помощьюcompress()
.
Также принимает необязательные параметры:
-
require_all_fields
¶ По умолчанию используется значение
True
, и в этом случае возникает ошибка проверки,required
если для любого поля не указано значение.Если значение равно
False
, атрибутField.required
может быть установленFalse
для отдельных полей, чтобы сделать их необязательными. Если значение для обязательного поля не указано,incomplete
генерируется ошибка проверки .Сообщение об ошибке по
incomplete
умолчанию может быть определено в подклассеMultiValueField
, или можно определить разные сообщения для каждого поля индивидуально. Например :from django.core.validators import RegexValidator class PhoneField(MultiValueField): def __init__(self, **kwargs): # Define one message for all fields. error_messages = { 'incomplete': 'Enter a country calling code and a phone number.', } # Or define a different message for each field. fields = ( CharField( error_messages={'incomplete': 'Enter a country calling code.'}, validators=[ RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'), ], ), CharField( error_messages={'incomplete': 'Enter a phone number.'}, validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')], ), CharField( validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')], required=False, ), ) super().__init__( error_messages=error_messages, fields=fields, require_all_fields=False, **kwargs )
-
widget
¶ Должен быть подклассом
django.forms.MultiWidget
. По умолчанию этоTextInput
, вероятно, не очень полезно в данном случае.
-
compress
( список_данных ) ¶ Принимает список допустимых значений и возвращает «сжатую» версию этих значений в виде одного значения. Например,
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()
.