Создание форм из моделей

ModelForm

class ModelForm

Если вы создаёте приложение, работающее с базой данных, скорее всего, у вас будут формы, которые тесно связаны с моделями Django. Например, у вас может быть модель BlogComment, и вы хотите создать форму, которая позволит людям оставлять комментарии. В этом случае было бы избыточно определять типы полей в форме, потому что вы уже определили поля в вашей модели.

По этой причине Django предоставляет вспомогательный класс, который позволяет создать класс формы Form из модели Django.

Например:

>>> from django.forms import ModelForm
>>> from myapp.models import Article

# Create the form class.
>>> class ArticleForm(ModelForm):
...     class Meta:
...         model = Article
...         fields = ['pub_date', 'headline', 'content', 'reporter']

# Creating a form to add an article.
>>> form = ArticleForm()

# Creating a form to change an existing article.
>>> article = Article.objects.get(pk=1)
>>> form = ArticleForm(instance=article)

Типы полей

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

Каждое поле модели имеет соответствующее стандартное поле формы. Например, поле CharField в модели представлено как поле CharField в форме. Модельное поле ManyToManyField представлено как поле MultipleChoiceField. Вот полный список преобразований:

Как можно ожидать, типы полей модели ForeignKey и ManyToManyField являются особыми случаями:

• ForeignKey представлено полем django.forms.ModelChoiceField, которое является полем ChoiceField, чьи варианты выбора — модель QuerySet.
• ManyToManyField представлено полем django.forms.ModelMultipleChoiceField, которое является полем MultipleChoiceField, чьи варианты выбора — модель QuerySet.

Кроме того, каждое сгенерированное поле формы имеет атрибуты, установленные следующим образом:

• Если поле модели имеет blank=True, то required устанавливается в False в поле формы. В противном случае, required=True.
• Поле формы label устанавливается в verbose_name поля модели, с заглавной первой буквой.
• Поле формы help_text устанавливается в help_text поля модели.
• Если у поля модели установлено choices, то widget поля формы будет установлено в Select, с вариантами, полученными из choices поля модели. Варианты обычно включают пустой выбор, который выбран по умолчанию. Если поле обязательно, это заставляет пользователя сделать выбор. Пустой выбор не будет включен, если у поля модели есть blank=False и явное значение default (значение default будет выбрано по умолчанию).

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

Полный пример

Рассмотрим этот набор моделей:

from django.db import models
from django.forms import ModelForm

TITLE_CHOICES = [
    ('MR', 'Mr.'),
    ('MRS', 'Mrs.'),
    ('MS', 'Ms.'),
]

class Author(models.Model):
    name = models.CharField(max_length=100)
    title = models.CharField(max_length=3, choices=TITLE_CHOICES)
    birth_date = models.DateField(blank=True, null=True)

    def __str__(self):
        return self.name

class Book(models.Model):
    name = models.CharField(max_length=100)
    authors = models.ManyToManyField(Author)

class AuthorForm(ModelForm):
    class Meta:
        model = Author
        fields = ['name', 'title', 'birth_date']

class BookForm(ModelForm):
    class Meta:
        model = Book
        fields = ['name', 'authors']

С этими моделями, подклассы ModelForm выше были бы примерно эквивалентны этому (единственное отличие — метод save(), который мы обсудим чуть позже):

from django import forms

class AuthorForm(forms.Form):
    name = forms.CharField(max_length=100)
    title = forms.CharField(
        max_length=3,
        widget=forms.Select(choices=TITLE_CHOICES),
    )
    birth_date = forms.DateField(required=False)

class BookForm(forms.Form):
    name = forms.CharField(max_length=100)
    authors = forms.ModelMultipleChoiceField(queryset=Author.objects.all())

Валидация на ModelForm

Для проверки ModelForm участвуют два основных этапа:

1. Проверка формы
2. Проверка экземпляра модели

Так же, как и обычная проверка формы, проверка формы модели вызывается неявно при вызове is_valid() или при обращении к атрибуту errors, и явно при вызове full_clean(), хотя на практике вы обычно не будете использовать последний метод.

Model проверка (Model.full_clean()) вызывается внутри этапа проверки формы, сразу после вызова метода clean() формы.

Переопределение метода clean()

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

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

Взаимодействие с проверкой модели

