FormulärfältLink to this heading#

krävsLink to this heading#

Field.requiredLink to this definition#

Som standard antar varje Field-klass att värdet är obligatoriskt, så om du skickar ett tomt värde - antingen None eller den tomma strängen ("") - kommer clean() att ge upphov till ett ValidationError undantag:

>>> 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'

För att ange att ett fält inte är obligatoriskt, skicka required=False till konstruktören 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'

Om en Field har required=False och du ger clean() ett tomt värde, så kommer clean() att returnera ett normaliserat tomt värde istället för att ge upphov till ValidationError. För CharField kommer detta att returnera empty_value som standard är en tom sträng. För andra klasser av Field kan det vara None. (Detta varierar från fält till fält.)

Widgets för obligatoriska formulärfält har HTML-attributet required. Ställ in attributet Form.use_required_attribute till False för att inaktivera det. Attributet required ingår inte i formulär för formuläruppsättningar eftersom webbläsarens validering kanske inte är korrekt när formuläruppsättningar läggs till och tas bort.

etikettLink to this heading#

Field.labelLink to this definition#

Med argumentet label kan du ange den ”människovänliga” etiketten för detta fält. Detta används när Field visas i en Form.

As explained in Utmatning av formulär som HTML, the default label for a Field is generated from the field name by converting all underscores to spaces and upper-casing the first letter. Specify a string for label if that default behavior doesn’t result in an adequate label. Use an empty string ("") to hide the label.

Här är ett fullständigt exempel på Form som implementerar label för två av sina fält. Vi har angett auto_id=False för att förenkla utdata:

>>> 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_suffixLink to this heading#

Field.label_suffixLink to this definition#

Med argumentet label_suffix kan du åsidosätta formulärets label_suffix för varje enskilt fält:

>>> 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>

initialLink to this heading#

Field.initialLink to this definition#

Med argumentet initial kan du ange det initiala värde som ska användas när detta Field återges i ett obundet Form.

För att ange dynamiska initialdata, se parametern Form.initial.

Användningsfallet för detta är när du vill visa ett ”tomt” formulär där ett fält är initialiserat till ett visst värde. Ett exempel:

>>> 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>

Du kanske tänker, varför inte bara skicka en ordbok med de ursprungliga värdena som data när du visar formuläret? Tja, om du gör det kommer du att utlösa validering och HTML-utdata kommer att innehålla eventuella valideringsfel:

>>> 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>

Det är därför som ”initial”-värden bara visas för obundna formulär. För bundna formulär kommer HTML-utdata att använda de bundna uppgifterna.

Observera också att ”initiala” värden inte används som ”fallback”-data vid validering om värdet för ett visst fält inte anges. initial-värden är endast avsedda för initial visning av formuläret:

>>> 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.']}

I stället för en konstant kan du också skicka en valfri callable:

>>> 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>

Callable kommer att utvärderas först när det obundna formuläret visas, inte när det definieras.

widgetLink to this heading#

Field.widgetLink to this definition#

Med argumentet widget kan du ange en Widget-klass som ska användas vid rendering av detta Field. Se Widgets för mer information.

hjälp_textLink to this heading#

Field.help_textLink to this definition#

Med argumentet help_text kan du ange en beskrivande text för detta Field. Om du anger help_text kommer den att visas bredvid Field när Field återges med en av de praktiska Form-metoderna (t.ex. as_ul()).

Precis som modellfältets help_text, är detta värde inte HTML-escaped i automatiskt genererade formulär.

Här är ett fullständigt exempel på en Form som implementerar help_text för två av sina fält. Vi har angett auto_id=False för att förenkla utdata:

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text="100 characters max.")
...     message = forms.CharField()
...     contact_email = forms.EmailField(help_text="Your email (so we can reply).")
...
>>> 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>Contact email:<div class="helptext">Your email (so we can reply).</div><input type="email" name="contact_email" maxlength="320" required></div>

När ett fält har en hjälptext associeras den med dess inmatning med hjälp av HTML-attributet aria-describedby. Om widgeten återges i en <fieldset> läggs aria-describedby till i detta element, annars läggs det till i widgetens <input>:

>>> 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>

När du lägger till ett anpassat aria-describedby-attribut, se till att även inkludera id för help_text-elementet (om det används) i önskad ordning. För användare av skärmläsare kommer beskrivningarna att läsas i den ordning de förekommer i 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>

FelmeddelandenLink to this heading#

