# Django 5.2.8 documentation

# 模型表单

`ModelForm` API reference. For introductory material about using a `ModelForm`, see the 从模型创建表单 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 an `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 `model`, and either `fields` or `exclude`. All other `Meta` attributes are optional.

Optional attributes, other than `localized_fields` and `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.

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.

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`

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 `django.db.models.Field.error_messages` and then finally on the default error messages for that field type.

### `exclude`

ModelFormOptions.exclude

  A tuple or list of `model` field names to be excluded from the form.

  Either `fields` or `exclude` must be set. If neither are set, an `ImproperlyConfigured` exception will be raised. If `exclude` is set and `fields` is unset, all model fields, except for those specified in `exclude`, are included in the form.

### `field_classes`

ModelFormOptions.field_classes

  A dictionary that maps a model field name to a `Field` class, which overrides the `form_class` used in the model field's `Field.formfield()` method.

  When a field is not specified, Django will fall back on the model field's default field class.

### `fields`

ModelFormOptions.fields

  A tuple or list of `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 `exclude`, this will not be included in the form despite being specified in `fields`.

  Either `fields` or `exclude` must be set. If neither are set, an `ImproperlyConfigured` exception will be raised.

### `formfield_callback`

ModelFormOptions.formfield_callback

  A function or callable that takes a model field and returns a `django.forms.Field` object.

### `help_texts`

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 `help_text`.

### `labels`

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 `verbose_name` and then the field's attribute name.

### `localized_fields`

ModelFormOptions.localized_fields

  A tuple or list of `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 enabling localization of fields for more details.

### `model`

ModelFormOptions.model

  Required. The `django.db.models.Model` to be used for the `ModelForm`.

### `widgets`

ModelFormOptions.widgets

  A dictionary that maps a model field name to a `django.forms.Widget`.

  When a field is not specified, Django will fall back on the default widget for that particular type of `django.db.models.Field`.

## Model form factory functions

### `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)

  为给定的 `model` 返回一个 `ModelForm` 类。你可以选择性地传递一个 `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)

  返回给定 `model` 类的 `FormSet` 类。

  参数 `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)

  使用 `modelformset_factory()` 返回一个 `InlineFormSet`，默认值为 `formset=``BaseInlineFormSet`、`can_delete=True` 和 `extra=3`。

  如果你的模型有多个 `ForeignKey` 到 `parent_model`，你必须指定一个 `fk_name`。

  参见 内联表单集 的用法示例。