В рамках процесса проверки ModelForm вызовет метод clean() каждого поля вашей модели, которое имеет соответствующее поле в вашей форме. Если вы исключили какие-либо поля модели, проверка этих полей не будет выполнена. Подробности о том, как работают очистка и проверка полей, см. в документации по проверке формы.

Метод clean() модели будет вызван до начала проверки на уникальность. См. Проверка объектов для получения дополнительной информации о хуке clean() модели.

Учет сообщений об ошибках модели error_messages

Сообщения об ошибках, определенные на уровне form field или на уровне формы Meta, всегда имеют приоритет над сообщениями об ошибках, определенными на уровне model field.

Сообщения об ошибках, определенные на уровне model fields, используются только в случае возникновения исключения ValidationError во время этапа проверки модели, и если соответствующие сообщения об ошибках не определены на уровне формы.

Вы можете переопределить сообщения об ошибках, возникших при проверке модели, добавив ключ NON_FIELD_ERRORS в словарь error_messages внутреннего класса Meta формы ModelForm:

from django.core.exceptions import NON_FIELD_ERRORS
from django.forms import ModelForm

class ArticleForm(ModelForm):
    class Meta:
        error_messages = {
            NON_FIELD_ERRORS: {
                'unique_together': "%(model_name)s's %(field_labels)s are not unique.",
            }
        }

Метод save()

У каждой формы ModelForm также есть метод save(). Этот метод создает и сохраняет объект базы данных из данных, привязанных к форме. Подкласс ModelForm может принимать существующий экземпляр модели в качестве аргумента ключевого слова instance; если он указан, save() обновит этот экземпляр. Если он не указан, save() создаст новый экземпляр указанной модели:

>>> from myapp.models import Article
>>> from myapp.forms import ArticleForm

# Create a form instance from POST data.
>>> f = ArticleForm(request.POST)

# Save a new Article object from the form's data.
>>> new_article = f.save()

# Create a form to edit an existing Article, but use
# POST data to populate the form.
>>> a = Article.objects.get(pk=1)
>>> f = ArticleForm(request.POST, instance=a)
>>> f.save()

Обратите внимание, что если форма не была проверена, вызов метода save() выполнит проверку, проверив form.errors. Будет вызвано исключение ValueError, если данные в форме не проходят проверку — то есть, если form.errors принимает значение True.

Если необязательное поле отсутствует в данных формы, результирующий экземпляр модели использует значение по умолчанию default для этого поля, если оно существует. Это поведение не относится к полям, которые используют CheckboxInput, CheckboxSelectMultiple или SelectMultiple (или любой пользовательский виджет, для которого метод value_omitted_from_data() всегда возвращает False), так как неотмеченный флажок и невыбранный <select multiple> не отображаются в данных отправки HTML-формы. Используйте пользовательское поле формы или виджет, если вы разрабатываете API и хотите получить поведение по умолчанию для поля, использующего один из этих виджетов.

Метод save() принимает необязательный аргумент ключевого слова commit, который принимает либо True, либо False. Если вы вызываете save() с commit=False, то она вернёт объект, который ещё не сохранён в базе данных. В этом случае вам нужно вызвать save() на результирующем экземпляре модели. Это полезно, если вы хотите выполнить пользовательскую обработку объекта перед сохранением или если хотите использовать один из специализированных вариантов сохранения модели. По умолчанию используется True.

Ещё один побочный эффект использования commit=False наблюдается, когда ваша модель имеет множественное отношение "многие ко многим" с другой моделью. Если ваша модель имеет множественное отношение "многие ко многим", и вы указываете commit=False при сохранении формы, Django не может немедленно сохранить данные формы для отношения "многие ко многим". Это связано с тем, что сохранить данные "многие ко многим" для экземпляра нельзя, пока экземпляр не существует в базе данных.

Для решения этой проблемы каждый раз, когда вы сохраняете форму с помощью commit=False, Django добавляет метод save_m2m() к вашему подклассу ModelForm. После того, как вы вручную сохранили экземпляр, полученный из формы, вы можете вызвать save_m2m(), чтобы сохранить данные формы "многие ко многим". Например:

# Create a form instance with POST data.
>>> f = AuthorForm(request.POST)

# Create, but don't save the new author instance.
>>> new_author = f.save(commit=False)

