Поля формы ¶
-
класс
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
, exceptTypedChoiceField
принимает два дополнительных аргумента,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
который на самом деле был строкой, которая случайно оказалась в том же формате, который был выбран дляdatetime
s.decoder
Может быть использовано для подтверждения ввода. Еслиjson.JSONDecodeError
возникает во время десериализации,ValidationError
будет повышен.По умолчанию
json.JSONDecoder
.
Удобные формы
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
, exceptTypedMultipleChoiceField
принимает два дополнительных аргумента,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
.- Виджет по умолчанию:
Слегка сложные встроенные 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
- Нормализуется до:
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.choices
value
ModelChoiceIteratorValue
Изменено в 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()
.