Field.error_messagesLink to this definition#

Med argumentet error_messages kan du åsidosätta de standardmeddelanden som fältet kommer att ge upphov till. Skicka in en ordbok med nycklar som matchar de felmeddelanden som du vill åsidosätta. Här är t.ex. standardfelmeddelandet:

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

Och här är ett anpassat felmeddelande:

>>> name = forms.CharField(error_messages={"required": "Please enter your name"})
>>> name.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

I avsnittet inbyggda fältklasser nedan definierar varje fält de felmeddelandenycklar som används.

validerareLink to this heading#

Field.validatorsLink to this definition#

Med argumentet validators kan du ange en lista över valideringsfunktioner för detta fält.

Se validators dokumentation för mer information.

lokaliseraLink to this heading#

Field.localizeLink to this definition#

Argumentet localize gör det möjligt att lokalisera inmatning av formulärdata samt den renderade utdata.

Se format localization documentation för mer information.

inaktiveradLink to this heading#

Field.disabledLink to this definition#

Det booleska argumentet disabled, när det sätts till True, inaktiverar ett formulärfält som använder HTML-attributet disabled så att det inte kan redigeras av användarna. Även om en användare manipulerar fältets värde som skickas till servern, kommer det att ignoreras till förmån för värdet från formulärets ursprungliga data.

template_nameLink to this heading#

Field.template_nameLink to this definition#

Argumentet template_name tillåter en anpassad mall som ska användas när fältet återges med as_field_group(). Som standard är detta värde inställt på "django/forms/field.html". Kan ändras per fält genom att åsidosätta detta attribut eller mer allmänt genom att åsidosätta standardmallen, se även Åsidosätta inbyggda fältmallar.

bound_field_classLink to this heading#

Field.bound_field_classLink to this definition#

Attributet bound_field_class gör det möjligt att för varje fält åsidosätta Form.bound_field_class.

has_changed()Link to this heading#

Field.has_changed()Link to this definition#

Metoden has_changed() används för att avgöra om fältvärdet har ändrats från det ursprungliga värdet. Returnerar True eller False.

See the Form.has_changed documentation for more information.

BooleanFieldLink to this heading#

class BooleanField(**kwargs)Link to this definition#

• Standardwidget: CheckboxInput

• Tomt värde: False

• Normaliseras till: Ett Python-värde av typen True eller False.

• Validerar att värdet är True (t.ex. att kryssrutan är markerad) om fältet har required=True.

• Felmeddelande nycklar: krävs

CharFieldLink to this heading#

class CharField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: En sträng.

• Använder MaxLengthValidator och MinLengthValidator om max_length och min_length anges. Annars är alla inmatningar giltiga.

• Nycklar för felmeddelande: required, max_length, min_length

Har följande valfria argument för validering:

max_lengthLink to this definition#

min_lengthLink to this definition#

Om dessa argument anges säkerställer de att strängen är högst eller minst den angivna längden.

stripLink to this definition#

Om True (standard), kommer värdet att rensas från inledande och efterföljande blanksteg.

empty_valueLink to this definition#

Det värde som ska användas för att representera ”tom”. Standardvärdet är en tom sträng.

ValFieldLink to this heading#

class ChoiceField(**kwargs)Link to this definition#

• Standardwidget: Select

• Tomt värde: '' (en tom sträng)

• Normaliseras till: En sträng.

• Validerar att det angivna värdet finns i listan med valmöjligheter.

• Nycklar för felmeddelanden: krävs, ogiltigt_val

Felmeddelandet invalid_choice kan innehålla %(value)s, som kommer att ersättas med det valda alternativet.

Kräver ett extra argument:

choicesLink to this definition#

Antingen en iterabel av 2-tuples att använda som val för detta fält, enumerationstyp, eller en callable som returnerar en sådan iterabel. Detta argument accepterar samma format som argumentet choices till ett modellfält. Se modellfältets referensdokumentation om choices för mer information. Om argumentet är en callable utvärderas det varje gång fältets form initieras, förutom under rendering. Standardvärdet är en tom lista.

DateFieldLink to this heading#

class DateField(**kwargs)Link to this definition#

• Standardwidget: DateInput

• Tomt värde: None

• Normaliseras till: Ett Python-objekt av typen datetime.date.

• Validerar att det angivna värdet är antingen ett datetime.date, datetime.datetime eller en sträng formaterad i ett visst datumformat.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Tar emot ett valfritt argument:

