Поля форм

class Field(**kwargs)

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

Field.clean(value)

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

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean('foo@example.com')
'foo@example.com'
>>> 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, это будет пустая строка. Для других классов Field, это может быть None. (Это зависит от поля.)

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

label

Field.label

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

Как объяснялось в разделе "Вывод форм в виде HTML" выше, ярлык по умолчанию для 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, отключает поле формы, используя атрибут HTML disabled, так что оно не может быть изменено пользователями. Даже если пользователь изменяет значение поля, отправленное на сервер, оно будет проигнорировано в пользу значения из начальных данных формы.

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

has_changed()

Field.has_changed()

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

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

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

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

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

BooleanField

class BooleanField(**kwargs)

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

Примечание

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

CharField

class 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

class ChoiceField(**kwargs)

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

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

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

choices

Итерируемый объект из 2-х кортежей, используемых в качестве вариантов для этого поля, варианты перечисления или функция, возвращающая такой итерируемый объект. Этот аргумент принимает те же форматы, что и аргумент choices для поля модели. Дополнительные сведения см. в документации по полю модели по параметрам выбора. Если аргумент является вызываемым объектом, он вычисляется каждый раз при инициализации формы поля. По умолчанию — пустой список.

TypedChoiceField

class TypedChoiceField(**kwargs)

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

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

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

coerce

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

empty_value

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

DateField

class 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

class DateTimeField(**kwargs)

• Значение по умолчанию виджета: DateTimeInput
• Значение пустого поля: None
• Нормализуется до: объект Python datetime.datetime.
• Проверяет, что заданное значение — это datetime.datetime, datetime.date или строка, отформатированная в определённом формате даты и времени.
• Ключи сообщений об ошибках: required, invalid

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

input_formats

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

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

DecimalField

class 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

class DurationField(**kwargs)

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

Принимает любой формат, понятный parse_duration().

EmailField

class EmailField(**kwargs)

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

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

FileField

class 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

class 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

class FloatField(**kwargs)

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

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

ImageField

class ImageField(**kwargs)

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

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

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

class IntegerField(**kwargs)

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

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

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

max_value

min_value

Эти аргументы задают диапазон допустимых значений поля.

GenericIPAddressField

class 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

class MultipleChoiceField(**kwargs)

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

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

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

TypedMultipleChoiceField

class TypedMultipleChoiceField(**kwargs)

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

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

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

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

NullBooleanField

class NullBooleanField(**kwargs)

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

RegexField

class RegexField(**kwargs)

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

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

regex

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

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

strip

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

SlugField

class SlugField(**kwargs)

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

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

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

allow_unicode

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

TimeField

class 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

class URLField(**kwargs)

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

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

max_length

min_length

Эти параметры аналогичны CharField.max_length и CharField.min_length.

UUIDField

class UUIDField(**kwargs)

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

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

Несколько сложные встроенные Field классы

ComboField

class ComboField(**kwargs)

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

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

fields

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

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean('test@example.com')
'test@example.com'
>>> f.clean('longemailaddress@example.com')
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(data_list)

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

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

SplitDateTimeField

class 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

class ModelChoiceField(**kwargs)

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

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

Требуется один аргумент:

queryset

A 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)

Обратите внимание, что если требуется 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>

Метод __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

class ModelMultipleChoiceField(**kwargs)

• По умолчанию виджет: SelectMultiple
• Пустое значение: Пустой набор QuerySet (self.queryset.none())
• Нормализуется в: Список экземпляров моделей.
• Проверяет, что каждый id в заданном списке значений существует в наборе запросов.
• Ключи сообщений об ошибках: required, 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.

Создание пользовательских полей

Если встроенные классы Field не соответствуют вашим потребностям, вы можете создать пользовательские классы Field. Для этого создайте подкласс django.forms.Field. Единственные требования к нему заключаются в реализации метода clean() и том, что метод __init__() принимает основные аргументы, упомянутые выше (required, label, initial, widget, help_text).

Вы также можете настроить доступ к полю, переопределив get_bound_field().