# Modify the author in some way.
>>> new_author.some_field = 'some_value'

# Save the new instance.
>>> new_author.save()

# Now, save the many-to-many data for the form.
>>> f.save_m2m()

Вызов save_m2m() необходим только если вы используете save(commit=False). Когда вы используете save() в форме, все данные — включая данные "многие ко многим" — сохраняются без необходимости дополнительных вызовов методов. Например:

# Create a form instance with POST data.
>>> a = Author()
>>> f = AuthorForm(request.POST, instance=a)

# Create and save the new author instance. There's no need to do anything else.
>>> new_author = f.save()

Помимо методов save() и save_m2m(), ModelForm работает точно так же, как и любая другая форма forms. Например, метод is_valid() используется для проверки валидности, метод is_multipart() используется для определения того, требует ли форма многочастную загрузку файлов (и, следовательно, должен ли быть передан параметр request.FILES в форму) и т. д. Дополнительную информацию см. в разделе Привязка загруженных файлов к форме.

Выбор полей для использования

Сильно рекомендуется явно задавать все поля, которые должны быть отредактированы в форме, используя атрибут fields. Отсутствие этого может легко привести к проблемам безопасности, когда форма неожиданно позволяет пользователю задавать определенные поля, особенно при добавлении новых полей в модель. В зависимости от того, как отображается форма, проблема может даже не отображаться на веб-странице.

Альтернативный подход заключается в автоматическом включении всех полей или удалении только некоторых. Этот фундаментальный подход известен как менее безопасный и привел к серьезным уязвимостям на крупных веб-сайтах (например, GitHub).

Однако существуют два сокращения для случаев, когда можно гарантировать, что эти проблемы безопасности не относятся к вам:

1. Установите атрибут fields со специальным значением '__all__', чтобы указать, что все поля в модели должны использоваться. Например:

   from django.forms import ModelForm
   
   class AuthorForm(ModelForm):
       class Meta:
           model = Author
           fields = '__all__'
   

2. Установите атрибут exclude внутреннего класса Meta ModelForm в список полей, которые следует исключить из формы.

   Например:

   class PartialAuthorForm(ModelForm):
       class Meta:
           model = Author
           exclude = ['title']
   

   Поскольку модель Author имеет 3 поля name, title и birth_date, это приведет к тому, что поля name и birth_date будут присутствовать в форме.

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

Кроме того, Django применяет следующее правило: если вы установите editable=False на поле модели, любая форма, созданная из модели через ModelForm, не будет включать это поле.

author = Author(title='Mr')
form = PartialAuthorForm(request.POST, instance=author)
form.save()

form = PartialAuthorForm(request.POST)
author = form.save(commit=False)
author.title = 'Mr'
author.save()

Настройка полей по умолчанию

Типы полей по умолчанию, описанные в таблице «Типы полей» выше, являются разумными значениями по умолчанию. Если у вас есть DateField в вашей модели, скорее всего, вы захотите, чтобы она представлялась как DateField в вашей форме. Но ModelForm предоставляет гибкость изменения поля формы для заданной модели.

Для задания пользовательского виджета для поля используйте атрибут widgets внутреннего класса Meta. Это должен быть словарь, сопоставляющий имена полей с классами или экземплярами виджетов.

Например, если вы хотите, чтобы CharField для атрибута name Author представлялся как <textarea> вместо его значения по умолчанию <input type="text">, вы можете настроить виджет поля:

from django.forms import ModelForm, Textarea
from myapp.models import Author

class AuthorForm(ModelForm):
    class Meta:
        model = Author
        fields = ('name', 'title', 'birth_date')
        widgets = {
            'name': Textarea(attrs={'cols': 80, 'rows': 20}),
        }

Словарь widgets принимает либо экземпляры виджетов (например, Textarea(...)), либо классы (например, Textarea). Обратите внимание, что словарь widgets игнорируется для поля модели с непустым атрибутом choices. В этом случае вам необходимо переопределить поле формы, чтобы использовать другой виджет.

Аналогично, вы можете указать атрибуты labels, help_texts и error_messages внутреннего класса Meta, если хотите дополнительно настроить поле.

Например, если вы хотите настроить текст для поля name:

from django.utils.translation import gettext_lazy as _

