Поля формы

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'

If a Field has required=False and you pass clean() an empty value, then clean() will return a normalized empty value rather than raising ValidationError. For CharField, this will be an empty string. For other Field classes, it might be None. (This varies from field to field.)

Widgets of required form fields have the required HTML attribute. Set the Form.use_required_attribute attribute to False to disable it. The required attribute isn’t included on forms of formsets because the browser validation may not be correct when adding and deleting formsets.

label

Field.label

Аргумент label позволяет вам определить «видимую людьми» метку для этого поля. Оно используется когда Field отображается на форме.

Как показано ранее в Выдаче формы в виде HTML, стандартная метка для Field создаётся из имени поля, с преобразованием всех символов подчёркивания в пробелы и переводом первой буквы в верхний регистр. Укажите 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 позволяет определять начальное значение для поля, при его отображении на незаполненной форме.

Для определения динамических начальных данных, используйте параметр 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>

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

Также следует отметить, что начальные значения не используются в качестве значений по умолчанию во время проведения проверки данных в полях формы. Начальные значения, определённые в 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.']}

Вместо констант вы также можете передавать любой исполняемый объект (callable):

>>> 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, который следует использовать при отображении поля. Обратитесь к Виджеты для более подробной информации.

help_text

Field.help_text

Аргумент help_text позволяет указать описание для поля. Если вы укажете help_text, он будет показан около поля при отображении формы с помощью вспомогательных методов 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']

В разделе классы встроенных полей показано, что каждое поле определяет ключи сообщений об ошибках, которые оно использует.

validators

Field.validators

Аргумент validators позволяет указать список функций, осуществляющих проверку поля.

Обратитесь к документации на валидаторы для подробной информации.

localize

Field.localize

Аргумент localize включает локализацию для данных формы, как на входе, так и на выходе.

See the format localization documentation for more information.

disabled

Field.disabled

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

Устанавливается при изменении данных поля

has_changed()

Field.has_changed()

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

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

Классы встроенных полей

Библиотека форм поставляется с набором классов Field, которые предоставляют решение общих задач проверки данных. Этот раздел описывает каждое встроенное поле.

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

BooleanField

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

Примечание

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

CharField

class CharField(**kwargs)
  • Стандартный виджет: TextInput
  • Empty value: Whatever you’ve given as empty_value.
  • Normalizes to: A string.
  • Uses MaxLengthValidator and MinLengthValidator if max_length and min_length are provided. Otherwise, all inputs are valid.
  • Ключи сообщений об ошибках: required, max_length, min_length.

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

max_length
min_length

Если они указаны, то производится соответствующая проверка длины полученной строки.

strip

При True (по умолчанию), у значения будут обрезаны пробелы в начале и в конце.

empty_value

The value to use to represent «empty». Defaults to an empty string.

ChoiceField

class ChoiceField(**kwargs)
  • Стандартный виджет: Select
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Проверяет, что введённое значение присутствует в списке вариантов.
  • Ключи сообщений об ошибках: required, invalid_choice.

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

Takes one extra argument:

choices

Either an iterable of 2-tuples to use as choices for this field, or a callable that returns such an iterable. This argument accepts the same formats as the choices argument to a model field. See the model field reference documentation on choices for more details. If the argument is a callable, it is evaluated each time the field’s form is initialized. Defaults to an empty list.

TypedChoiceField

class TypedChoiceField(**kwargs)

Just like a ChoiceField, except TypedChoiceField takes two extra arguments, coerce and empty_value.

  • Стандартный виджет: Select
  • Empty value: Whatever you’ve given as empty_value.
  • Normalizes to: A value of the type provided by the coerce argument.
  • Проверяет, что полученное значение присутствует в списке вариантов и может быть преобразовано в нужный тип.
  • Ключи сообщений об ошибках: required, invalid_choice.

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

coerce

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

empty_value

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

DateField

class DateField(**kwargs)
  • Стандартный виджет: DateInput
  • Пустое значение: None.
  • Возвращает: Объект datetime.date языка Python.
  • Проверяет, что полученное значение является объектом datetime.date, datetime.datetime или строкой, отформатированной в нужном виде.
  • Ключи сообщений об ошибках: required, invalid.

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