input_formatsLink to this definition#

En iterabel av format som används för att försöka konvertera en sträng till ett giltigt datetime.date-objekt.

Om inget input_formats-argument anges hämtas standardinmatningsformaten från det aktiva lokala formatet DATE_INPUT_FORMATS, eller från DATE_INPUT_FORMATS om lokalisering är inaktiverad. Se även format localization.

DatumTimeFieldLink to this heading#

class DateTimeField(**kwargs)Link to this definition#

• Standardwidget: DateTimeInput

• Tomt värde: None

• Normaliseras till: Ett Python-objekt av typen datetime.datetime.

• Validerar att det angivna värdet är antingen en datetime.datetime, datetime.date eller en sträng formaterad i ett visst datetime-format.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Tar emot ett valfritt argument:

input_formatsLink to this definition#

En iterabel av format som används för att försöka konvertera en sträng till ett giltigt datetime.datetime-objekt, utöver ISO 8601-format.

Fältet accepterar alltid strängar i ISO 8601-formaterade datum eller liknande som känns igen av parse_datetime(). Några exempel är:

• '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'

Om inget input_formats-argument anges hämtas standardinmatningsformaten från det aktiva lokala formatet DATETIME_INPUT_FORMATS och DATE_INPUT_FORMATS-nycklar, eller från DATETIME_INPUT_FORMATS och DATE_INPUT_FORMATS om lokalisering är inaktiverad. Se även format localization.

DecimalFieldLink to this heading#

class DecimalField(**kwargs)Link to this definition#

• Standardwidget: NumberInput när Field.localize är False, annars TextInput.

• Tomt värde: None

• Normaliseras till: En Python decimal.

• Validerar att det angivna värdet är en decimal. Använder MaxValueValidator och MinValueValidator om max_value och min_value anges. Använder StepValueValidator om step_size anges. Ledande och efterföljande blanksteg ignoreras.

• Nycklar för felmeddelanden: required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits, step_size.

Felmeddelandena max_value och min_value kan innehålla %(limit_value)s, som kommer att ersättas med lämplig gräns. På samma sätt kan felmeddelandena max_digits, max_decimal_places och max_whole_digits innehålla %(max)s.

Tar emot fem valfria argument:

max_valueLink to this definition#

min_valueLink to this definition#

Dessa styr det intervall av värden som tillåts i fältet och bör anges som decimal.decimal-värden.

max_digitsLink to this definition#

Det maximala antalet siffror (de före decimaltecknet plus de efter decimaltecknet, med inledande nollor borttagna) som tillåts i värdet.

decimal_placesLink to this definition#

Det maximala antalet decimaler som tillåts.

step_sizeLink to this definition#

Begränsa giltiga indata till en integrerad multipel av step_size. Om min_value också anges läggs det till som en förskjutning för att avgöra om stegstorleken matchar.

DurationFieldLink to this heading#

class DurationField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: None

• Normaliseras till: En Python timedelta.

• Validerar att det angivna värdet är en sträng som kan konverteras till en timedelta. Värdet måste ligga mellan datetime.timedelta.min och datetime.timedelta.max.

• Nycklar för felmeddelanden: krävs, ogiltigt, överflöde.

Accepterar alla format som förstås av parse_duration().

EmailFieldLink to this heading#

class EmailField(**kwargs)Link to this definition#

• Standardwidget: EmailInput

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: En sträng.

• Använder EmailValidator för att validera att det angivna värdet är en giltig e-postadress, med hjälp av ett måttligt komplext reguljärt uttryck.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Har de valfria argumenten max_length, min_length och empty_value som fungerar precis som de gör för CharField. Argumentet max_length är som standard 320 (se RFC 3696 Section 3).

FileFieldLink to this heading#

class FileField(**kwargs)Link to this definition#

• Standardwidget: ClearableFileInput

• Tomt värde: None

• Normaliseras till: Ett UploadedFile-objekt som sammanfattar filinnehållet och filnamnet i ett enda objekt.

• Kan validera att icke-tom filinformation har bundits till formuläret.

• Nycklar för felmeddelanden: krävs, ogiltigt, `` saknas``, tomt, max_längd

Har de valfria argumenten för validering: max_length och allow_empty_file. Om de anges säkerställer de att filnamnet har högst den angivna längden och att valideringen lyckas även om filinnehållet är tomt.

Mer information om objektet UploadedFile finns i dokumentation om filuppladdningar.