class AuthorForm(ModelForm):
    class Meta:
        model = Author
        fields = ('name', 'title', 'birth_date')
        labels = {
            'name': _('Writer'),
        }
        help_texts = {
            'name': _('Some useful help text.'),
        }
        error_messages = {
            'name': {
                'max_length': _("This writer's name is too long."),
            },
        }

Вы также можете указать field_classes, чтобы настроить тип полей, созданных формой.

Например, если вы хотите использовать MySlugFormField для поля slug, вы можете сделать следующее:

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

class ArticleForm(ModelForm):
    class Meta:
        model = Article
        fields = ['pub_date', 'headline', 'content', 'reporter', 'slug']
        field_classes = {
            'slug': MySlugFormField,
        }

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

Если вы хотите указать валидаторы поля, вы можете сделать это, декларативно определив поле и установив параметр validators:

from django.forms import CharField, ModelForm
from myapp.models import Article

class ArticleForm(ModelForm):
    slug = CharField(validators=[validate_slug])

    class Meta:
        model = Article
        fields = ['pub_date', 'headline', 'content', 'reporter', 'slug']

class Article(models.Model):
    headline = models.CharField(
        max_length=200,
        null=True,
        blank=True,
        help_text='Use puns liberally',
    )
    content = models.TextField()

class ArticleForm(ModelForm):
    headline = MyFormField(
        max_length=200,
        required=False,
        help_text='Use puns liberally',
    )

    class Meta:
        model = Article
        fields = ['headline', 'content']

Включение локализации полей

По умолчанию поля в ModelForm не локализуют свои данные. Чтобы включить локализацию полей, вы можете использовать атрибут localized_fields класса Meta.

>>> from django.forms import ModelForm
>>> from myapp.models import Author
>>> class AuthorForm(ModelForm):
...     class Meta:
...         model = Author
...         localized_fields = ('birth_date',)

Если localized_fields установлено в специальное значение '__all__', все поля будут локализованы.

Наследование форм

Как и в случае с базовыми формами, вы можете расширять и повторно использовать ModelForms, наследуя их. Это полезно, если вам нужно объявить дополнительные поля или методы в родительском классе для использования в нескольких формах, полученных из моделей. Например, используя предыдущий класс ArticleForm:

>>> class EnhancedArticleForm(ArticleForm):
...     def clean_pub_date(self):
...         ...

Это создает форму, которая ведет себя идентично ArticleForm, за исключением дополнительной валидации и очистки для поля pub_date.

Вы также можете расширить внутренний класс Meta родительского класса, если хотите изменить списки Meta.fields или Meta.exclude:

>>> class RestrictedArticleForm(EnhancedArticleForm):
...     class Meta(ArticleForm.Meta):
...         exclude = ('body',)

Это добавляет дополнительный метод из EnhancedArticleForm и изменяет исходный ArticleForm.Meta, чтобы удалить одно поле.

Однако есть несколько моментов, на которые следует обратить внимание.

• Применяются обычные правила разрешения имен Python. Если у вас несколько родительских классов, объявляющих внутренний класс Meta, будет использоваться только первый. Это означает, что будет использоваться Meta дочернего класса, если он существует, в противном случае — Meta первого родителя и т. д.
• Возможно наследование как от Form, так и от ModelForm одновременно, однако необходимо убедиться, что ModelForm появляется первой в MRO. Это связано с тем, что эти классы полагаются на разные метаклассы, и класс может иметь только один метакласс.

• Можно декларативно удалить Field, унаследованный от родительского класса, установив имя в None в дочернем классе.

  Этот метод можно использовать только для отказа от поля, определенного декларативно родительским классом; он не помешает метаклассу ModelForm сгенерировать поле по умолчанию. Чтобы отказаться от полей по умолчанию, см. Выбор полей для использования.

Предоставление начальных значений

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

>>> article = Article.objects.get(pk=1)
>>> article.headline
'My headline'
>>> form = ArticleForm(initial={'headline': 'Initial headline'}, instance=article)
>>> form['headline'].value()
'Initial headline'

Функция-фабрика ModelForm

Вы можете создавать формы из заданной модели с помощью самостоятельной функции modelform_factory() вместо определения класса. Это может быть удобнее, если у вас нет много настроек:

>>> from django.forms import modelform_factory
>>> from myapp.models import Book
>>> BookForm = modelform_factory(Book, fields=("author", "title"))