input_formats

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

If no input_formats argument is provided, the default input formats are taken from DATE_INPUT_FORMATS if USE_L10N is False, or from the active locale format DATE_INPUT_FORMATS key if localization is enabled. See also format localization.

DateTimeField

class DateTimeField(**kwargs)
  • Стандартный виджет: DateTimeInput
  • Пустое значение: None.
  • Возвращает: Объект datetime.datetime языка Python.
  • Проверяет, что полученное значение является объектом datetime.datetime, datetime.date или строкой, отформатированной в нужном виде.
  • Ключи сообщений об ошибках: required, invalid.

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

input_formats

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

If no input_formats argument is provided, the default input formats are taken from DATETIME_INPUT_FORMATS if USE_L10N is False, or from the active locale format DATETIME_INPUT_FORMATS key if localization is enabled. See also format localization.

DecimalField

class DecimalField(**kwargs)
  • По умолчанию используется виджет NumberInput при Field.localize равном False, иначе TextInput.
  • Пустое значение: None.
  • Возвращает: Тип decimal языка Python.
  • Validates that the given value is a decimal. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is ignored.
  • Ключи сообщений об ошибках: 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.
  • Нормализует к timedelta.
  • Validates that the given value is a string which can be converted into a timedelta. The value must be between datetime.timedelta.min and datetime.timedelta.max.
  • Error message keys: required, invalid, overflow.

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

EmailField

class EmailField(**kwargs)
  • Стандартный виджет: EmailInput
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Uses EmailValidator to validate that the given value is a valid email address, using a moderately complex regular expression.
  • Ключи сообщений об ошибках: 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
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Проверяет, что выбранное значение присутствует в списке вариантов.
  • Ключи сообщений об ошибках: required, invalid_choice.

The field allows choosing from files inside a certain directory. It takes five extra arguments; only path is required:

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.
  • Возвращает: Тип float языка Python.
  • Validates that the given value is a float. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is allowed, as in Python’s float() function.
  • Ключи сообщений об ошибках: required, invalid, max_value, min_value.

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

ImageField

class ImageField(**kwargs)
  • Стандартный виджет: ClearableFileInput
  • Пустое значение: None.
  • Возвращает: Объект UploadedFile, который оборачивает содержимое файла и его имя в единый объект.
  • Validates that file data has been bound to the form. Also uses FileExtensionValidator to validate that the file extension is supported by Pillow.
  • Ключи сообщений об ошибках: required, invalid, missing, empty, invalid_image.

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

При использовании ImageField на форме, вы должны не забыть связать данные файла с формой.

After the field has been cleaned and validated, the UploadedFile object will have an additional image attribute containing the Pillow Image instance used to check if the file was a valid image. Pillow closes the underlying file descriptor after verifying an image, so whilst non-image data attributes, such as format, height, and width, are available, methods that access the underlying image data, such as getdata() or getpixel(), cannot be used without reopening the file. For example:

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

Additionally, UploadedFile.content_type will be updated with the image’s content type if Pillow can determine it, otherwise it will be set to None.

IntegerField

class IntegerField(**kwargs)
  • По умолчанию используется виджет NumberInput при Field.localize равном False, иначе TextInput.
  • Пустое значение: None.
  • Normalizes to: A Python integer.
  • Validates that the given value is an integer. Uses MaxValueValidator and MinValueValidator if max_value and min_value are provided. Leading and trailing whitespace is allowed, as in Python’s int() function.
  • Ключи сообщений об ошибках: required, invalid, max_value, min_value.

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

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

max_value
min_value

Они определяют диапазон значений, разрешённый для поля.

GenericIPAddressField

class GenericIPAddressField(**kwargs)