När du använder en FileField i ett formulär måste du också komma ihåg att binda filinformationen till formuläret.

Felet max_length hänvisar till filnamnets längd. I felmeddelandet för den nyckeln kommer %(max)d att ersättas med den maximala filnamnslängden och %(length)d kommer att ersättas med den aktuella filnamnslängden.

FilePathFieldLink to this heading#

class FilePathField(**kwargs)Link to this definition#

• Standardwidget: Select

• Tomt värde: '' (en tom sträng)

• Normaliseras till: En sträng.

• Kontrollerar att det valda alternativet finns i listan med alternativ.

• Nycklar för felmeddelanden: krävs, ogiltigt_val

Fältet gör det möjligt att välja bland filer i en viss katalog. Det tar fem extra argument; endast path är obligatoriskt:

pathLink to this definition#

Den absoluta sökvägen till den katalog vars innehåll du vill lista. Denna katalog måste existera.

recursiveLink to this definition#

Om False (standard) kommer endast det direkta innehållet i path att erbjudas som val. Om True, kommer katalogen att vara rekursivt nedåtgående och alla nedåtgående kommer att listas som val.

matchLink to this definition#

Ett mönster för ett reguljärt uttryck; endast filer med namn som matchar detta uttryck kommer att tillåtas som val.

allow_filesLink to this definition#

Optional. Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

allow_foldersLink to this definition#

Optional. Either True or False. Default is False. Specifies whether folders in the specified location should be included. Either this or allow_files must be True.

FilePathField has the following method:

set_choices()Link to this definition#

Scans the directory at path and refreshes the field’s choices. This is called automatically during __init__(), but it can also be called explicitly to pick up files added to the directory after the field was first instantiated (usually at server startup). For example, call it in a form’s __init__() to get fresh choices per request:

Code

class MyForm(forms.Form):
    my_file = forms.FilePathField(path="/path/to/dir")

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["my_file"].set_choices()

FloatFieldLink to this heading#

class FloatField(**kwargs)Link to this definition#

• Standardwidget: NumberInput när Field.localize är False, annars TextInput.

• Tomt värde: None

• Normaliseras till: En Python-flottör.

• Validerar att det angivna värdet är en float. Använder MaxValueValidator och MinValueValidator om max_value och min_value anges. Använder StepValueValidator om step_size anges. Ledande och efterföljande blanktecken är tillåtna, som i Pythons funktion float().

• Nycklar för felmeddelanden: required, invalid, max_value, min_value, step_size.

Tar emot tre valfria argument:

max_valueLink to this definition#

min_valueLink to this definition#

Dessa styr det värdeintervall som tillåts i fältet.

step_sizeLink to this definition#

Begränsa giltiga indata till en integrerad multipel av step_size. Om min_value också anges läggs det till som en förskjutning för att avgöra om stegstorleken matchar.

GenericIPAddressFieldLink to this heading#

class GenericIPAddressField(**kwargs)Link to this definition#

Ett fält som innehåller antingen en IPv4- eller en IPv6-adress.

• Standardwidget: TextInput

• Tomt värde: '' (en tom sträng)

• Normaliseras till: En sträng. IPv6-adresser normaliseras enligt beskrivningen nedan.

• Kontrollerar att det angivna värdet är en giltig IP-adress.

• Nycklar för felmeddelanden: required, invalid, max_length

Normaliseringen av IPv6-adresser följer RFC 4291 Section 2.2 avsnitt 2.2, inklusive användning av det IPv4-format som föreslås i punkt 3 i det avsnittet, som ::ffff:192.0.2.0. Till exempel: skulle 2001:0::0:01 normaliseras till 2001::1, och ::ffff:0a0a:0a0a till ::ffff:10.10.10.10. Alla tecken konverteras till gemener.

Tar emot tre valfria argument:

protocolLink to this definition#

Begränsar giltiga indata till det angivna protokollet. Accepterade värden är both (standard), IPv4 eller IPv6. Matchningen är okänslig för skiftlägesanalys.

unpack_ipv4Link to this definition#

Packar upp IPv4-mappade adresser som ::ffff:192.0.2.1. Om detta alternativ är aktiverat kommer den adressen att packas upp till 192.0.2.1. Standard är inaktiverat. Kan endast användas när protocol är inställt på 'both'.

max_lengthLink to this definition#

Standardvärdet är 39 och fungerar på samma sätt som för CharField.

ImageFieldLink to this heading#