Это также можно использовать для внесения изменений в существующие формы, например, задавая виджеты для конкретного поля:

>>> from django.forms import Textarea
>>> Form = modelform_factory(Book, form=BookForm,
...                          widgets={"title": Textarea()})

Поля для включения можно указать, используя ключевые аргументы fields и exclude или соответствующие атрибуты внутреннего класса ModelForm Meta. См. документацию Выбор полей для использования.

… или включить локализация для определённых полей:

>>> Form = modelform_factory(Author, form=AuthorForm, localized_fields=("birth_date",))

Наборы форм модели

class models.BaseModelFormSet

Как и обычные наборы форм, Django предоставляет несколько улучшенных классов наборов форм, чтобы сделать работу с моделями Django более удобной. Давайте повторно используем модель Author из вышеприведённого примера:

>>> from django.forms import modelformset_factory
>>> from myapp.models import Author
>>> AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))

Использование fields ограничивает набор форм использованием только указанных полей. В качестве альтернативы, можно применить подход «исключение», указав, какие поля исключить:

>>> AuthorFormSet = modelformset_factory(Author, exclude=('birth_date',))

Это создаст набор форм, способный работать с данными, связанными с моделью Author. Он работает точно так же, как обычный набор форм:

>>> formset = AuthorFormSet()
>>> print(formset)
<input type="hidden" name="form-TOTAL_FORMS" value="1" id="id_form-TOTAL_FORMS"><input type="hidden" name="form-INITIAL_FORMS" value="0" id="id_form-INITIAL_FORMS"><input type="hidden" name="form-MIN_NUM_FORMS" value="0" id="id_form-MIN_NUM_FORMS"><input type="hidden" name="form-MAX_NUM_FORMS" value="1000" id="id_form-MAX_NUM_FORMS">
<tr><th><label for="id_form-0-name">Name:</label></th><td><input id="id_form-0-name" type="text" name="form-0-name" maxlength="100"></td></tr>
<tr><th><label for="id_form-0-title">Title:</label></th><td><select name="form-0-title" id="id_form-0-title">
<option value="" selected>---------</option>
<option value="MR">Mr.</option>
<option value="MRS">Mrs.</option>
<option value="MS">Ms.</option>
</select><input type="hidden" name="form-0-id" id="id_form-0-id"></td></tr>

Изменение набора запросов

По умолчанию, при создании набора форм из модели, набор форм будет использовать набор запросов, который включает все объекты в модели (например, Author.objects.all()). Вы можете изменить это поведение, используя аргумент queryset:

>>> formset = AuthorFormSet(queryset=Author.objects.filter(name__startswith='O'))

В качестве альтернативы можно создать подкласс, который устанавливает self.queryset в __init__:

from django.forms import BaseModelFormSet
from myapp.models import Author

class BaseAuthorFormSet(BaseModelFormSet):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.queryset = Author.objects.filter(name__startswith='O')

Затем передайте свой класс BaseAuthorFormSet в функцию фабрики:

>>> AuthorFormSet = modelformset_factory(
...     Author, fields=('name', 'title'), formset=BaseAuthorFormSet)

Если вы хотите вернуть набор форм, который не включает никаких предварительно существующих экземпляров модели, вы можете указать пустой набор запросов:

>>> AuthorFormSet(queryset=Author.objects.none())

Изменение формы

По умолчанию, при использовании modelformset_factory, будет создана форма модели с использованием modelform_factory(). Часто бывает полезно указать пользовательскую форму модели. Например, можно создать пользовательскую форму модели с пользовательской валидацией:

class AuthorForm(forms.ModelForm):
    class Meta:
        model = Author
        fields = ('name', 'title')

    def clean_name(self):
        # custom validation for the name field
        ...

Затем передайте вашу форму модели в функцию фабрики:

AuthorFormSet = modelformset_factory(Author, form=AuthorForm)

Определение пользовательской формы модели не всегда необходимо. Функция modelformset_factory имеет несколько аргументов, которые передаются в modelform_factory, которые описаны ниже.

Указание виджетов для использования в форме с widgets

Используя параметр widgets, можно указать словарь значений для настройки класса виджета ModelForm для определённого поля. Это работает так же, как словарь widgets в классе Meta внутренней формы ModelForm:

