Referencia del API de ModelForm. Para material introductorio sobre el uso de un ModelForm, consulte la guía de temas Creación de formularios desde modelos.
La API _meta se utiliza para crear formularios que reflejan un modelo Django. Está accesible a través de la propiedad _meta de cada modelo de formulario, y es una instancia de django.forms.models.ModelFormOptions.
La estructura de la forma generada puede ser personalizada definiendo opciones de metadatos como atributos de una clase Meta interna. Por ejemplo:
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
Los atributos obligatorios son model, y ya sea fields o exclude. Todos los otros atributos de la clase Meta son opcionales.
Los atributos opcionales, excepto localized_fields y formfield_callback, esperan un diccionario que mapea el nombre de un campo del modelo a un valor. Cualquier campo que no esté definido en el diccionario recae en el valor por defecto del campo.
Nombres de campos inválidos
Los nombres de campos inválidos o excluidos en un atributo de diccionario opcional no tienen efecto, ya que los campos que no se incluyen no se acceden.
error_messages¶Un diccionario que mapea el nombre de un campo del modelo a un diccionario de claves de mensajes de error (null, blank, invalid, unique, etc.) a mensajes de error personalizados.
Cuando no se especifica un campo, Django recae en los mensajes de error definidos en el campo django.db.models.Field.error_messages del modelo y luego finalmente en los mensajes de error por defecto para ese tipo de campo.
exclude¶Una lista de tuplas o listas de nombres de campos del modelo (model) que se deben excluir del formulario.
O bien, debe establecerse fields o exclude. Si no se establecen ninguno de los dos, se levantará una excepción ImproperlyConfigured. Si se establece exclude y no se establece fields, se incluirán todos los campos del modelo, excepto aquellos especificados en exclude.
field_classes¶Un diccionario que mapea el nombre de un campo del modelo a una clase de campo (Field), lo que sobreescribe la form_class utilizada en el método Field.formfield() del campo del modelo.
Cuando no se especifica un campo, Django caerá en el campo de clase por defecto del campo del modelo (default field class).
fields¶Una tupla o lista de nombres de campos del modelo (model) que se deben incluir en el formulario. El valor '__all__' puede usarse para especificar que todos los campos deben ser incluidos.
Si se especifica algún campo en exclude, no se incluirá en el formulario a pesar de estar especificado en fields.
O bien, debe establecerse fields o exclude. Si no se establecen ninguno de los dos, se levantará una excepción ImproperlyConfigured.
formfield_callback¶Una función o llamable que toma un campo del modelo y devuelve un objeto de campo (django.forms.Field).
Un diccionario que mapea nombres de campos de modelo a una cadena de etiqueta.
Cuando un campo no está especificado, Django recaerá en el nombre verbal del campo de ese modelo (verbose_name) y luego en el nombre de atributo del campo.
Una tupla o lista de nombres de campos model a ser localizados. El valor '__all__' se puede utilizar para especificar que todos los campos deben ser localizados.
Por defecto, los campos de formulario no están localizados, consulta activar la localización de campos para obtener más detalles.
model¶Requerido. El django.db.models.Model a utilizar para el ModelForm.
Un diccionario que mapea un nombre de campo de modelo a una django.forms.Widget.
Cuando no se especifica un campo, Django caerá en el widget predeterminado para ese tipo particular de django.db.models.Field.
modelform_factory¶Devuelve una clase ModelForm para el modelo dado. Puedes pasar opcionalmente un argumento form para utilizar como punto de partida para la construcción del ModelForm.
fields es una lista opcional de nombres de campo. Si se proporciona, solo los campos nombrados se incluirán en los campos devueltos.
exclude es una lista opcional de nombres de campo. Si se proporciona, los campos nombrados se excluirán de los campos devueltos, incluso si están listados en el argumento fields.
formfield_callback es un llamable que toma un campo de modelo y devuelve un campo de formulario.
widgets es un diccionario de nombres de campo de modelo mapeado a un widget.
Los textos traducidos son:
etiquetas es un diccionario de nombres de campos del modelo mapeados a una etiqueta.
textos_de_ayuda es un diccionario de nombres de campos del modelo mapeados a un texto de ayuda.
mensajes_de_error es un diccionario de nombres de campos del modelo mapeados a un diccionario de mensajes de error.
clases_de_campo es un diccionario de nombres de campos del modelo mapeados a una clase de campo de formulario.
Consulte la sección La función de fábrica de ModelForm para ver un ejemplo de uso.
Debes proporcionar explícitamente la lista de campos, ya sea mediante argumentos de palabra clave fields o exclude, o las correspondientes atributos en la clase Meta interna del formulario. Consulte Seleccionando los campos a utilizar para obtener más información. Omitir cualquier definición de los campos a utilizar dará como resultado una excepción ImproperlyConfigured.
modelformset_factory¶Devuelve una clase FormSet para la clase del modelo dada.
Los argumentos model, form, fields, exclude, formfield_callback, widgets, campos_localizados, etiquetas, textos_de_ayuda, mensajes_de_error y clases_de_campo se pasan todos a modelform_factory().
Los textos traducidos son:
El argumento edit_only permite evitar la creación de nuevos objetos.
Consulte Formularios de modelos para ver un ejemplo de uso.
inlineformset_factory¶Devuelve un conjunto de formularios InlineFormSet utilizando modelformset_factory() con los valores por defecto de formset=BaseInlineFormSet, can_delete=True y extra=3.
Si tu modelo tiene más de un campo ForeignKey a la parent_model, debes especificar un fk_name.
Consulte Conjuntos de formularios en línea para ver un ejemplo de uso.
may 31, 2026