• 3.1
  • 3.2
  • 5.0
  • Версия документации: 6.1

Модельные формы

Справочник API ModelForm. Вводный материал об использовании ModelForm см. в руководстве по теме Создание форм из моделей.

Форма модели Мета API

class ModelFormOptions

API _meta используется для создания форм, отражающих модель Django. Он доступен через атрибут _meta каждой формы модели и представляет собой экземпляр django.forms.models.ModelFormOptions.

Структуру сгенерированной формы можно настроить, определив параметры метаданных как атрибуты внутреннего класса Meta. Например:

from django.forms import ModelForm
from myapp.models import Book


class BookForm(ModelForm):
    class Meta:
        model = Book
        fields = ["title", "author"]
        help_texts = {
            "title": "The title of the book",
            "author": "The author of the book",
        }
        # ... other attributes

Обязательными атрибутами являются model и либо fields, либо exclude. Все остальные мета-атрибуты являются необязательными.

Необязательные атрибуты, кроме localized_fields и formfield_callback, ожидают наличия словаря, который сопоставляет имя поля модели со значением. Для любого поля, которое не определено в словаре, возвращается значение поля по умолчанию.

Неверные имена полей

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

Неверные атрибуты мета-класса

Вы можете определить любой атрибут в классе Meta. Опечатки или неправильные имена атрибутов не вызывают ошибки.

error_messages

ModelFormOptions.error_messages

Словарь, который сопоставляет имя поля модели со словарем ключей сообщений об ошибках («null», «blank», «invalid», «unique» и т. д.), сопоставленных с пользовательскими сообщениями об ошибках.

Если поле не указано, Django будет использовать сообщения об ошибках, определенные в django.db.models.Field.error_messages этого поля модели, а затем, наконец, использовать сообщения об ошибках по умолчанию для этого типа поля.

исключить

ModelFormOptions.exclude

Кортеж или список имен полей model, которые необходимо исключить из формы.

Должен быть установлен либо fields, либо exclude. Если ни один из них не установлен, будет создано исключение ImproperlyConfigured. Если exclude установлен, а fields не установлен, все поля модели, за исключением тех, которые указаны в exclude, включаются в форму.

field_classes

ModelFormOptions.field_classes

Словарь, который сопоставляет имя поля модели с классом Field, который переопределяет form_class, используемый в методе Field.formfield() поля модели.

Если поле не указано, Django будет использовать класс поля по умолчанию поля модели.

fields

ModelFormOptions.fields

Кортеж или список имен полей model, которые будут включены в форму. Значение '__all__' может использоваться для указания того, что все поля должны быть включены.

Если какое-либо поле указано в exclude, оно не будет включено в форму, несмотря на то, что оно указано в fields.

Должен быть установлен либо fields, либо exclude. Если ни один из них не установлен, будет создано исключение ImproperlyConfigured.

formfield_callback

ModelFormOptions.formfield_callback

Функция или вызываемый объект, который принимает поле модели и возвращает объект django.forms.Field.

help_texts

ModelFormOptions.help_texts

Словарь, который сопоставляет имя поля модели с текстовой строкой справки.

Если поле не указано, Django будет использовать help_text этого поля модели.

этикетки

ModelFormOptions.labels

Словарь, который сопоставляет имена полей модели со строкой метки.

Если поле не указано, Django будет использовать verbose_name этого поля модели, а затем имя атрибута поля.

localized_fields

ModelFormOptions.localized_fields

Кортеж или список имен полей model для локализации. Значение '__all__' можно использовать, чтобы указать, что все поля должны быть локализованы.

По умолчанию поля формы не локализованы, более подробную информацию см. в разделе включение локализации полей.

модель

ModelFormOptions.model

Необходимый. django.db.models.Model, который будет использоваться для ModelForm.

виджеты

ModelFormOptions.widgets

Словарь, который сопоставляет имя поля модели с django.forms.Widget.

Если поле не указано, Django будет использовать виджет по умолчанию для этого конкретного типа django.db.models.Field.

Фабричные функции модели

modelform_factory

modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None, widgets=None, localized_fields=None, labels=None, help_texts=None, error_messages=None, field_classes=None)

Возвращает класс ModelForm для указанной model. Вы можете опционально передавать аргумент form, чтобы использовать форму в качестве стартовой точки при конструировании ModelForm.

Аргумент fields является необязательным списком имён полей. Если он указан, то только перечисленные в нём поля будут созданы в модельной форме.

Аргумент exclude является необязательным списком имён полей. Если он указан, то соответствующих полей не будет в созданной модельной форме, даже если они были указаны в аргументе fields.

Аргумент formfield_callback является обработчиком, который будет применять к полям модели и возвращать поля формы.

Аргумент widgets является словарём с именами полей модели привязанных к виджетам.

Аргумент localized_fields является списком имён полей, которые должны быть локализованы.

Аргумент labels является словарём имён полей модели привязанных к меткам.

Аргумент help_texts является словарём имён полей модели привязанных к тексту подсказок.

Аргумент error_messages является словарём имён полей модели привязанных к словарю с сообщениями об ошибках.

Аргумент field_classes является словарём имён полей модели привязанных к классам полей формы.

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

Вы должны явно определять список полей, через именованные аргументы fields или exclude, или через соответствующие атрибуты внутреннего класса Meta формы. Обратитесь к документации на Указываем какие поля использовать для подробностей. Игнорирование определения используемых полей вызовет исключение ImproperlyConfigured.

modelformset_factory

modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)

Возвращает класс FormSet для указанного класса model.

Аргументы model, form, fields, exclude, formfield_callback, widgets, localized_fields, labels, help_texts, error_messages и field_classes все проходят через функцию modelform_factory().

Аргументы «formset», «extra», «can_delete», «can_order», «max_num», «validate_max», «min_num», «validate_min», «absolute_max», «can_delete_extra» и «renderer» передаются в formset_factory(). Подробности см. в разделе formsets.

Аргумент edit_only позволяет:ref:предотвратить создание новых объектов <model-formsets-edit-only>.

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

inlineformset_factory

inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)

Возвращает InlineFormSet, используя функцию modelformset_factory() со стандартными formset=BaseInlineFormSet, can_delete=True и extra=3.

Если ваша модель содержит больше одного внешнего ключа (ForeignKey) к родительской модели (parent_model), обязательно указывайте fk_name.

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

Back to Top