Документация Django 3.0
При создании класса Form наиболее важной деталью является определение полей формы. Каждое поле обладает собственной логикой проверки вводимых данных наряду с дополнительными возможностями.
Базовые аргументы поля¶
Каждый конструктор класса Field принимает эти аргументы. Некоторые классы Field принимают дополнительные аргументы. Перечисленные ниже аргументы принимаются всеми полями:
required ¶
По умолчанию каждый класс Field предполагает значение обязательным. Таким образом, если вы передадите ему пустое значение, т.е. None или пустую строку ( «» ), то метод clean() вызовет исключение ValidationError :
Для того, чтобы сделать поле «необязательным» передайте required=False в конструктор 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 ¶
Аргумент label позволяет вам определить «видимую людьми» метку для этого поля. Оно используется когда Field отображается на форме.
Ниже приведён пример формы, которая определяет метки для двух своих полей. Мы используем auto_id=False для упрощения вывода:
label_suffix ¶
Аргумент label_suffix позволяет вам переопределить атрибут формы label_suffix для каждого поля:
initial ¶
Аргумент initial позволяет определять начальное значение для поля, при его отображении на незаполненной форме.
Использование этого аргумента подходит для отображения пустой формы, в которой поля будут иметь указанные значения. Например:
Вам могло прийти в голову просто передать словарь с начальными значениями при отображении формы. Но если так сделать, то вы запустите механизм проверки данных и HTML код формы будет содержать в себе результаты этой проверки:
Это главная причина, по которой начальные значения отображаются только на незаполненных формах. Для заполненных форм, HTML код всегда будет содержать введённые в форму данные.
Также следует отметить, что начальные значения не используются в качестве значений по умолчанию во время проведения проверки данных в полях формы. Начальные значения, определённые в initial предназначены лишь для первого отображения формы:
Вместо констант вы также можете передавать любой исполняемый объект ( callable ):
Исполняемый объект будет вычислен только в момент отображения незаполненной формы.
widget ¶
help_text ¶
Ниже представлен пример формы, в которой help_text определён у двух полей. Мы используем auto_id=False для упрощения вывода:
error_messages ¶
Аргумент error_messages позволяет изменить стандартные сообщения об ошибках, которые выдаёт поле. Создайте словарь с ключами тех сообщений, которые вы желаете изменить. Например, стандартное сообщение об ошибке:
А вот собственное сообщение об ошибке:
В разделе классы встроенных полей показано, что каждое поле определяет ключи сообщений об ошибках, которые оно использует.
validators ¶
Аргумент validators позволяет указать список функций, осуществляющих проверку поля.
Обратитесь к документации на валидаторы для подробной информации.
localize ¶
Аргумент localize включает локализацию для данных формы, как на входе, так и на выходе.
See the format localization documentation for more information.
disabled ¶
Устанавливается при изменении данных поля¶
has_changed() ¶
Смотрите документацию на Form.has_changed() для подробностей.
Классы встроенных полей¶
Для каждого поля мы указываем виджет, который используется в случае, если вы явно не определили нужный вам виджет. Мы также указываем значение, которое будет возвращено, если вы предоставили пустое значение (см. required).
BooleanField ¶
CharField ¶
Имеет три необязательных аргумента для проверки:
Если они указаны, то производится соответствующая проверка длины полученной строки.
При True (по умолчанию), у значения будут обрезаны пробелы в начале и в конце.
The value to use to represent «empty». Defaults to an empty string.
ChoiceField ¶
Takes one extra argument:
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 ¶
Принимает дополнительные аргументы:
DateField ¶
Принимает один необязательный аргумент:
DateTimeField ¶
Принимает один необязательный аргумент:
DecimalField ¶
Принимает четыре необязательных аргумента:
Максимальное число разрядов (до и после десятичной точки, впередистоящие нули обрезаются) разрешённых в значении.
Максимальное число разрешённых десятичных разрядов.
DurationField ¶
EmailField ¶
FileField ¶
Ошибка max_length относится к длине имени файла. В сообщении об ошибке шаблон %(max)d будет заменён максимальной длиной имени файла, а %(length)d – длиной имени текущего файла.
FilePathField ¶
The field allows choosing from files inside a certain directory. It takes five extra arguments; only path is required:
Абсолютный путь до каталога, содержимое которого вы желаете отобразить. Этот каталог должен существовать.
Шаблон регулярного выражения. Отображаться будут только те файлы, которые подходят под указанное регулярное выражение.
FloatField ¶
ImageField ¶
Использование ImageField требует наличия Pillow (рекомендуется) с поддержкой используемых вами форматов изображений. Если вы сталкиваетесь с ошибкой corrupt image при загрузке изображения, обычно это означает, что Pillow не поддерживает такой формат изображения. Для решения этой проблемы, установите соответствующую библиотеку и переустановите Pillow.
IntegerField ¶
Принимает два необязательных аргумента для проверки:
Они определяют диапазон значений, разрешённый для поля.
GenericIPAddressField ¶
Поле для обработки адресов IPv4 или IPv6.
Принимает два необязательных аргумента:
MultipleChoiceField ¶
TypedMultipleChoiceField ¶
NullBooleanField ¶
RegexField ¶
Принимает один обязательный аргумент:
Регулярное выражение в виде строки или скомпилированного объекта регулярного выражения.
SlugField ¶
Это поле предназначено для представления поля модели SlugField на формах.
Принимает необязательный аргумент:
TimeField ¶
Принимает один необязательный аргумент:
URLField ¶
Принимает следующие необязательные аргументы:
UUIDField ¶
Достаточно сложные встроенные классы Field ¶
ComboField ¶
Принимает один дополнительный обязательный аргумент:
Список полей, которые должны использоваться для проверки значения поля (в порядке их определения).
MultiValueField ¶
Агрегирует логику нескольких полей, создавая единое значение.
Принимает один дополнительный обязательный аргумент:
Also takes some optional arguments:
Этот метод должен быть реализован в дочерних классах.
SplitDateTimeField ¶
Принимает два необязательных аргумента:
Поля для обработки связей¶
Возможно указать queryset=None при определении поля, далее в конструкторе формы определить значение этого атрибута:
ModelChoiceField ¶
Позволяет выбор единственного объекта модели, имеет смысл при отображении внешнего ключа. Следует отметить, что стандартный виджет для ModelChoiceField становится непрактичным когда число его значений растёт. Сотня значений уже становится проблемой.
Единственный обязательный аргумент:
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 принимает два необязательных аргумента:
Создание форм из моделей ¶
ModelForm ¶
Если вы создаете приложение на основе базы данных, скорее всего, у вас будут формы, которые близко соответствуют моделям Django. Например, у вас может быть BlogComment модель, и вы хотите создать форму, позволяющую людям отправлять комментарии. В этом случае было бы излишним определять типы полей в вашей форме, потому что вы уже определили поля в своей модели.
По этой причине Django предоставляет вспомогательный класс, который позволяет вам создавать Form класс из модели Django.
Типы полей ¶
Созданный Form класс будет иметь поле формы для каждого указанного поля модели в порядке, указанном в fields атрибуте.
Как и следовало ожидать, ForeignKey и ManyToManyField типы полей модели являются частными случаями:
Кроме того, каждое сгенерированное поле формы имеет следующие атрибуты:
Наконец, обратите внимание, что вы можете переопределить поле формы, используемое для данного поля модели. См. Раздел « Замена полей по умолчанию» ниже.
Полный пример ¶
Рассмотрим этот набор моделей:
С этими моделями приведенные ModelForm выше подклассы были бы примерно эквивалентны этому (единственное отличие состоит в save() методе, который мы обсудим чуть позже):
Проверка на ModelForm ¶
Есть два основных этапа проверки ModelForm :
Процесс очистки изменяет экземпляр модели, переданный ModelForm конструктору, различными способами. Например, любые поля даты в модели преобразуются в фактические объекты даты. Неудачная проверка может привести к тому, что базовый экземпляр модели окажется в несогласованном состоянии, поэтому повторно использовать его не рекомендуется.
Переопределение метода clean () ¶
Вы можете переопределить clean() метод в форме модели, чтобы обеспечить дополнительную проверку так же, как и в обычной форме.
Экземпляр формы модели, прикрепленный к объекту модели, будет содержать instance атрибут, который дает его методам доступ к этому конкретному экземпляру модели.
Взаимодействие с валидацией модели ¶
В рамках процесса проверки ModelForm будет вызывать clean() метод каждого поля в вашей модели, у которого есть соответствующее поле в вашей форме. Если вы исключили какие-либо поля модели, проверка этих полей выполняться не будет. См. Документацию по проверке формы, чтобы узнать больше о том, как работают очистка и проверка полей.
Соображения относительно модели error_messages ¶
Сообщения об ошибках, определенные на уровне или на уровне мета-формы, всегда имеют приоритет над сообщениями об ошибках, определенными на уровне. form field model field
Вы можете переопределить сообщения об ошибках, NON_FIELD_ERRORS возникающие при проверке модели, добавив NON_FIELD_ERRORS ключ в error_messages словарь ModelForm внутреннего Meta класса:
save() Метод ¶
У каждого ModelForm тоже есть save() метод. Этот метод создает и сохраняет объект базы данных из данных, привязанных к форме. Подкласс ModelForm может принимать существующий экземпляр модели в качестве аргумента ключевого слова instance ; если он предоставлен, save() обновит этот экземпляр. Если он не указан, save() будет создан новый экземпляр указанной модели:
modelformset_factory() используется formset_factory() для создания наборов форм. Это означает, что модельный набор форм является расширением базового набора форм, который знает, как взаимодействовать с конкретной моделью.
При использовании наследования нескольких таблиц формы, созданные фабрикой наборов форм, будут содержать поле родительской ссылки (по умолчанию
_ptr ) вместо id поля.
Изменение набора запросов ¶
По умолчанию, когда вы создаете набор форм из модели, набор форм будет использовать набор запросов, который включает все объекты в модели (например, Author.objects.all() ). Вы можете изменить это поведение, используя queryset аргумент:
Затем передайте свой BaseAuthorFormSet класс фабричной функции:
Изменение формы ¶
Затем передайте форму модели в функцию factory:
Указание виджетов для использования в форме с помощью widgets ¶
Используя widgets параметр, вы можете указать словарь значений для настройки ModelForm класса виджета для определенного поля. Это работает так же, как widgets словарь во внутреннем Meta классе ModelForm произведения:
Включение локализации для полей с localized_fields ¶
С помощью localized_fields параметра вы можете включить локализацию полей в форме.
Предоставление начальных значений ¶
Сохранение объектов в наборе форм ¶
Передайте, commit=False чтобы вернуть несохраненные экземпляры модели:
После вызова save() ваш модельный набор форм будет иметь три новых атрибута, содержащих изменения набора форм:
models.BaseModelFormSet. changed_objects ¶ models.BaseModelFormSet. deleted_objects ¶ models.BaseModelFormSet. new_objects ¶
Ограничение количества редактируемых объектов ¶
max_num не препятствует отображению существующих объектов:
Кроме того, extra=0 это не препятствует созданию новых экземпляров модели, поскольку вы можете добавлять дополнительные формы с помощью JavaScript или отправлять дополнительные данные POST. Наборы форм еще не предоставляют функциональные возможности для представления «только редактирование», которое предотвращает создание новых экземпляров.
Если значение max_num больше, чем количество существующих связанных объектов, extra в набор форм будет добавлено до дополнительных пустых форм, при условии, что общее количество форм не превышает max_num :
Использование набора форм модели на виде ¶
Наборы форм очень похожи на наборы форм. Допустим, мы хотим представить набор форм для редактирования Author экземпляров модели:
Перекрытие clean() на ModelFormSet ¶
Использование настраиваемого набора запросов ¶
Как указывалось ранее, вы можете переопределить набор запросов по умолчанию, используемый набором форм модели:
Обратите внимание, что в этом примере мы передаем queryset аргумент как в случаях, так POST и в GET случаях.
Использование набора форм в шаблоне ¶
Есть три способа визуализировать набор форм в шаблоне Django.
Во-первых, вы можете позволить набору форм выполнять большую часть работы:
Во-вторых, вы можете визуализировать набор форм вручную, но пусть форма сама сама себя обрабатывает:
В-третьих, вы можете вручную отобразить каждое поле:
Если вы решите использовать этот третий метод и не перебираете поля с помощью цикла, вам необходимо отобразить поле первичного ключа. Например, если вы отдавая и поле модели: <% for %>name age
Встроенные наборы форм ¶
Если вы хотите создать набор форм, позволяющий редактировать книги, принадлежащие определенному автору, вы можете сделать это:
Переопределение методов на InlineFormSet ¶
Например, если вы хотите переопределить clean() :
Затем, когда вы создаете свой встроенный набор форм, передайте необязательный аргумент formset :
Более одного внешнего ключа для одной модели ¶
Чтобы решить эту проблему, вы можете использовать fk_name для inlineformset_factory() :
Использование встроенного набора форм в представлении ¶
Вы можете захотеть предоставить представление, которое позволяет пользователю редактировать связанные объекты модели. Вот как это сделать:
Указание виджетов для использования во встроенной форме ¶
Поля формы ¶
Когда вы создаете Form класс, наиболее важной частью является определение полей формы. Каждое поле имеет настраиваемую логику проверки, а также несколько других ловушек.
Field. clean ( значение ) ¶
Аргументы основного поля ¶
Каждый Field конструктор класса принимает по крайней мере эти аргументы. Некоторые Field классы принимают дополнительные аргументы, зависящие от поля, но всегда следует принимать следующее:
required ¶
Чтобы указать, что поле не является обязательным, перейдите required=False к Field конструктору:
label ¶
Как объяснено выше в разделе «Вывод форм как HTML», метка по умолчанию для a Field создается из имени поля путем преобразования всех подчеркиваний в пробелы и верхнего регистра первой буквы. Укажите, label если это поведение по умолчанию не приводит к адекватной метке.
Вот полный пример, Form который реализуется label для двух его полей. Мы указали, auto_id=False чтобы упростить вывод:
label_suffix ¶
initial ¶
Чтобы указать динамические начальные данные, см. Form.initial Параметр.
Вы можете подумать, а почему бы просто не передать словарь начальных значений в виде данных при отображении формы? Что ж, если вы это сделаете, вы активируете проверку, и вывод HTML будет включать любые ошибки проверки:
Вот почему initial значения отображаются только для несвязанных форм. Для связанных форм в выводе HTML будут использоваться связанные данные.
Также обратите внимание, что initial значения не используются в качестве «резервных» данных при проверке, если не указано значение конкретного поля. initial значения предназначены только для отображения начальной формы:
Вместо константы вы также можете передать любой вызываемый объект:
Вызываемый объект будет оцениваться только при отображении несвязанной формы, а не при ее определении.
widget ¶
help_text ¶
Вот полный пример, Form который реализуется help_text для двух его полей. Мы указали, auto_id=False чтобы упростить вывод:
error_messages ¶
А вот собственное сообщение об ошибке:
В разделе встроенных классов полей ниже каждый Field определяет ключи сообщений об ошибках, которые он использует.
validators ¶
validators Аргумент позволяет предоставить список функций проверки для этого поля.
localize ¶
localize Аргумент позволяет локализацию ввода данных формы, а также обработанную продукцию.
disabled ¶
Проверка, изменились ли данные поля ¶
has_changed() ¶
См. Form.has_changed() Документацию для получения дополнительной информации.
Встроенные Field классы ¶
Естественно, forms библиотека поставляется с набором Field классов, которые представляют общие потребности в валидации. В этом разделе описано каждое встроенное поле.
BooleanField ¶
CharField ¶
Имеет четыре необязательных аргумента для проверки:
Если предоставлены, эти аргументы гарантируют, что строка будет не больше или не меньше заданной длины.
Если True (по умолчанию), значение будет очищено от начальных и конечных пробелов.
Значение, которое следует использовать для представления «пусто». По умолчанию пустая строка.
ChoiceField ¶
Принимает один дополнительный аргумент:
TypedChoiceField ¶
Принимает дополнительные аргументы:
Значение, которое следует использовать для представления «пусто». По умолчанию пустая строка; None еще один распространенный выбор здесь. Обратите внимание, что это значение не будет принудительно изменяться функцией, указанной в coerce аргументе, поэтому выберите его соответствующим образом.
DateField ¶
Принимает один необязательный аргумент:
Список форматов, используемых для попытки преобразовать строку в допустимый datetime.date объект.
DateTimeField ¶
Принимает один необязательный аргумент:
Список форматов, используемых для попытки преобразовать строку в допустимый datetime.datetime объект, в дополнение к форматам ISO 8601.
Добавлена поддержка синтаксического анализа строки даты ISO 8601 (включая необязательный часовой пояс).
DecimalField ¶
Принимает четыре необязательных аргумента:
Они управляют диапазоном значений, разрешенных в поле, и должны быть указаны как decimal.Decimal значения.
Максимальное количество цифр (до десятичной точки плюс цифры после десятичной точки с удаленными ведущими нулями), разрешенное в значении.
Максимально разрешенное количество десятичных знаков.
DurationField ¶
EmailField ¶
FileField ¶
max_length Ошибка относится к длине имени файла. В сообщении об ошибке для этого ключа, %(max)d будет заменена максимальная длина имени файла и %(length)d будет заменена текущая длина имени файла.
FilePathField ¶
Поле позволяет выбирать файлы внутри определенного каталога. Требуется пять дополнительных аргументов; path требуется только :
Абсолютный путь к каталогу, содержимое которого вы хотите перечислить. Этот каталог должен существовать.
Шаблон регулярного выражения; только файлы с именами, соответствующими этому выражению, будут допущены в качестве выбора.
FloatField ¶
ImageField ¶
Для использования ImageField требуется, чтобы Pillow был установлен с поддержкой используемых вами форматов изображений. Если вы столкнулись с ошибкой при загрузке изображения, это обычно означает, что Pillow не понимает его формат. Чтобы исправить это, установите соответствующую библиотеку и переустановите Pillow. corrupt image
IntegerField ¶
Принимает два необязательных аргумента для проверки:
Они управляют диапазоном значений, разрешенных в поле.
JSONField ¶
Принимает два необязательных аргумента:
json.JSONDecoder Подкласс десериализация входа. При десериализации может потребоваться учет того факта, что вы не можете быть уверены в типе ввода. Например, вы рискуете вернуть a, datetime который на самом деле был строкой, которая случайно оказалась в том же формате, который был выбран для datetime s.
decoder Может быть использовано для подтверждения ввода. Если json.JSONDecodeError возникает во время десериализации, ValidationError будет повышен.
JSONField в большинстве случаев не очень удобен для пользователя. Однако это полезный способ форматирования данных из клиентского виджета для отправки на сервер.
GenericIPAddressField ¶
Поле, содержащее адрес IPv4 или IPv6.
Принимает два необязательных аргумента:
MultipleChoiceField ¶
TypedMultipleChoiceField ¶
NullBooleanField ¶
NullBooleanField может использоваться с виджетами, такими как Select или RadioSelect путем предоставления виджета choices :
RegexField ¶
Принимает один обязательный аргумент:
Регулярное выражение, заданное в виде строки или скомпилированного объекта регулярного выражения.
SlugField ¶
Это поле предназначено для использования при представлении модели SlugField в формах.
Принимает два необязательных параметра:
Значение, которое следует использовать для представления «пусто». По умолчанию пустая строка.
TimeField ¶
Принимает один необязательный аргумент:
Список форматов, используемых для попытки преобразовать строку в допустимый datetime.time объект.
URLField ¶
UUIDField ¶
Это поле будет принимать любой строковый формат, принятый в качестве hex аргумента UUID конструктора.
Слегка сложные встроенные Field классы ¶
ComboField ¶
Принимает один дополнительный обязательный аргумент:
Список полей, которые следует использовать для проверки значения поля (в том порядке, в котором они указаны).
MultiValueField ¶
Агрегирует логику нескольких полей, которые вместе создают одно значение.
Принимает один дополнительный обязательный аргумент:
Также принимает некоторые необязательные аргументы:
incomplete Сообщение об ошибке по умолчанию может быть определено в MultiValueField подклассе, или различные сообщения могут быть определены для каждого отдельного поля. Например:
Этот метод должен быть реализован в подклассах.
SplitDateTimeField ¶
Принимает два необязательных аргумента:
Список форматов, используемых для попытки преобразовать строку в допустимый datetime.date объект.
Список форматов, используемых для попытки преобразовать строку в допустимый datetime.time объект.
Поля, которые обрабатывают отношения ¶
Для более сложных применений вы можете указать queryset=None при объявлении поля формы, а затем заполнить queryset в __init__() методе формы :
Оба ModelChoiceField и ModelMultipleChoiceField имеют iterator атрибут, который указывает класс, используемый для итерации по набору запросов при генерации вариантов выбора. См. Подробности в разделе « Итерация выбора отношений».
ModelChoiceField ¶
Позволяет выбрать один объект модели, подходящий для представления внешнего ключа. Обратите внимание, что виджет по умолчанию для ModelChoiceField становится непрактичным, когда количество записей увеличивается. Вам не следует использовать его для более чем 100 предметов.
Требуется единственный аргумент:
Набор QuerySet объектов модели, на основе которых производятся варианты выбора для поля и который используется для проверки выбора пользователя. Он оценивается при рендеринге формы.
ModelChoiceField также принимает два необязательных аргумента:
По умолчанию виджет, используемый пользователем, ModelChoiceField будет иметь пустой выбор вверху списка. Вы можете изменить текст этой метки (которая используется «———» по умолчанию) с помощью empty_label атрибута, или вы можете полностью отключить пустую метку, установив empty_label значение None :
Обратите внимание, что если a ModelChoiceField является обязательным и имеет начальное значение по умолчанию, пустой выбор не создается (независимо от значения empty_label ).