>>> AuthorFormSet = modelformset_factory(
...     Author, fields=('name', 'title'),
...     widgets={'name': Textarea(attrs={'cols': 80, 'rows': 20})})

Включение локализации для полей с localized_fields

Используя параметр localized_fields, можно включить локализация для полей в форме.

>>> AuthorFormSet = modelformset_factory(
...     Author, fields=('name', 'title', 'birth_date'),
...     localized_fields=('birth_date',))

Если localized_fields установлено в специальное значение '__all__', все поля будут локализованы.

Предоставление начальных значений

Как и с обычными наборами форм, можно указать начальные данные для форм в наборе форм, указав параметр initial при создании класса набора форм модели, возвращаемого modelformset_factory(). Однако, с наборами форм модели, начальные значения применяются только к дополнительным формам, которые не привязаны к существующему экземпляру модели. Если длина initial превышает количество дополнительных форм, избыточные начальные данные игнорируются. Если дополнительные формы с начальными данными не изменяются пользователем, они не будут валидированы или сохранены.

Сохранение объектов в наборе форм

Как и с ModelForm, можно сохранить данные как объект модели. Это делается с помощью метода save() набора форм:

# Create a formset instance with POST data.
>>> formset = AuthorFormSet(request.POST)

# Assuming all is valid, save the data.
>>> instances = formset.save()

Метод save() возвращает экземпляры, которые были сохранены в базе данных. Если данные данного экземпляра не изменились в привязанных данных, экземпляр не будет сохранён в базе данных и не будет включён в возвращаемое значение (instances в примере выше).

Если поля отсутствуют в форме (например, потому что они были исключены), эти поля не будут установлены методом save(). Более подробную информацию об этом ограничении, которое также действует для обычных ModelForms, можно найти в разделе Выбор используемых полей.

Передайте commit=False, чтобы вернуть несохранённые экземпляры модели:

# don't save to the database
>>> instances = formset.save(commit=False)
>>> for instance in instances:
...     # do something with instance
...     instance.save()

Это даёт возможность прикрепить данные к экземплярам перед их сохранением в базе данных. Если ваш набор форм содержит ManyToManyField, вам также нужно вызвать formset.save_m2m(), чтобы убедиться, что многозначные связи сохранены должным образом.

После вызова save(), ваш набор форм модели будет иметь три новых атрибута, содержащих изменения набора форм:

models.BaseModelFormSet.changed_objects

models.BaseModelFormSet.deleted_objects

models.BaseModelFormSet.new_objects

Ограничение количества редактируемых объектов

Как и с обычными наборами форм, можно использовать параметры max_num и extra для modelformset_factory(), чтобы ограничить количество дополнительных форм, отображаемых.

max_num не предотвращает отображение существующих объектов:

>>> Author.objects.order_by('name')
<QuerySet [<Author: Charles Baudelaire>, <Author: Paul Verlaine>, <Author: Walt Whitman>]>

>>> AuthorFormSet = modelformset_factory(Author, fields=('name',), max_num=1)
>>> formset = AuthorFormSet(queryset=Author.objects.order_by('name'))
>>> [x.name for x in formset.get_queryset()]
['Charles Baudelaire', 'Paul Verlaine', 'Walt Whitman']

Кроме того, extra=0 не предотвращает создание новых экземпляров моделей, поскольку вы можете добавлять дополнительные формы с помощью JavaScript или отправлять дополнительные данные POST. Наборы форм ещё не предоставляют функциональности для представления «только для редактирования», которое предотвращает создание новых экземпляров.

Если значение max_num больше количества существующих связанных объектов, до extra дополнительных пустых форм будут добавлены в набор форм, при условии, что общее количество форм не превысит max_num:

