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

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

API `Meta` модельных форм

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. Все остальные атрибуты Meta необязательны.

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

Недопустимые имена полей

Недопустимые имена полей или имена исключённых полей в необязательном атрибуте-словаре не оказывают влияния, поскольку не включённые поля не обрабатываются.

Недопустимые атрибуты класса Meta

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

`error_messages`

ModelFormOptions.error_messages

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

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

`exclude`

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 этого поля модели.

`labels`

ModelFormOptions.labels

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

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

`localized_fields`

ModelFormOptions.localized_fields

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

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

`model`

ModelFormOptions.model: Обязательный параметр. Объект django.db.models.Model, который будет использоваться для ModelForm.

`widgets`

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 — словарь, сопоставляющий имена полей модели с классами полей формы.

Примеры использования см. в разделе Фабричная функция ModelForm.

Необходимо явно указать список полей: передать именованные аргументы 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(). Подробнее см. в разделе Наборы форм.

Аргумент 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.

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

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/6.0/ref/forms/models/

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

API Meta модельных форм

error_messages

exclude

field_classes

fields

formfield_callback

help_texts

labels

localized_fields

model

widgets