class ImageField(**kwargs)Link to this definition#

• Standardwidget: ClearableFileInput

• Tomt värde: None

• Normaliseras till: Ett UploadedFile-objekt som sammanfattar filinnehållet och filnamnet i ett enda objekt.

• Validerar att fildata har bundits till formuläret. Använder även FileExtensionValidator för att validera att filändelsen stöds av Pillow.

• Nycklar för felmeddelanden: krävs, ogiltig, `` saknas``, tomt, ogiltig_bild

För att använda en ImageField krävs att pillow är installerat med stöd för de bildformat du använder. Om du stöter på ett corrupt image-fel när du laddar upp en bild, betyder det vanligtvis att Pillow inte förstår dess format. För att åtgärda detta installerar du lämpligt bibliotek och installerar om Pillow.

När du använder en ImageField på ett formulär måste du också komma ihåg att binda filinformationen till formuläret.

Efter att fältet har rensats och validerats kommer objektet UploadedFile att ha ett ytterligare image-attribut som innehåller Pillow Image-instansen som används för att kontrollera om filen var en giltig bild. Pillow stänger den underliggande filbeskrivaren efter att ha verifierat en bild, så medan attribut för icke-bilddata, t.ex. format, höjd och bredd, är tillgängliga, kan metoder som får åtkomst till underliggande bilddata, t.ex. getdata() eller getpixel(), inte användas utan att öppna filen igen. Ett exempel:

Python console

>>> 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>

Dessutom kommer UploadedFile.content_type att uppdateras med bildens innehållstyp om Pillow kan bestämma den, annars kommer den att sättas till None.

IntegerFieldLink to this heading#

class IntegerField(**kwargs)Link to this definition#

• Standardwidget: NumberInput när Field.localize är False, annars TextInput.

• Tomt värde: None

• Normaliseras till: Ett heltal i Python.

• Validerar att det givna värdet är ett heltal. Använder MaxValueValidator och MinValueValidator om max_value och min_value anges. Använder StepValueValidator om step_size anges. Ledande och efterföljande blanktecken är tillåtna, som i Pythons funktion int().

• Nycklar för felmeddelanden: required, invalid, max_value, min_value, step_size

Felmeddelandena max_value, min_value och step_size kan innehålla %(limit_value)s, som ersätts med lämplig gräns.

Tar emot tre valfria argument för validering:

max_valueLink to this definition#

min_valueLink to this definition#

Dessa styr det värdeintervall som tillåts i fältet.

step_sizeLink to this definition#

Begränsa giltiga indata till en integrerad multipel av step_size. Om min_value också anges läggs det till som en förskjutning för att avgöra om stegstorleken matchar.

JSONFieldLink to this heading#

class JSONField(encoder=None, decoder=None, **kwargs)Link to this definition#

Ett fält som tar emot JSON-kodade data för en JSONField.

• Standardwidget: Textarea

• Tomt värde: None

• Normaliseras till: En Python-representation av JSON-värdet (vanligtvis som en dict, list eller None), beroende på JSONField.decoder.

• Validerar att det angivna värdet är en giltig JSON.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Tar två valfria argument:

encoderLink to this definition#

A json.JSONEncoder subclass to serialize data types not supported by the standard JSON serializer (e.g. datetime.datetime or UUID). For example, you can use the DjangoJSONEncoder class.

Standardvärdet är json.JSONEncoder.

decoderLink to this definition#

A json.JSONDecoder subclass to deserialize the input. Your deserialization may need to account for the fact that you can’t be certain of the input type. For example, you run the risk of returning a datetime that was actually a string that just happened to be in the same format chosen for datetimes.

The decoder can be used to validate the input. If json.JSONDecodeError is raised during the deserialization, a ValidationError will be raised.

Standardvärdet är json.JSONDecoder.

MultipleChoiceFieldLink to this heading#

class MultipleChoiceField(**kwargs)Link to this definition#

• Standardwidget: SelectMultiple

• Tomt värde: [] (en tom lista)

• Normaliserar till: En lista med strängar.

• Validerar att alla värden i den angivna listan med värden finns i listan med val.

• Nycklar för felmeddelanden: required, invalid_choice, invalid_list

Felmeddelandet invalid_choice kan innehålla %(value)s, som kommer att ersättas med det valda alternativet.

Tar ett extra obligatoriskt argument, choices, som för ChoiceField.

NullBooleanFieldLink to this heading#