Поле для обработки адресов IPv4 или IPv6.

  • Стандартный виджет: TextInput
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string. IPv6 addresses are normalized as described below.
  • Проверяет, что полученное значение является правильным 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
  • Пустое значение: [] (пустой список).
  • Normalizes to: A list of strings.
  • Проверяет, что каждое значение из полученного списка присутствует в списке вариантов.
  • Ключи сообщений об ошибках: 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.
  • Возвращает: True, False или None.
  • Ничего не проверяет, т.е. никогда не возвратит ValidationError.

RegexField

class RegexField(**kwargs)
  • Стандартный виджет: TextInput
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Uses RegexValidator to validate that the given value matches a certain regular expression.
  • Ключи сообщений об ошибках: required, invalid.

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

regex

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

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

strip

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

SlugField

class SlugField(**kwargs)
  • Стандартный виджет: TextInput
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Uses validate_slug or validate_unicode_slug to validate that the given value contains only letters, numbers, underscores, and hyphens.
  • Ключи сообщений об ошибках: required, invalid.

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

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

allow_unicode

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

TimeField

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

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

input_formats

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

If no input_formats argument is provided, the default input formats are taken from TIME_INPUT_FORMATS if USE_L10N is False, or from the active locale format TIME_INPUT_FORMATS key if localization is enabled. See also format localization.

URLField

class URLField(**kwargs)
  • Стандартный виджет: URLInput
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Uses URLValidator to validate that the given value is a valid 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
  • Пустое значение: '' (пустая строка).
  • Normalizes to: A string.
  • Проверяет, что полученное значение соответствует каждому полю, указанному в качестве аргумента 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().

Also takes some optional arguments:

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)
  • Стандартный виджет: :class: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_date_formats не был предоставлен, то используются шаблоны аналогичные полю TimeField.

Поля для обработки связей

Для представления связей между моделями предлагается два поля: ModelChoiceField and ModelMultipleChoiceField. Оба эти поля требуют наличие одного параметра queryset, который используется для создания вариантов значений для этого поля. При проверке формы эти поля заполняются одним объектом модели (в случае ModelChoiceField) или множеством объектов модели (в случае ModelMultipleChoiceField) в словаре cleaned_data формы.

Возможно указать queryset=None при определении поля, далее в конструкторе формы определить значение этого атрибута:

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.
  • Возвращает: Экземпляр модели.
  • Проверяет, что полученный идентификатор присутствует в выборке.
  • Ключи сообщений об ошибках: required, invalid_choice.

Позволяет выбор единственного объекта модели, имеет смысл при отображении внешнего ключа. Следует отметить, что стандартный виджет для ModelChoiceField становится непрактичным когда число его значений растёт. Сотня значений уже становится проблемой.

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

queryset

A QuerySet of model objects from which the choices for the field are derived and which is used to validate the user’s selection. It’s evaluated when the form is rendered.

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

empty_label

По умолчанию виджет <select>, используемый полем ModelChoiceField, содержит пустой вариант в начале списка. Вы можете изменить текстовую метку для этого варианта (по умолчанию это "---------") с помощью атрибута empty_label. Также вы можете исключить пустой вариант из списка поря, назначив None параметру empty_label:

# 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>

The __str__() method of the model will be called to generate string representations of the objects for use in the field’s choices. To provide customized representations, subclass ModelChoiceField and override label_from_instance. This method will receive a model object and should return a string suitable for representing it. For example:

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())
  • Возвращает: Выборку с экземплярами модели.
  • Проверяет, что каждый идентификатор полученного списка значений присутствует в выборке.
  • Ключи сообщений об ошибках: required, list, invalid_choice, invalid_pk_value.

Сообщение об ошибке invalid_choice может включать %(value)sinvalid_pk_value%(pk)s.

Allows the selection of one or more model objects, suitable for representing a many-to-many relation. As with ModelChoiceField, you can use label_from_instance to customize the object representations.

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

queryset

Same as ModelChoiceField.queryset.

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

to_field_name

Same as ModelChoiceField.to_field_name.

Создание собственных полей

If the built-in Field classes don’t meet your needs, you can create custom Field classes. To do this, create a subclass of django.forms.Field. Its only requirements are that it implement a clean() method and that its __init__() method accept the core arguments mentioned above (required, label, initial, widget, help_text).

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