/
vshmidt
/
django
Обзор
Документация
Войти
/
vshmidt
/
django
Код
Запросы
0
Задачи
Вики
Пакеты
0
Релизы
0
Аналитика
Безопасность
main
docs/ref/forms/models.txt
261 строка
10 KB
Jacob Walls
Fixed a typo in docs/ref/forms/models.txt.
09 янв 2026, 03:10
09 янв 2026, 03:10
f3b982f
Код
Авторство
О чём код?
=========== Model forms =========== .. module:: django.forms.models :synopsis: ModelForm API reference for inner ``Meta`` class and factory functions .. currentmodule:: django.forms ``ModelForm`` API reference. For introductory material about using a ``ModelForm``, see the :doc:`/topics/forms/modelforms` topic guide. Model form ``Meta`` API ======================= .. class:: ModelFormOptions The ``_meta`` API is used to build forms that reflect a Django model. It is accessible through the ``_meta`` attribute of each model form, and is a ``django.forms.models.ModelFormOptions`` instance. The structure of the generated form can be customized by defining metadata options as attributes of an inner ``Meta`` class. For example:: 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 Required attributes are :attr:`~ModelFormOptions.model`, and either :attr:`~ModelFormOptions.fields` or :attr:`~ModelFormOptions.exclude`. All other ``Meta`` attributes are optional. Optional attributes, other than :attr:`~ModelFormOptions.localized_fields` and :attr:`~ModelFormOptions.formfield_callback`, expect a dictionary that maps a model field name to a value. Any field that is not defined in the dictionary falls back to the field's default value. .. admonition:: Invalid field names Invalid or excluded field names in an optional dictionary attribute have no effect, since fields that are not included are not accessed. .. admonition:: Invalid Meta class attributes You may define any attribute on a ``Meta`` class. Typos or incorrect attribute names do not raise an error. ``error_messages`` ------------------ .. attribute:: ModelFormOptions.error_messages A dictionary that maps a model field name to a dictionary of error message keys (``null``, ``blank``, ``invalid``, ``unique``, etc.) mapped to custom error messages. When a field is not specified, Django will fall back on the error messages defined in that model field's :attr:`django.db.models.Field.error_messages` and then finally on the default error messages for that field type. ``exclude`` ----------- .. attribute:: ModelFormOptions.exclude A tuple or list of :attr:`~ModelFormOptions.model` field names to be excluded from the form. Either :attr:`~ModelFormOptions.fields` or :attr:`~ModelFormOptions.exclude` must be set. If neither are set, an :class:`~django.core.exceptions.ImproperlyConfigured` exception will be raised. If :attr:`~ModelFormOptions.exclude` is set and :attr:`~ModelFormOptions.fields` is unset, all model fields, except for those specified in :attr:`~ModelFormOptions.exclude`, are included in the form. ``field_classes`` ----------------- .. attribute:: ModelFormOptions.field_classes A dictionary that maps a model field name to a :class:`~django.forms.Field` class, which overrides the ``form_class`` used in the model field's :meth:`.Field.formfield` method. When a field is not specified, Django will fall back on the model field's :ref:`default field class <model-form-field-types>`. ``fields`` ---------- .. attribute:: ModelFormOptions.fields A tuple or list of :attr:`~ModelFormOptions.model` field names to be included in the form. The value ``'__all__'`` can be used to specify that all fields should be included. If any field is specified in :attr:`~ModelFormOptions.exclude`, this will not be included in the form despite being specified in :attr:`~ModelFormOptions.fields`. Either :attr:`~ModelFormOptions.fields` or :attr:`~ModelFormOptions.exclude` must be set. If neither are set, an :class:`~django.core.exceptions.ImproperlyConfigured` exception will be raised. ``formfield_callback`` ---------------------- .. attribute:: ModelFormOptions.formfield_callback A function or callable that takes a model field and returns a :class:`django.forms.Field` object. ``help_texts`` -------------- .. attribute:: ModelFormOptions.help_texts A dictionary that maps a model field name to a help text string. When a field is not specified, Django will fall back on that model field's :attr:`~django.db.models.Field.help_text`. ``labels`` ---------- .. attribute:: ModelFormOptions.labels A dictionary that maps a model field names to a label string. When a field is not specified, Django will fall back on that model field's :attr:`~django.db.models.Field.verbose_name` and then the field's attribute name. ``localized_fields`` -------------------- .. attribute:: ModelFormOptions.localized_fields A tuple or list of :attr:`~ModelFormOptions.model` field names to be localized. The value ``'__all__'`` can be used to specify that all fields should be localized. By default, form fields are not localized, see :ref:`enabling localization of fields <modelforms-enabling-localization-of-fields>` for more details. ``model`` --------- .. attribute:: ModelFormOptions.model Required. The :class:`django.db.models.Model` to be used for the :class:`~django.forms.ModelForm`. ``widgets`` ----------- .. attribute:: ModelFormOptions.widgets A dictionary that maps a model field name to a :class:`django.forms.Widget`. When a field is not specified, Django will fall back on the default widget for that particular type of :class:`django.db.models.Field`. Model form factory functions ============================ .. currentmodule:: django.forms.models ``modelform_factory`` --------------------- .. function:: 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) Returns a :class:`~django.forms.ModelForm` class for the given ``model``. You can optionally pass a ``form`` argument to use as a starting point for constructing the ``ModelForm``. ``fields`` is an optional list of field names. If provided, only the named fields will be included in the returned fields. ``exclude`` is an optional list of field names. If provided, the named fields will be excluded from the returned fields, even if they are listed in the ``fields`` argument. ``formfield_callback`` is a callable that takes a model field and returns a form field. ``widgets`` is a dictionary of model field names mapped to a widget. ``localized_fields`` is a list of names of fields which should be localized. ``labels`` is a dictionary of model field names mapped to a label. ``help_texts`` is a dictionary of model field names mapped to a help text. ``error_messages`` is a dictionary of model field names mapped to a dictionary of error messages. ``field_classes`` is a dictionary of model field names mapped to a form field class. See :ref:`modelforms-factory` for example usage. You must provide the list of fields explicitly, either via keyword arguments ``fields`` or ``exclude``, or the corresponding attributes on the form's inner ``Meta`` class. See :ref:`modelforms-selecting-fields` for more information. Omitting any definition of the fields to use will result in an :exc:`~django.core.exceptions.ImproperlyConfigured` exception. ``modelformset_factory`` ------------------------ .. function:: 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) Returns a ``FormSet`` class for the given ``model`` class. Arguments ``model``, ``form``, ``fields``, ``exclude``, ``formfield_callback``, ``widgets``, ``localized_fields``, ``labels``, ``help_texts``, ``error_messages``, and ``field_classes`` are all passed through to :func:`~django.forms.models.modelform_factory`. Arguments ``formset``, ``extra``, ``can_delete``, ``can_order``, ``max_num``, ``validate_max``, ``min_num``, ``validate_min``, ``absolute_max``, ``can_delete_extra``, and ``renderer`` are passed through to :func:`~django.forms.formsets.formset_factory`. See :doc:`formsets </topics/forms/formsets>` for details. The ``edit_only`` argument allows :ref:`preventing new objects creation <model-formsets-edit-only>`. See :ref:`model-formsets` for example usage. ``inlineformset_factory`` ------------------------- .. function:: 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) Returns an ``InlineFormSet`` using :func:`modelformset_factory` with defaults of ``formset=``:class:`~django.forms.models.BaseInlineFormSet`, ``can_delete=True``, and ``extra=3``. If your model has more than one :class:`~django.db.models.ForeignKey` to the ``parent_model``, you must specify a ``fk_name``. See :ref:`inline-formsets` for example usage.