class NullBooleanField(**kwargs)Link to this definition#

• Standardwidget: NullBooleanSelect

• Tomt värde: None

• Normaliseras till: Ett Python-värde av typen True, False eller None.

• Validerar ingenting (d.v.s. det ger aldrig upphov till ett ValidationError).

NullBooleanField kan användas med widgetar som Select eller RadioSelect genom att tillhandahålla widgeten choices:

Code

NullBooleanField(
    widget=Select(
        choices=[
            ("", "Unknown"),
            (True, "Yes"),
            (False, "No"),
        ]
    )
)

RegexFieldLink to this heading#

class RegexField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: En sträng.

• Använder RegexValidator för att validera att det angivna värdet matchar ett visst reguljärt uttryck.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Kräver ett argument:

regexLink to this definition#

Ett reguljärt uttryck som anges antingen som en sträng eller som ett kompilerat objekt för reguljära uttryck.

Tar också max_length, min_length, strip och empty_value som fungerar precis som de gör för CharField.

stripLink to this definition#

Standardvärdet är False. Om aktiverat kommer stripping att tillämpas före regex-valideringen.

SlugFieldLink to this heading#

class SlugField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: En sträng.

• Använder validate_slug eller validate_unicode_slug för att validera att det angivna värdet endast innehåller bokstäver, siffror, understreck och bindestreck.

• Felmeddelanden: krävs, ogiltigt

Detta fält är avsett att användas för att representera en modell SlugField i formulär.

Tar emot två valfria parametrar:

allow_unicodeLink to this definition#

En boolean som instruerar fältet att acceptera Unicode-bokstäver utöver ASCII-bokstäver. Standardvärdet är False.

empty_valueLink to this definition#

Det värde som ska användas för att representera ”tom”. Standardvärdet är en tom sträng.

TimeFieldLink to this heading#

class TimeField(**kwargs)Link to this definition#

• Standardwidget: TimeInput

• Tomt värde: None

• Normaliseras till: Ett Python-objekt av typen datetime.time.

• Validerar att det angivna värdet är antingen en datetime.time eller en sträng formaterad i ett visst tidsformat.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Tar emot ett valfritt argument:

input_formatsLink to this definition#

En iterabel av format som används för att försöka konvertera en sträng till ett giltigt datetime.time-objekt.

Om inget input_formats-argument anges hämtas standardinmatningsformaten från det aktiva lokala formatet TIME_INPUT_FORMATS, eller från TIME_INPUT_FORMATS om lokalisering är inaktiverad. Se även format localization.

TypedChoiceFieldLink to this heading#

class TypedChoiceField(**kwargs)Link to this definition#

Precis som en ChoiceField, men TypedChoiceField tar två extra argument, coerce och empty_value.

• Standardwidget: Select

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: Ett värde av den typ som anges av argumentet coerce.

• Validerar att det angivna värdet finns i listan med val och kan tvingas fram.

• Nycklar för felmeddelanden: krävs, ogiltigt_val

Tar extra argument:

coerceLink to this definition#

En funktion som tar ett argument och returnerar ett tvingat värde. Exempel är de inbyggda typerna int, float, bool och andra typer. Standardvärdet är en identitetsfunktion. Observera att tvingande sker efter validering av indata, så det är möjligt att tvinga till ett värde som inte finns i choices.

empty_valueLink to this definition#

Det värde som ska användas för att representera ”tom” Standardvärdet är den tomma strängen; None är ett annat vanligt val här. Observera att det här värdet inte kommer att tvingas fram av den funktion som anges i argumentet coerce, så välj det i enlighet med detta.

Typ av flervalsfältLink to this heading#

class TypedMultipleChoiceField(**kwargs)Link to this definition#

Precis som en MultipleChoiceField, förutom att TypedMultipleChoiceField tar två extra argument, coerce och empty_value.

• Standardwidget: SelectMultiple

• Tomt värde: Vad du än har angett som empty_value

• Normaliseras till: En lista med värden av den typ som anges i argumentet coerce.

• Validerar att de angivna värdena finns i listan med val och kan tvingas.

• Nycklar för felmeddelanden: krävs, ogiltigt_val

Felmeddelandet invalid_choice kan innehålla %(value)s, som kommer att ersättas med det valda alternativet.

Tar två extra argument, coerce och empty_value, som för TypedChoiceField.

URL-fältLink to this heading#

class URLField(**kwargs)Link to this definition#

