Cuando creas una clase Form, la parte más importante es definir los campos del formulario. Cada campo tiene lógica de validación personalizada, junto con unos pocos otros hooks.
Aunque el método principal en que utilizarás las clases Field es en las clases Form, también puedes instanciarlas y usarlas directamente para obtener una mejor idea de cómo funcionan. Cada instancia de Field tiene un método clean(), que toma un argumento único y, o bien lanza una excepción ValidationError de django.core.exceptions o devuelve el valor limpio:
>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("foo@example.com")
'foo@example.com'
>>> f.clean("invalid email address")
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']
Cada constructor de clase Field acepta al menos estos argumentos. Algunas clases Field aceptan argumentos adicionales específicos del campo, pero los siguientes deben ser aceptados siempre:
requerido¶Por defecto, cada clase Field asume que el valor es requerido, por lo que si pasas un valor vacío – ya sea None o la cadena vacía ("") – entonces clean() lanzará una excepción ValidationError:
>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
Para especificar que un campo no es requerido, pasa required=False al constructor de la clase Field:
>>> f = forms.CharField(required=False)
>>> f.clean("foo")
'foo'
>>> f.clean("")
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'
Si un campo tiene required=False y pasas a clean() un valor vacío, entonces clean() devolverá un valor vacío normalizado en lugar de lanzar ValidationError. Para CharField, esto devuelve empty_value que por defecto es una cadena vacía. Para otras clases Field, podría ser None. (Esto varía según el campo.)
Los widgets de los campos formularios requeridos tienen la atributo HTML required. Establece el atributo Form.use_required_attribute en False para deshabilitarlo. El atributo required no se incluye en las formas de formsets porque la validación del navegador puede no ser correcta al agregar y eliminar formsets.
label¶El argumento label te permite especificar el «etiqueta amigable para humanos» para este campo. Se utiliza cuando el Field se muestra en un Form.
Como se explica en Imprimir formas como HTML, la etiqueta predeterminada de un Field se genera a partir del nombre del campo convirtiendo todos los guiones bajos a espacios y poniendo mayúscula la primera letra. Especifica label si ese comportamiento por defecto no da como resultado una etiqueta adecuada.
Aquí tienes un ejemplo completo de Form que implementa label para dos de sus campos. Hemos especificado auto_id=False para simplificar la salida:
>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(label="Your name")
... url = forms.URLField(label="Your website", required=False)
... comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>
label_suffix¶El argumento label_suffix te permite sobreescribir el sufijo de etiqueta del formulario en una base por campo:
>>> class ContactForm(forms.Form):
... age = forms.IntegerField()
... nationality = forms.CharField()
... captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")
...
>>> f = ContactForm(label_suffix="?")
>>> print(f)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>
initial¶El argumento initial te permite especificar el valor inicial a utilizar cuando se renderice este Field en un Form no vinculado.
Para especificar datos iniciales dinámicos, consulta el parámetro Form.initial.
El uso de este caso es cuando deseas mostrar un formulario «vacío» en el que se inicializa un campo a un valor particular. Por ejemplo:
>>> from django import forms
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial="Your name")
... url = forms.URLField(initial="https://")
... comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>
Puede estar pensando, ¿por qué no pasar simplemente un diccionario con los valores iniciales como datos al mostrar el formulario? Bueno, si lo haces, activarás la validación y el HTML de salida incluirá cualquier error de validación:
>>> class CommentForm(forms.Form):
... name = forms.CharField()
... url = forms.URLField()
... comment = forms.CharField()
...
>>> default_data = {"name": "Your name", "url": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
<input type="text" name="name" value="Your name" required>
</div>
<div>Url:
<ul class="errorlist"><li>Enter a valid URL.</li></ul>
<input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
<ul class="errorlist"><li>This field is required.</li></ul>
<input type="text" name="comment" required aria-invalid="true">
</div>
Esto es por qué los valores initial solo se muestran en formularios no vinculados. Los formularios vinculados utilizarán el HTML de salida del datos vinculado.
También tenga en cuenta que los valores initial no se utilizan como «datos de respaldo» en la validación si un campo particular no tiene valor. Los valores initial solo están destinados a mostrar el formulario inicial:
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial="Your name")
... url = forms.URLField(initial="https://")
... comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}
En lugar de una constante, también puedes pasar cualquier llamable:
>>> import datetime
>>> class DateForm(forms.Form):
... day = forms.DateField(initial=datetime.date.today)
...
>>> print(DateForm())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>
La llamable se evaluará solo cuando se muestre el formulario no vinculado, no cuando se defina.
widget¶El argumento widget te permite especificar una clase de Widget para utilizar al renderizar este campo. Consulte Widgets para obtener más información.
help_text¶El argumento help_text te permite especificar texto descriptivo para este campo. Si proporciona help_text, se mostrará junto al campo cuando el campo se renderice mediante uno de los métodos de conveniencia del formulario (por ejemplo, as_ul()).
Like el campo del modelo help_text, este valor no está escapado en HTML en las formas generadas automáticamente.
Aquí tienes un ejemplo completo Form que implementa help_text para dos de sus campos. Hemos especificado auto_id=False para simplificar la salida:
>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
... subject = forms.CharField(max_length=100, help_text="100 characters max.")
... message = forms.CharField()
... sender = forms.EmailField(help_text="A valid email address, please.")
... cc_myself = forms.BooleanField(required=False)
...
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
<div>Cc myself:<input type="checkbox" name="cc_myself"></div>
Cuando un campo tiene texto de ayuda, se asocia con su input utilizando el atributo HTML aria-describedby. Si el widget se renderiza en un <fieldset> entonces aria-describedby se agrega a este elemento, de lo contrario se agrega al input del widget:
>>> from django import forms
>>> class UserForm(forms.Form):
... username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>
Cuando agregas un atributo aria-describedby personalizado, asegúrate de incluir también el id del elemento help_text (si se utiliza) en el orden deseado. Para los usuarios con lectores de pantalla, las descripciones se leerán en su orden de aparición dentro de aria-describedby:
>>> class UserForm(forms.Form):
... username = forms.CharField(
... max_length=255,
... help_text="e.g., user@example.com",
... widget=forms.TextInput(
... attrs={"aria-describedby": "custom-description id_username_helptext"},
... ),
... )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>
Se agregó soporte para <fieldset>.
error_messages¶El argumento error_messages te permite sobreescribir los mensajes de error predeterminados que el campo lanzará. Pasa un diccionario con claves que coincidan con los mensajes de error que deseas sobreescribir. Por ejemplo, aquí está el mensaje de error predeterminado:
>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
Y aquí está un mensaje de error personalizado:
>>> name = forms.CharField(error_messages={"required": "Please enter your name"})
>>> name.clean("")
Traceback (most recent call last):
...
ValidationError: ['Please enter your name']
En la sección Field classes integradas``_ a continuación, cada ``Field define las claves de mensajes de error que utiliza.
validators¶Los textos traducidos son:
Consulte la documentación sobre validadores para obtener más información.
localize¶El argumento localize habilita la localización de los datos de entrada del formulario, así como el resultado renderizado.
Consulte la documentación sobre localización de formato para obtener más información.
disabled¶El argumento booleano disabled, cuando se establece en True, deshabilita un campo del formulario utilizando el atributo HTML disabled para que no sea editable por los usuarios. Incluso si un usuario manipula el valor del campo enviado al servidor, se ignorará a favor del valor de los datos iniciales del formulario.
template_name¶El argumento template_name permite utilizar una plantilla personalizada cuando el campo se renderiza con as_field_group(). Por defecto, este valor está configurado en "django/forms/field.html". Puede ser cambiado por campo mediante la sobrescritura de esta atributo o más generalmente mediante la sobrescripción de la plantilla predeterminada, consulte también sobrescribir-plantillas-de-campos-integrados.
bound_field_class¶La atributo bound_field_class permite una sobrescritura por campo de Form.bound_field_class.
La función has_changed() se utiliza para determinar si el valor del campo ha cambiado desde el valor inicial. Devuelve True o False.
Ver la documentación de Form.has_changed() para obtener más información.
Field¶Naturalmente, la biblioteca forms viene con un conjunto de clases Field que representan necesidades de validación comunes. Esta sección documenta cada campo integrado.
Para cada campo, describimos el widget predeterminado utilizado si no especificas widget. También indicamos el valor devuelto cuando proporcionas un valor vacío (consulte la sección sobre required arriba para entender qué significa eso).
Widget por defecto: CheckboxInput
Valor vacío: False
Normaliza a: Un valor Python True o False.
Valida que el valor sea True (por ejemplo, el cuadro de verificación está seleccionado) si el campo tiene required=True.
Claves de mensajes de error: required
Nota
Dado que todas las subclases de Field tienen required=True por defecto, la condición de validación aquí es importante. Si deseas incluir un booleano en tu formulario que puede ser tanto True como False (por ejemplo, un cuadro de verificación seleccionado o no), debes recordar pasar required=False cuando estés creando el campo BooleanField.
CharField¶Widget predeterminado: TextInput
Valor vacío: Lo que hayas dado como empty_value.
Normaliza a: Una cadena de texto.
Utiliza MaxLengthValidator y MinLengthValidator si se proporcionan max_length y min_length. De lo contrario, todos los inputs son válidos.
Claves de mensajes de error: required, max_length, min_length
Tienes las siguientes argumentos opcionales para la validación:
Si se proporcionan, estos argumentos garantizan que la cadena tenga como máximo o como mínimo la longitud dada.
Si True (por defecto), el valor se despojará de espacios en blanco en la parte delantera y trasera.
El valor a utilizar para representar «vacío». Por defecto, es una cadena vacía.
ChoiceField¶Widget por defecto: Select
Valor vacío: '' (una cadena vacía)
Normaliza a: Una cadena de texto.
Verifica que el valor dado existe en la lista de opciones.
Error message keys: requerido, elección_inválida
La mensaje de error invalid_choice puede contener %(value)s, que se reemplazará con la opción seleccionada.
Toma un argumento extra:
O bien una iterable de 2-tuplas para utilizar como opciones para este campo, tipo de enumeración <field-choices-enum-types>, o una función que devuelve tal iterable. Este argumento acepta los mismos formatos que el argumento choices en un campo de modelo. Consulte la documentación de referencia del campo de modelo sobre opciones para obtener más detalles. Si el argumento es una función, se evalúa cada vez que se inicializa el formulario del campo, además de durante la renderización. Por defecto, es una lista vacía.
Tipo de elección
Este campo normaliza las opciones a cadenas, por lo que si se requieren opciones en otros tipos de datos, como enteros o booleanos, considera utilizar el campo TypedChoiceField en su lugar.
DateField¶Widget predeterminado: DateInput
Valor vacío: None
Normaliza a: Un objeto de Python datetime.date.
Valida que el valor dado es una datetime.date, datetime.datetime o cadena formateada en un formato de fecha particular.
Claves de mensaje de error: required, invalid
Toma un argumento opcional:
Una iterable de formatos utilizados para intentar convertir una cadena a un objeto datetime.date válido.
Si no se proporciona el argumento input_formats, los formatos de entrada por defecto se toman del formato activo de la ubicación DATE_INPUT_FORMATS clave, o desde DATE_INPUT_FORMATS si la localización está deshabilitada. Consulte también localización de formato.
DateTimeField¶Widget predeterminado: DateTimeInput
Valor vacío: None
Normaliza a: Un objeto Python datetime.datetime.
Valida que el valor dado es una datetime.datetime, datetime.date o cadena formateada en un formato de fecha y hora particular.
Claves de mensaje de error: required, invalid
Toma un argumento opcional:
Una iterable de formatos utilizados para intentar convertir una cadena a un objeto datetime.datetime válido, además de los formatos ISO 8601.
El campo siempre acepta cadenas en fechas formateadas en ISO 8601 o similares reconocidas por parse_datetime(). Algunos ejemplos son:
'2006-10-25 14:30:59'
'2006-10-25T14:30:59'
'2006-10-25 14:30'
'2006-10-25T14:30'
'2006-10-25T14:30Z'
'2006-10-25T14:30+02:00'
'2006-10-25'
Si no se proporciona el argumento input_formats, los formatos de entrada por defecto son tomados del formato activo de localización DATETIME_INPUT_FORMATS y DATE_INPUT_FORMATS claves, o desde DATETIME_INPUT_FORMATS y DATE_INPUT_FORMATS si la localización está deshabilitada. Consulta también localización de formato.
DecimalField¶Widget predeterminado: NumberInput cuando Field.localize es False, en caso contrario TextInput.
Valor vacío: None
Normaliza a: Un Python decimal.
Valida que el valor dado es un decimal. Utiliza MaxValueValidator y MinValueValidator si se proporcionan max_value y min_value. Utiliza StepValueValidator si se proporciona step_size. Se ignora el espacio en blanco de cabeza y cola.
Clave de mensaje de error: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size.
Los mensajes de error max_value y min_value pueden contener %(limit_value)s, que se sustituirá por el valor límite adecuado. De manera similar, los mensajes de error max_digits, max_decimal_places y max_whole_digits pueden contener %(max)s.
Acepta cinco argumentos opcionales:
Estos controlan el rango de valores permitidos en el campo, y deben darse como valores decimal.Decimal.
El número máximo de dígitos (los anteriores al punto decimal más los posteriores, con ceros iniciadores eliminados).
El número máximo de decimales permitidos.
Limita los valores de entrada a un múltiplo integral de step_size. Si también se proporciona min_value, se agrega como desplazamiento para determinar si el tamaño del paso coincide.
Widget predeterminado: TextInput
Valor vacío: None
Normaliza a: Un timedelta de Python.
Los textos traducidos son:
Claves de mensaje de error: requerido, inválido, sobrecarga.
Acepta cualquier formato entendido por parse_duration().
Campo de correo electrónico¶Widget predeterminado: EmailInput
Valor vacío: Cualquier cosa que hayas dado como empty_value.
Normaliza a: Una cadena de texto.
Utiliza EmailValidator para validar que el valor dado es una dirección de correo electrónico válida, utilizando una expresión regular compleja moderada.
Claves de mensaje de error: required, invalid
Tiene los argumentos opcionales max_length, min_length y empty_value que funcionan exactamente como lo hacen para CharField. El argumento max_length tiene un valor por defecto de 320 (consulte RFC 3696 Section 3).
Campo de archivo¶Widget predeterminado: ClearableFileInput
Valor vacío: None
Normaliza a: Un objeto UploadedFile que envuelve el contenido del archivo y el nombre del archivo en un solo objeto.
Puede validar que se ha ligado datos de archivos no vacíos al formulario.
Claves de mensajes de error: required, invalid, missing, empty, max_length
Tiene las argumentos opcionales para la validación: max_length y allow_empty_file. Si se proporcionan, estos garantizan que el nombre del archivo no exceda la longitud dada, y que la validación tenga éxito incluso si el contenido del archivo está vacío.
Para obtener más información sobre el objeto UploadedFile, consulte la documentación de subidas de archivos.
Cuando utilices un campo FileField en un formulario, debes recordar también ligar los datos del archivo al formulario. (ligar los datos de archivos).
La clave de error max_length se refiere a la longitud del nombre del archivo. En el mensaje de error para esa clave, %(max)d se reemplazará con la longitud máxima del nombre del archivo y %(length)d se reemplazará con la longitud actual del nombre del archivo.
FilePathField¶Widget por defecto: Select
Valor vacío: '' (una cadena vacía)
Normaliza a: Una cadena de texto.
Valida que la elección seleccionada existe en la lista de opciones.
Error message keys: requerido, elección_inválida
El campo permite elegir archivos dentro de un directorio determinado. Requiere cinco argumentos adicionales; solo path es obligatorio:
El path absoluto del directorio cuyos contenidos deseas listar. Este directorio debe existir.
Si False (el valor por defecto) solo se ofrecerán como opciones los contenidos directos de path. Si True, el directorio se descenderá recursivamente y todos sus descendientes se listarán como opciones.
Un patrón de expresión regular; solo se permitirán archivos con nombres que coincidan con esta expresión como opciones.
Opcional. Puede ser True o False. Por defecto es True. Especifica si los archivos en la ubicación especificada deben incluirse. Debe ser True al menos una de esta opción o allow_folders.
Opcional. Puede ser True o False. Por defecto es False. Especifica si los directorios en la ubicación especificada deben incluirse. Debe ser True al menos una de esta opción o allow_files.
Widget predeterminado: NumberInput cuando Field.localize es False, en caso contrario TextInput.
Valor vacío: None
Normaliza a: Un float Python.
Valida que el valor dado es un float. Utiliza MaxValueValidator y MinValueValidator si se proporcionan max_value y min_value. Utiliza StepValueValidator si se proporciona step_size. Se permite espacio en blanco inicial y final, al igual que la función de Python float().
Claves de mensajes de error: required, invalid, max_value, min_value, step_size.
Toma tres argumentos opcionales:
Estos controlan el rango de valores permitidos en el campo.
Limita los valores de entrada a un múltiplo integral de step_size. Si también se proporciona min_value, se agrega como desplazamiento para determinar si el tamaño del paso coincide.
Un campo que contiene una dirección IP IPv4 o IPv6.
Widget predeterminado: TextInput
Valor vacío: '' (una cadena vacía)
Se normaliza a: Una cadena. Las direcciones IPv6 se normalizan tal como se describe a continuación.
Valida que el valor dado es una dirección IP válida.
Claves de mensajes de error: required, invalid, max_length
La normalización de direcciones IPv6 sigue la RFC 4291 Section 2.2 sección 2.2, incluyendo el uso del formato IPv4 sugerido en el párrafo 3 de esa sección, como ::ffff:192.0.2.0. Por ejemplo, 2001:0::0:01 se normalizaría a 2001::1, y ::ffff:0a0a:0a0a a ::ffff:10.10.10.10. Todos los caracteres se convierten a minúsculas.
Toma tres argumentos opcionales:
Limita las entradas válidas al protocolo especificado. Los valores aceptados son both (por defecto), IPv4 o IPv6. El matching es insensible a mayúsculas y minúsculas.
Desempaca direcciones IPv4 mapeadas como ::ffff:192.0.2.1. Si esta opción está habilitada, esa dirección se desempacaría a 192.0.2.1. El valor por defecto es deshabilitado. Solo puede usarse cuando protocol está configurado en 'both'.
El valor por defecto para max_length se estableció en 39 caracteres.
Widget predeterminado: ClearableFileInput
Valor vacío: None
Normaliza a: Un objeto UploadedFile que envuelve el contenido del archivo y el nombre del archivo en un solo objeto.
Valida que los datos de archivo estén vinculados a la forma. También utiliza FileExtensionValidator para validar que la extensión del archivo está soportada por Pillow.
Claves de mensajes de error: required, invalid, missing, empty, invalid_image
Al utilizar un ImageField, es necesario que pillow esté instalado con el soporte para los formatos de imagen que se utilizan. Si se produce un error de corrupt image al subir una imagen, suele significar que Pillow no entiende su formato. Para solucionarlo, instale la biblioteca correspondiente y reinstale Pillow.
Cuando utilices un ImageField en una forma, debes recordar también vincular los datos de archivo a la forma.
Después de que el campo haya sido limpiado y validado, el objeto UploadedFile tendrá un atributo adicional image que contiene la instancia Pillow Image utilizada para verificar si el archivo era una imagen válida. Pillow cierra el descriptor de archivo subyacente después de verificar una imagen, por lo que mientras que los datos de atributos no relacionados con imágenes, como format, height y width, están disponibles, los métodos que acceden a los datos de la imagen subyacente, como getdata() o getpixel(), no pueden usarse sin reabrir el archivo. Por ejemplo:
>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
... img = forms.ImageField()
...
>>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data["img"]
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>
Además, UploadedFile.content_type se actualizará con el tipo de contenido de la imagen si Pillow puede determinarlo, en caso contrario se establecerá en None.
Widget predeterminado: NumberInput cuando Field.localize es False, en caso contrario TextInput.
Valor vacío: None
Normaliza a: Un entero Python.
Verifica que el valor dado es un entero. Utiliza MaxValueValidator y MinValueValidator si se proporcionan max_value y min_value. Utiliza StepValueValidator si se proporciona step_size. Se permite el espacio en blanco inicial y final, al igual que la función de Python int().
Claves para mensajes de error: required, invalid, max_value, min_value, step_size
Los mensajes de error max_value, min_value y step_size pueden contener %(limit_value)s, que se sustituirá por el valor límite adecuado.
Toma tres argumentos opcionales para la validación:
Estos controlan el rango de valores permitidos en el campo.
Limita los valores de entrada a un múltiplo integral de step_size. Si también se proporciona min_value, se agrega como desplazamiento para determinar si el tamaño del paso coincide.
JSONField¶Un campo que acepta datos codificados en JSON para un JSONField.
Widget predeterminado: Textarea
Valor vacío: None
Normaliza a: Una representación de Python del valor JSON (generalmente como dict, list o None), dependiendo de JSONField.decoder.
Verifica que el valor dado es un JSON válido.
Claves de mensaje de error: required, invalid
Toma dos argumentos opcionales:
A una clase heredada de json.JSONEncoder para serializar tipos de datos no soportados por el serializador JSON estándar (por ejemplo, datetime.datetime o UUID). Por ejemplo, puedes utilizar la clase DjangoJSONEncoder.
Por defecto utiliza json.JSONEncoder.
A una clase heredada de json.JSONDecoder para deserializar la entrada. Tu deserialización puede necesitar tener en cuenta el hecho de que no puedes estar seguro del tipo de entrada. Por ejemplo, corres el riesgo de devolver un datetime que era realmente una cadena que simplemente sucedió estar en el mismo formato elegido para datetime.
El decoder se puede utilizar para validar la entrada. Si se levanta json.JSONDecodeError durante la deserialización, se levantará un ValidationError.
Por defecto utiliza json.JSONDecoder.
Nota
Si utilizas una clase heredada de ModelForm <django.forms.ModelForm>, se utilizarán el encoder y el decoder de JSONField.
Formularios amigables con el usuario
JSONField no es particularmente amigable para los usuarios en la mayoría de los casos. Sin embargo, es una forma útil de formatear datos desde un widget del lado del cliente para su envío al servidor.
Widget por defecto: SelectMultiple
Valor vacío: [] (una lista vacía)
Normaliza a: Una lista de cadenas.
Valida que cada valor en la lista de valores dada existe en la lista de opciones.
Claves de mensajes de error: requerido, opción_inválida, lista_inválida
La mensaje de error invalid_choice puede contener %(value)s, que se reemplazará con la opción seleccionada.
Toma un argumento adicional requerido, choices, igual que para ChoiceField.
NullBooleanField¶Widget predeterminado: NullBooleanSelect
Valor vacío: None
Normaliza a: Un valor Python True, False o None.
No valida nada (es decir, nunca levanta una ValidationError).
Puede usarse NullBooleanField con widgets como Select o RadioSelect proporcionando el widget choices:
NullBooleanField(
widget=Select(
choices=[
("", "Unknown"),
(True, "Yes"),
(False, "No"),
]
)
)
RegexField¶Widget predeterminado: TextInput
Valor vacío: Cualquier cosa que hayas dado como empty_value.
Normaliza a: Una cadena de texto.
Usa la clase ~django.core.validators.RegexValidator para validar que el valor dado coincide con una expresión regular determinada.
Claves de mensaje de error: required, invalid
Toma un argumento requerido:
Una expresión regular especificada como una cadena o un objeto de expresión regular compilado.
También toma max_length, min_length, strip y empty_value que funcionan exactamente igual que para la clase CharField.
Por defecto, es False. Si está habilitado, se aplicará la eliminación antes de la validación de regex.
CampoSlug¶Widget predeterminado: TextInput
Valor vacío: Lo que hayas dado como empty_value.
Normaliza a: Una cadena de texto.
Usa la clase ~django.core.validators.validate_slug o ~django.core.validators.validate_unicode_slug para validar que el valor dado contiene solo letras, números, guiones bajos y guiones.
Mensajes de error: requerido, inválido
Este campo se destaca para su uso en la representación de un modelo SlugField en formularios.
Toma dos parámetros opcionales:
Una booleana que instruye al campo a aceptar letras Unicode además de letras ASCII. Por defecto, es False.
El valor a utilizar para representar «vacío». Por defecto, es una cadena vacía.
TimeField¶Widget por defecto: TimeInput
Valor vacío: None
Normaliza a: Un objeto Python datetime.time.
Valida que el valor dado sea una datetime.time o una cadena formateada en un formato de tiempo particular.
Claves de mensaje de error: required, invalid
Toma un argumento opcional:
Iterable de formatos utilizados para intentar convertir una cadena a un objeto datetime.time válido.
Si no se proporciona la argumento input_formats, los formatos de entrada por defecto se toman del formato activo de ubicación TIME_INPUT_FORMATS clave, o desde TIME_INPUT_FORMATS si la localización está deshabilitada. Consulte también localización de formato.
TypedChoiceField¶Al igual que un ChoiceField, excepto que TypedChoiceField toma dos argumentos adicionales, coerce y empty_value.
Widget por defecto: Select
Valor vacío: Lo que hayas dado como empty_value.
Normaliza a: Un valor del tipo proporcionado por el argumento coerce.
Verifica que el valor dado existe en la lista de opciones y se puede coercer.
Error message keys: requerido, elección_inválida
Toma argumentos adicionales:
Una función que toma un argumento y devuelve un valor coercido. Ejemplos incluyen los tipos integrados int, float y bool. Por defecto, utiliza una función de identidad. Ten en cuenta que la coerción ocurre después de la validación del input, por lo que es posible coercer a un valor no presente en choices.
El valor a utilizar para representar «vacío». Por defecto, se utiliza la cadena vacía; None es otra elección común aquí. Ten en cuenta que este valor no se coercerá por la función proporcionada en el argumento coerce, así que elige con cuidado.
TypedMultipleChoiceField¶Al igual que un MultipleChoiceField, excepto que TypedMultipleChoiceField toma dos argumentos adicionales, coerce y empty_value.
Widget por defecto: SelectMultiple
Valor vacío: Lo que hayas dado como empty_value
Normaliza a: Una lista de valores del tipo proporcionado por el argumento coerce.
Verifica que los valores dados existen en la lista de opciones y se pueden coercer.
Error message keys: requerido, elección_inválida
La mensaje de error invalid_choice puede contener %(value)s, que se reemplazará con la opción seleccionada.
Toma dos argumentos adicionales, coerce y empty_value, al igual que TypedChoiceField.
Campo de URL¶Widget predeterminado: URLInput
Valor vacío: Cualquier cosa que hayas dado como empty_value.
Normaliza a: Una cadena de texto.
Utiliza URLValidator para validar que el valor proporcionado es una URL válida.
Claves de mensaje de error: required, invalid
Tiene los argumentos opcionales max_length, min_length y empty_value que funcionan exactamente como lo hacen en el campo de caracteres CharField, y un argumento adicional:
El esquema asumido para las URL proporcionadas sin uno. Por defecto, se utiliza "http". Por ejemplo, si assume_scheme es "https" y el valor proporcionado es "example.com", el valor normalizado será "https://example.com".
Obsoleto desde la versión 5.0: El valor predeterminado para assume_scheme cambiará de "http" a "https" en Django 6.0. Establezca la configuración transicional FORMS_URLFIELD_ASSUME_HTTPS en True para optar por utilizar "https" durante el ciclo de lanzamiento de Django 5.x.
Campo UUID¶CampoCombo¶Widget predeterminado: TextInput
Valor vacío: '' (una cadena vacía)
Normaliza a: Una cadena de texto.
Valida el valor dado contra cada uno de los campos especificados como argumento del CampoCombo.
Claves de mensaje de error: required, invalid
Toma un argumento adicional requerido:
La lista de campos que deben usarse para validar el valor del campo (en el orden en que se proporcionan).
>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean("test@example.com")
'test@example.com'
>>> f.clean("longemailaddress@example.com")
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']
CampoMultiValor¶Widget predeterminado: TextInput
Valor vacío: '' (una cadena vacía)
Normaliza a: el tipo devuelto por el método compress de la subclase.
Valida el valor dado contra cada uno de los campos especificados como argumento del CampoMultiValor.
Claves de mensajes de error: requerido, inválido, incompleto
Combina la lógica de múltiples campos que producen un valor único.
Este campo es abstracto y debe ser sobrescrito. A diferencia de los campos de valor singular, las subclases de CampoMultiValor no deben implementar clean() sino en su lugar - implementar compress().
Toma un argumento adicional requerido:
Un tuple de campos cuyos valores se limpian y se combinan posteriormente en un valor único. Cada valor del campo se limpia mediante el campo correspondiente en fields – el primer valor se limpia mediante el primer campo, el segundo valor se limpia mediante el segundo campo, etc. Una vez que todos los campos estén limpios, la lista de valores limpios se combina en un valor único mediante compress().
También toma algunas argumentos opcionales:
Por defecto es True, en cuyo caso se levantará una excepción de validación required si no se proporciona ningún valor para ningún campo.
Al establecerse en False, el atributo Field.required puede configurarse como False para campos individuales para hacerlos opcionales. Si no se proporciona ningún valor para un campo requerido, se levantará una excepción de validación incomplete.
Puede definirse un mensaje de error incompleto por defecto en la subclase MultiValueField, o pueden definirse mensajes diferentes en cada campo individual. Por ejemplo:
from django.core.validators import RegexValidator
class PhoneField(MultiValueField):
def __init__(self, **kwargs):
# Define one message for all fields.
error_messages = {
"incomplete": "Enter a country calling code and a phone number.",
}
# Or define a different message for each field.
fields = (
CharField(
error_messages={"incomplete": "Enter a country calling code."},
validators=[
RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."),
],
),
CharField(
error_messages={"incomplete": "Enter a phone number."},
validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")],
),
CharField(
validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")],
required=False,
),
)
super().__init__(
error_messages=error_messages,
fields=fields,
require_all_fields=False,
**kwargs
)
Debe ser una subclase de django.forms.MultiWidget. El valor predeterminado es TextInput, que probablemente no es muy útil en este caso.
Toma una lista de valores válidos y devuelve una versión «comprimida» de esos valores – en un solo valor. Por ejemplo, SplitDateTimeField es una subclase que combina un campo de hora y un campo de fecha en un objeto datetime.
Esta método debe implementarse en las subclases.
SplitDateTimeField¶Widget predeterminado: SplitDateTimeWidget
Valor vacío: None
Normaliza a: Un objeto Python datetime.datetime.
Valida que el valor dado es una datetime.datetime o una cadena formateada en un formato de fecha y hora particular.
Claves de mensajes de error: required, invalid, invalid_date, invalid_time
Toma dos argumentos opcionales:
Una lista de formatos utilizados para intentar convertir una cadena a un objeto datetime.date válido.
Si no se proporciona el argumento input_date_formats, se usan los formatos de entrada predeterminados para DateField.
Una lista de formatos utilizados para intentar convertir una cadena a un objeto datetime.time válido.
Si no se proporciona el argumento input_time_formats, se usan los formatos de entrada predeterminados para TimeField.
Están disponibles dos campos para representar relaciones entre modelos: ModelChoiceField y ModelMultipleChoiceField. Ambos campos requieren un parámetro queryset único que se utiliza para crear las opciones del campo. Al validar el formulario, estos campos colocan en el diccionario cleaned_data del formulario una sola objeto de modelo (en el caso de ModelChoiceField) o múltiples objetos de modelo (en el caso de ModelMultipleChoiceField).
Para usos más complejos, puedes especificar queryset=None cuando declaras el campo del formulario y luego poblar el queryset en el método __init__() del formulario:
class FooMultipleChoiceForm(forms.Form):
foo_select = forms.ModelMultipleChoiceField(queryset=None)
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.fields["foo_select"].queryset = ...
Tanto ModelChoiceField como ModelMultipleChoiceField tienen un atributo iterator que especifica la clase utilizada para iterar sobre el conjunto de resultados cuando se generan las opciones. Consulta Iteración de opciones de relación para obtener más detalles.
ModelChoiceField¶Widget por defecto: Select
Valor vacío: None
Normaliza a: una instancia de modelo.
Valida que el id dado existe en la consulta de conjuntos.
Error message keys: requerido, elección_inválida
La mensaje de error invalid_choice puede contener %(value)s, que se reemplazará con la opción seleccionada.
Permite la selección de un objeto de modelo único, adecuado para representar una clave foránea. Ten en cuenta que el widget predeterminado para ModelChoiceField se vuelve impráctico cuando el número de entradas aumenta. Debes evitar utilizarlo para más de 100 items.
Se requiere un solo argumento:
Un conjunto de consultas de objetos de modelo desde los que se derivan las opciones del campo y que se utiliza para validar la selección del usuario. Se evalúa cuando el formulario se renderiza.
ModelChoiceField también toma varios argumentos opcionales:
Por defecto, el widget <select> utilizado por ModelChoiceField tendrá una opción vacía en la parte superior de la lista. Puedes cambiar el texto de esta etiqueta (que es "---------" por defecto) con la atributo empty_label, o puedes deshabilitar la etiqueta vacía completamente estableciendo empty_label a None:
# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
Ten en cuenta que no se crea ninguna opción vacía (independientemente del valor de empty_label) si un ModelChoiceField es requerido y tiene un valor inicial por defecto, o un widget está configurado para RadioSelect y el argumento blank es False.
Este argumento opcional se utiliza para especificar el campo que utilizar como valor de las opciones en el widget del campo. Asegúrate de que sea un campo único para el modelo, de lo contrario el valor seleccionado podría coincidir con más de un objeto. Por defecto está configurado a None, en cuyo caso se utilizará la clave primaria de cada objeto. Por ejemplo:
# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)
yield
<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>
No hay nada que traducir, solo la palabra «and».
# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
yield
<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>
Cuando se utiliza el widget RadioSelect, este argumento booleano opcional determina si se crea una opción vacía. Por defecto, blank es False, en cuyo caso no se crea ninguna opción vacía.
También tiene la atributo: ModelChoiceField
El clase de iterador utilizado para generar opciones del campo desde queryset. Por defecto, ModelChoiceIterator.
El método __str__() del modelo se llamará para generar representaciones de cadena de los objetos para su uso en las opciones del campo. Para proporcionar representaciones personalizadas, sobreescriba la clase ModelChoiceField y sobrescriba el método label_from_instance. Este método recibirá un objeto del modelo y debería devolver una cadena adecuada para representarlo. Por ejemplo:
from django.forms import ModelChoiceField
class MyModelChoiceField(ModelChoiceField):
def label_from_instance(self, obj):
return "My Object #%i" % obj.id
Widget por defecto: SelectMultiple
Valor vacío: Un conjunto de consultas vacío (self.queryset.none()).
Normaliza a: Un conjunto de consultas (QuerySet) de instancias del modelo.
Verifica que cada id en la lista de valores dada exista en el conjunto de resultados.
Los errores de mensaje claves: requerido, lista_inválida, opción_inválida, valor_pk_inválido
El mensaje opción_inválida puede contener %(value)s y el mensaje valor_pk_inválido puede contener %(pk)s, que se sustituirán por los valores adecuados.
Permite la selección de uno o más objetos del modelo, adecuado para representar una relación muchos-a-muchos. Al igual que con ModelChoiceField, puedes utilizar label_from_instance para personalizar las representaciones de objeto.
Se requiere un solo argumento:
Lo mismo que ModelChoiceField.queryset.
Toma un argumento opcional:
Lo mismo que ModelChoiceField.to_field_name.
También tiene el atributo ModelMultipleChoiceField:
Lo mismo que ModelChoiceField.iterator.
Por defecto, ModelChoiceField y ModelMultipleChoiceField utilizan ModelChoiceIterator para generar sus campos choices.
Al iterar, ModelChoiceIterator devuelve pares de elección 2-tupla que contienen instancias de ModelChoiceIteratorValue como el primer elemento value en cada elección. ModelChoiceIteratorValue envuelve el valor de la elección mientras mantiene una referencia al modelo de origen que puede utilizarse en implementaciones personalizadas de widget, por ejemplo, para agregar atributos data-* a los elementos <option>.
Los textos traducidos son:
from django.db import models
class Topping(models.Model):
name = models.CharField(max_length=100)
price = models.DecimalField(decimal_places=2, max_digits=6)
def __str__(self):
return self.name
class Pizza(models.Model):
topping = models.ForeignKey(Topping, on_delete=models.CASCADE)
Puedes utilizar una clase derivada de Select para incluir el valor de Topping.price como atributo HTML data-price para cada elemento <option>:
from django import forms
class ToppingSelect(forms.Select):
def create_option(
self, name, value, label, selected, index, subindex=None, attrs=None
):
option = super().create_option(
name, value, label, selected, index, subindex, attrs
)
if value:
option["attrs"]["data-price"] = value.instance.price
return option
class PizzaForm(forms.ModelForm):
class Meta:
model = Pizza
fields = ["topping"]
widgets = {"topping": ToppingSelect}
Esto renderizará la selección Pizza.topping como:
<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>
Para un uso más avanzado, puedes derivar ModelChoiceIterator con el fin de personalizar las opciones devueltas.
ModelChoiceIterator¶La clase por defecto asignada a la propiedad iterator de ModelChoiceField y ModelMultipleChoiceField. Un iterable que devuelve 2-tuple opciones desde el conjunto de resultados.
Se requiere un solo argumento:
La instancia de ModelChoiceField o ModelMultipleChoiceField para iterar y devolver opciones.
ModelChoiceIterator tiene los siguientes métodos:
Devuelve opciones en formato 2-tuple (value, label), utilizado por ChoiceField.choices. El primer elemento value es una instancia de ModelChoiceIteratorValue.
ModelChoiceIteratorValue¶Dos argumentos son requeridos:
El valor de la elección. Este valor se utiliza para renderizar el atributo value de un elemento HTML <option>.
La instancia del modelo desde la consulta. La instancia puede ser accedida en implementaciones personalizadas de ChoiceWidget.create_option() para ajustar el HTML renderizado.
ModelChoiceIteratorValue tiene el siguiente método:
Si las clases de campo integradas no satisfacen tus necesidades, puedes crear clases de campo personalizadas. Para hacer esto, crea una subclase de django.forms.Field. Sus únicas requisitos son que implemente un método clean() y que su método __init__() acepte los argumentos básicos mencionados anteriormente (required, label, initial, widget, help_text).
También puedes personalizar cómo se accederá a un campo sobrescribiendo bound_field_class o sobreescribiendo Field.get_bound_field() si necesitas más flexibilidad al crear el BoundField:
Toma una instancia de Form y el nombre del campo. La instancia de BoundField devuelta se utilizará cuando se acceda al campo en un template.
Consulte Customizando BoundField para ejemplos de sobrescritura de un BoundField.
may 31, 2026