>>> AuthorFormSet = modelformset_factory(Author, fields=('name',), max_num=4, extra=2)
>>> formset = AuthorFormSet(queryset=Author.objects.order_by('name'))
>>> for form in formset:
...     print(form.as_table())
<tr><th><label for="id_form-0-name">Name:</label></th><td><input id="id_form-0-name" type="text" name="form-0-name" value="Charles Baudelaire" maxlength="100"><input type="hidden" name="form-0-id" value="1" id="id_form-0-id"></td></tr>
<tr><th><label for="id_form-1-name">Name:</label></th><td><input id="id_form-1-name" type="text" name="form-1-name" value="Paul Verlaine" maxlength="100"><input type="hidden" name="form-1-id" value="3" id="id_form-1-id"></td></tr>
<tr><th><label for="id_form-2-name">Name:</label></th><td><input id="id_form-2-name" type="text" name="form-2-name" value="Walt Whitman" maxlength="100"><input type="hidden" name="form-2-id" value="2" id="id_form-2-id"></td></tr>
<tr><th><label for="id_form-3-name">Name:</label></th><td><input id="id_form-3-name" type="text" name="form-3-name" maxlength="100"><input type="hidden" name="form-3-id" id="id_form-3-id"></td></tr>

Значение max_num, равное None (по умолчанию), устанавливает высокое ограничение на количество отображаемых форм (1000). На практике это эквивалентно отсутствию ограничения.

Использование набора форм модели в представлении

Наборы форм модели очень похожи на наборы форм. Предположим, мы хотим отобразить набор форм для редактирования экземпляров модели Author:

from django.forms import modelformset_factory
from django.shortcuts import render
from myapp.models import Author

def manage_authors(request):
    AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
    if request.method == 'POST':
        formset = AuthorFormSet(request.POST, request.FILES)
        if formset.is_valid():
            formset.save()
            # do something.
    else:
        formset = AuthorFormSet()
    return render(request, 'manage_authors.html', {'formset': formset})

Как видите, логика представления набора форм модели не сильно отличается от логики «обычного» набора форм. Единственное отличие заключается в том, что мы вызываем formset.save() для сохранения данных в базе данных. (Это было описано выше в разделе Сохранение объектов в наборе форм.)

Переопределение clean() в ModelFormSet

Как и с ModelForms, по умолчанию метод clean() набора форм модели будет проверять, что ни один из элементов набора форм не нарушает уникальные ограничения модели (либо unique, либо unique_together, либо unique_for_date|month|year). Если вы хотите переопределить метод clean() набора форм модели и сохранить эту проверку, вы должны вызвать метод родительского класса clean:

from django.forms import BaseModelFormSet

class MyModelFormSet(BaseModelFormSet):
    def clean(self):
        super().clean()
        # example custom validation across forms in the formset
        for form in self.forms:
            # your custom formset validation
            ...

Обратите также внимание, что к тому времени, когда вы дойдёте до этого шага, для каждой Form уже созданы отдельные экземпляры модели. Изменение значения в form.cleaned_data недостаточно для изменения сохранённого значения. Если вы хотите изменить значение в ModelFormSet.clean(), вы должны изменить form.instance:

from django.forms import BaseModelFormSet

class MyModelFormSet(BaseModelFormSet):
    def clean(self):
        super().clean()

        for form in self.forms:
            name = form.cleaned_data['name'].upper()
            form.cleaned_data['name'] = name
            # update the instance value.
            form.instance.name = name

Использование пользовательского набора запросов

Как уже упоминалось, вы можете переопределить набор запросов по умолчанию, используемый набором форм модели:

from django.forms import modelformset_factory
from django.shortcuts import render
from myapp.models import Author

def manage_authors(request):
    AuthorFormSet = modelformset_factory(Author, fields=('name', 'title'))
    if request.method == "POST":
        formset = AuthorFormSet(
            request.POST, request.FILES,
            queryset=Author.objects.filter(name__startswith='O'),
        )
        if formset.is_valid():
            formset.save()
            # Do something.
    else:
        formset = AuthorFormSet(queryset=Author.objects.filter(name__startswith='O'))
    return render(request, 'manage_authors.html', {'formset': formset})

Обратите внимание, что мы передаём аргумент queryset в обоих случаях POST и GET в этом примере.

Использование набора форм в шаблоне

Существует три способа отображения набора форм в шаблоне Django.

Во-первых, вы можете позволить набору форм выполнить большую часть работы:

<form method="post">
    {{ formset }}
</form>

Во-вторых, вы можете вручную отобразить набор форм, но позволить форме справиться с собой:

<form method="post">
    {{ formset.management_form }}
    {% for form in formset %}
        {{ form }}
    {% endfor %}
</form>

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

В-третьих, вы можете вручную отобразить каждое поле:

<form method="post">
    {{ formset.management_form }}
    {% for form in formset %}
        {% for field in form %}
            {{ field.label_tag }} {{ field }}
        {% endfor %}
    {% endfor %}
</form>

Если вы выберете этот третий метод и не будете итерироваться по полям с помощью цикла {% for %}, вам нужно будет отобразить поле первичного ключа. Например, если вы отображаете поля name и age модели:

<form method="post">
    {{ formset.management_form }}
    {% for form in formset %}
        {{ form.id }}
        <ul>
            <li>{{ form.name }}</li>
            <li>{{ form.age }}</li>
        </ul>
    {% endfor %}
</form>

Обратите внимание, что нам нужно явно отобразить {{ form.id }}. Это гарантирует, что набор форм модели, в случае POST, будет работать правильно. (Этот пример предполагает первичный ключ под названием id. Если вы явно определили свой собственный первичный ключ, который не называется id, убедитесь, что он отображается.)

Встроенные наборы форм

class models.BaseInlineFormSet

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

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)

class Book(models.Model):
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    title = models.CharField(max_length=100)

Если вы хотите создать набор форм, который позволит вам редактировать книги, принадлежащие определённому автору, вы можете сделать это:

>>> from django.forms import inlineformset_factory
>>> BookFormSet = inlineformset_factory(Author, Book, fields=('title',))
>>> author = Author.objects.get(name='Mike Royko')
>>> formset = BookFormSet(instance=author)

Префикс BookFormSet — 'book_set' (<model name>_set). Если у BookFormSet связь с Author имеет related_name, то она используется вместо этого.

Переопределение методов в InlineFormSet

При переопределении методов в InlineFormSet следует наследовать от BaseInlineFormSet, а не от BaseModelFormSet.

Например, если вы хотите переопределить clean():

from django.forms import BaseInlineFormSet

class CustomInlineFormSet(BaseInlineFormSet):
    def clean(self):
        super().clean()
        # example custom validation across forms in the formset
        for form in self.forms:
            # your custom formset validation
            ...

См. также Переопределение clean() в наборе форм модели.

Затем, при создании набора форм, передайте необязательный аргумент formset:

>>> from django.forms import inlineformset_factory
>>> BookFormSet = inlineformset_factory(Author, Book, fields=('title',),
...     formset=CustomInlineFormSet)
>>> author = Author.objects.get(name='Mike Royko')
>>> formset = BookFormSet(instance=author)

Несколько внешних ключей к одной и той же модели

Если ваша модель содержит более одного внешнего ключа к одной и той же модели, вам потребуется вручную разрешить неоднозначность, используя fk_name. Например, рассмотрите следующую модель:

class Friendship(models.Model):
    from_friend = models.ForeignKey(
        Friend,
        on_delete=models.CASCADE,
        related_name='from_friends',
    )
    to_friend = models.ForeignKey(
        Friend,
        on_delete=models.CASCADE,
        related_name='friends',
    )
    length_in_months = models.IntegerField()

Для решения этой проблемы вы можете использовать fk_name для inlineformset_factory():

>>> FriendshipFormSet = inlineformset_factory(Friend, Friendship, fk_name='from_friend',
...     fields=('to_friend', 'length_in_months'))

Использование встроенного набора форм в представлении

Возможно, вам нужно предоставить представление, которое позволит пользователю редактировать связанные объекты модели. Вот как это можно сделать:

def manage_books(request, author_id):
    author = Author.objects.get(pk=author_id)
    BookInlineFormSet = inlineformset_factory(Author, Book, fields=('title',))
    if request.method == "POST":
        formset = BookInlineFormSet(request.POST, request.FILES, instance=author)
        if formset.is_valid():
            formset.save()
            # Do something. Should generally end with a redirect. For example:
            return HttpResponseRedirect(author.get_absolute_url())
    else:
        formset = BookInlineFormSet(instance=author)
    return render(request, 'manage_books.html', {'formset': formset})

Обратите внимание, как мы передаём instance в обоих случаях: POST и GET.

Указание виджетов для использования в форме встроенного набора

inlineformset_factory использует modelformset_factory и передаёт большинство своих аргументов в modelformset_factory. Это означает, что вы можете использовать параметр widgets таким же образом, как передавать его в modelformset_factory. Смотрите Указание виджетов для использования в форме с виджетами выше.