• Standardwidget: URLInput

• Tomt värde: Vad du än har angett som empty_value.

• Normaliseras till: En sträng.

• Använder URLValidator för att validera att det angivna värdet är en giltig URL.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Har de valfria argumenten max_length, min_length, empty_value som fungerar precis som de gör för CharField, och ytterligare ett argument:

assume_schemeLink to this definition#

The scheme assumed for URLs provided without one. Defaults to "https". For example, if assume_scheme is "https" and the provided value is "example.com", the normalized value will be "https://example.com".

UUIDFieldLink to this heading#

class UUIDField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: None

• Normaliseras till: Ett UUID-objekt.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Detta fält accepterar alla strängformat som accepteras som hex-argument till UUID-konstruktören.

ComboFieldLink to this heading#

class ComboField(**kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: '' (en tom sträng)

• Normaliseras till: En sträng.

• Validerar det angivna värdet mot vart och ett av de fält som angetts som argument till ComboField.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt

Kräver ett extra argument:

fieldsLink to this definition#

Lista över fält som ska användas för att validera fältets värde (i den ordning de anges).

Python console

>>> 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).']

MultiValueFieldLink to this heading#

class MultiValueField(fields=(), **kwargs)Link to this definition#

• Standardwidget: TextInput

• Tomt värde: '' (en tom sträng)

• Normaliserar till: den typ som returneras av compress-metoden i underklassen.

• Validerar det angivna värdet mot vart och ett av de fält som angetts som argument till MultiValueField.

• Nycklar för felmeddelanden: ”Obligatoriskt”, ”Ogiltigt”, ”Ofullständigt

Sammanställer logiken i flera fält som tillsammans ger ett enda värde.

Detta fält är abstrakt och måste underklassas. Till skillnad från envärdesfälten får underklasser av MultiValueField inte implementera clean() utan istället - implementera compress().

Kräver ett extra argument:

fieldsLink to this definition#

A tuple of fields whose values are cleaned and subsequently combined into a single value. Each value of the field is cleaned by the corresponding field in fields – the first value is cleaned by the first field, the second value is cleaned by the second field, etc. Once all fields are cleaned, the list of clean values is combined into a single value by compress().

Tar också några valfria argument:

require_all_fieldsLink to this definition#

Standardvärdet är True, i vilket fall ett required valideringsfel kommer att uppstå om inget värde anges för något fält.

När attributet Field.required är satt till False kan det sättas till False för enskilda fält för att göra dem valfria. Om inget värde anges för ett obligatoriskt fält kommer valideringsfelet incomplete att uppstå.

Ett standardfelmeddelande incomplete kan definieras för underklassen MultiValueField, eller så kan olika meddelanden definieras för varje enskilt fält. Till exempel:

Code

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
        )

widgetLink to this definition#

Måste vara en underklass till django.forms.MultiWidget. Standardvärdet är TextInput, vilket förmodligen inte är särskilt användbart i det här fallet.

compress(data_list)Link to this definition#

Tar en lista med giltiga värden och returnerar en ”komprimerad” version av dessa värden - i ett enda värde. Exempelvis är SplitDateTimeField en underklass som kombinerar ett tidsfält och ett datumfält till ett datetime-objekt.

Denna metod måste implementeras i underklasserna.

SplitDateTimeFieldLink to this heading#

class SplitDateTimeField(**kwargs)Link to this definition#

• Standardwidget: SplitDateTimeWidget

• Tomt värde: None

• Normaliseras till: Ett Python-objekt av typen datetime.datetime.

• Validerar att det angivna värdet är en datetime.datetime eller en sträng formaterad i ett visst datetime-format.

• Nycklar för felmeddelanden: required, invalid, invalid_date, invalid_time

Tar två valfria argument:

input_date_formatsLink to this definition#

En lista över format som används för att försöka konvertera en sträng till ett giltigt datetime.date-objekt.

Om inget input_date_formats-argument anges används standardformaten för inmatning för DateField.

input_time_formatsLink to this definition#

En lista över format som används för att försöka konvertera en sträng till ett giltigt datetime.time-objekt.

Om inget input_time_formats-argument anges används standardformaten för inmatning för TimeField.

ModellValFieldLink to this heading#

class ModelChoiceField(**kwargs)Link to this definition#

• Standardwidget: Select

• Tomt värde: None

• Normaliseras till: En modellinstans.

• Validerar att det angivna id:et finns i frågeuppsättningen.

