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

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

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

Вы можете переопределить сообщения об ошибках, вызванные NON_FIELD_ERRORS валидации модели, добавив ключ NON_FIELD_ERRORS в словарь error_messages внутреннего класса 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() на результирующем экземпляре модели. Это полезно, если вы хотите выполнить пользовательскую обработку объекта перед сохранением или хотите использовать специализированные варианты сохранения модели. commit по умолчанию 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 внутреннего класса 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. Пожалуйста, ознакомьтесь с документацией ModelForm Выбор полей для использования.

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

>>> 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). Если префикс Book для ForeignKey к 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() в ModelFormSet.

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