• Nycklar för felmeddelanden: krävs, ogiltigt_val

Felmeddelandet invalid_choice kan innehålla %(value)s, som kommer att ersättas med det valda alternativet.

Gör det möjligt att välja ett enda modellobjekt, lämpligt för att representera en främmande nyckel. Observera att standardwidgeten för ModelChoiceField blir opraktisk när antalet poster ökar. Du bör undvika att använda den för mer än 100 poster.

Ett enda argument krävs:

querysetLink to this definition#

En QuerySet av modellobjekt från vilka valmöjligheterna för fältet härleds och som används för att validera användarens val. Den utvärderas när formuläret renderas.

ModelChoiceField tar också flera valfria argument:

empty_labelLink to this definition#

By default the <select> widget used by ModelChoiceField will have an empty choice at the top of the list. You can change the text of this label (which is "- Select an option -" by default) with the empty_label attribute, or you can disable the empty label entirely by setting empty_label to None:

Code

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

Observera att inget tomt val skapas (oavsett värdet på empty_label) om en ModelChoiceField krävs och har ett standardinitialvärde, eller om en widget är inställd på RadioSelect och argumentet blank är False.

to_field_nameLink to this definition#

Detta valfria argument används för att ange det fält som ska användas som värde för valen i fältets widget. Se till att det är ett unikt fält för modellen, annars kan det valda värdet matcha mer än ett objekt. Som standard är det inställt på None, i vilket fall primärnyckeln för varje objekt kommer att användas. Till exempel:

Code

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

skulle ge:

Html

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

och:

Code

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

skulle ge:

Html

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

blankLink to this definition#

När du använder widgeten RadioSelect, avgör detta valfria booleska argument om ett tomt val skapas. Som standard är blank False, i vilket fall inget tomt val skapas.

ModelChoiceField har också attributet:

iteratorLink to this definition#

Den iteratorklass som används för att generera fältval från queryset. Som standard används ModelChoiceIterator.

Metoden __str__() i modellen kommer att anropas för att generera strängrepresentationer av objekten för användning i fältets val. För att tillhandahålla anpassade representationer, subklassa ModelChoiceField och åsidosätt label_from_instance. Denna metod tar emot ett modellobjekt och ska returnera en sträng som är lämplig för att representera det. Till exempel:

Code

from django.forms import ModelChoiceField


class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

ModellMultipleChoiceFieldLink to this heading#

class ModelMultipleChoiceField(**kwargs)Link to this definition#

• Standardwidget: SelectMultiple

• Tomt värde: En tom QuerySet (self.queryset.none())

• Normaliseras till: En QuerySet av modellinstanser.

• Validerar att varje id i den angivna listan med värden finns i queryset.

• Nycklar för felmeddelanden: required, invalid_list, invalid_choice, invalid_pk_value

Meddelandet invalid_choice kan innehålla %(value)s och meddelandet invalid_pk_value kan innehålla %(pk)s, som kommer att ersättas med lämpliga värden.

Tillåter val av ett eller flera modellobjekt, lämpligt för att representera en många-till-många-relation. Precis som med ModelChoiceField kan du använda label_from_instance för att anpassa objektrepresentationerna.

Ett enda argument krävs:

querysetLink to this definition#

Samma som ModelChoiceField.queryset.

Tar emot ett valfritt argument:

to_field_nameLink to this definition#

Samma som ModelChoiceField.to_field_name.

ModelMultipleChoiceField har också attributet:

iteratorLink to this definition#

Samma som ModelChoiceField.iterator.

Iteration av relationsvalLink to this heading#

Som standard använder ModelChoiceField och ModelMultipleChoiceField ModelChoiceIterator för att generera fältets choices.

Vid iteration ger ModelChoiceIterator 2-tupelval som innehåller ModelChoiceIteratorValue-instanser som det första value-elementet i varje val. ModelChoiceIteratorValue omsluter valvärdet samtidigt som det bibehåller en referens till källmodellinstansen som kan användas i anpassade widgetimplementeringar, till exempel för att lägga till data-* attribut till <option> element.

Tänk till exempel på följande modeller:

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)

Du kan använda en Select widgetunderklass för att inkludera värdet av Topping.price som HTML-attributet data-price för varje <option> element:

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}

Detta kommer att göra Pizza.topping-valet som:

<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>

För mer avancerad användning kan du subklassa ModelChoiceIterator för att anpassa de 2-tupelval som erhålls.