Referens till modellfält¶

Det här dokumentet innehåller alla API-referenser för Field inklusive de field options och field types som Django erbjuder.

Se även

Om de inbyggda fälten inte räcker till kan du prova django-localflavor (dokumentation), som innehåller olika kodstycken som är användbara för vissa länder och kulturer.

Du kan också enkelt skriva dina egna anpassade modellfält.

Observera

Fält definieras i django.db.models.fields, men för enkelhetens skull importeras de till django.db.models. Standardkonventionen är att använda from django.db import models och referera till fält som models.<Foo>Field.

Alternativ för fält¶

Följande argument är tillgängliga för alla fälttyper. Alla är valfria.

`null`¶

Field.null¶

Om True, kommer Django att lagra tomma värden som NULL i databasen. Standard är False.

Undvik att använda null på strängbaserade fält som CharField och TextField. Django-konventionen är att använda en tom sträng, inte NULL, som ”inga data”-tillstånd för strängbaserade fält. Om ett strängbaserat fält har null=False kan tomma strängar fortfarande sparas för ”inga data”. Om ett strängbaserat fält har null=True, betyder det att det har två möjliga värden för ”no data”: NULL och den tomma strängen. I de flesta fall är det överflödigt att ha två möjliga värden för ”no data”. Ett undantag är när en CharField har både unique=True och blank=True inställda. I den här situationen krävs null=True för att undvika brott mot unika begränsningar när flera objekt med tomma värden sparas.

För både strängbaserade och icke-strängbaserade fält måste du också ange blank=True om du vill tillåta tomma värden i formulär, eftersom parametern null endast påverkar databaslagring (se blank).

Observera

Vid användning av Oracle databas backend kommer värdet NULL att lagras för att beteckna den tomma strängen oavsett detta attribut.

`blank`¶

Field.blank¶

Om True, får fältet vara tomt. Standard är False.

Observera att detta skiljer sig från null. null är rent databasrelaterat, medan blank är valideringsrelaterat. Om ett fält har blank=True, tillåter formulärvalidering att ett tomt värde anges. Om ett fält har blank=False kommer fältet att vara obligatoriskt.

Tillhandahållande av saknade värden

blank=True kan användas med fält som har null=False, men detta kommer att kräva implementering av clean() på modellen för att programmatiskt tillhandahålla eventuella saknade värden.

`val`¶

Field.choices[source]¶

En mappning eller iterabel i det format som beskrivs nedan för att användas som val för detta fält. Om val anges, verkställs de av modellvalidering och standardformulärwidgeten kommer att vara en valbox med dessa val istället för standardtextfältet.

Om en mappning anges är nyckelelementet det faktiska värde som ska anges i modellen och det andra elementet är det lättlästa namnet. Till exempel:

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

Du kan också skicka en sequence som i sig består av iterabler med exakt två element (t.ex. [(A1, B1), (A2, B2), ...]). Det första elementet i varje tupel är det faktiska värde som ska anges i modellen, och det andra elementet är det mänskligt läsbara namnet. Till exempel:

YEAR_IN_SCHOOL_CHOICES = [
    ("FR", "Freshman"),
    ("SO", "Sophomore"),
    ("JR", "Junior"),
    ("SR", "Senior"),
    ("GR", "Graduate"),
]

choices kan också definieras som en callable som inte förväntar sig några argument och som returnerar något av de format som beskrivs ovan. Till exempel:

def get_currencies():
    return {i: i for i in settings.CURRENCIES}


class Expense(models.Model):
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    currency = models.CharField(max_length=3, choices=get_currencies)

Att skicka en callable för choices kan vara särskilt praktiskt när, till exempel, alternativen är:

resultatet av I/O-bundna operationer (som potentiellt kan cachas), t.ex. att fråga en tabell i samma eller en extern databas, eller att komma åt val från en statisk fil.
en lista som för det mesta är stabil men som kan variera från tid till annan eller från projekt till projekt. Exempel i denna kategori är att använda tredjepartsappar som tillhandahåller en välkänd förteckning över värden, t.ex. valutor, länder, språk, tidszoner etc.

I allmänhet är det bäst att definiera val i en modellklass och att definiera en konstant med lämpligt namn för varje värde:

from django.db import models


class Student(models.Model):
    FRESHMAN = "FR"
    SOPHOMORE = "SO"
    JUNIOR = "JR"
    SENIOR = "SR"
    GRADUATE = "GR"
    YEAR_IN_SCHOOL_CHOICES = {
        FRESHMAN: "Freshman",
        SOPHOMORE: "Sophomore",
        JUNIOR: "Junior",
        SENIOR: "Senior",
        GRADUATE: "Graduate",
    }
    year_in_school = models.CharField(
        max_length=2,
        choices=YEAR_IN_SCHOOL_CHOICES,
        default=FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {self.JUNIOR, self.SENIOR}

Du kan definiera en lista med val utanför en modellklass och sedan hänvisa till den, men om du definierar valen och namnen för varje val i modellklassen behålls all denna information i den klass som använder den och hjälper till att hänvisa till valen (t.ex. fungerar Student.SOPHOMORE överallt där modellen Student har importerats).

Du kan också samla dina tillgängliga val i namngivna grupper som kan användas för organisatoriska ändamål:

MEDIA_CHOICES = {
    "Audio": {
        "vinyl": "Vinyl",
        "cd": "CD",
    },
    "Video": {
        "vhs": "VHS Tape",
        "dvd": "DVD",
    },
    "unknown": "Unknown",
}

Mappningens nyckel är det namn som ska användas för gruppen och värdet är alternativen i gruppen, som består av fältvärdet och ett lättläst namn för ett alternativ. Grupperade alternativ kan kombineras med ogrupperade alternativ i en enda mappning (som alternativet "unknown" i det här exemplet).

Du kan också använda en sekvens, t.ex. en lista med 2-tupler:

MEDIA_CHOICES = [
    (
        "Audio",
        (
            ("vinyl", "Vinyl"),
            ("cd", "CD"),
        ),
    ),
    (
        "Video",
        (
            ("vhs", "VHS Tape"),
            ("dvd", "DVD"),
        ),
    ),
    ("unknown", "Unknown"),
]

Observera att val kan vara vilket sekvensobjekt som helst - inte nödvändigtvis en lista eller tupel. Detta gör att du kan konstruera val dynamiskt. Men om du hackar choices för att vara dynamisk, är det förmodligen bättre att använda en riktig databastabell med en ForeignKey. choices är avsedd för statiska data som inte ändras mycket, om ens någonsin.

Observera

En ny migration skapas varje gång ordningen på valen ändras.

För varje modellfält som har choices inställt, kommer Django att normalisera valen till en lista med 2-tuples och lägga till en metod för att hämta det mänskliga läsbara namnet för fältets aktuella värde. Se get_FOO_display() i API-dokumentationen för databasen.

Om inte blank=False anges för fältet tillsammans med default kommer en etikett som innehåller "---------" att återges med valboxen. Om du vill åsidosätta detta beteende lägger du till en tupel i choices som innehåller None, t.ex. (None, 'Your String For Display'). Alternativt kan du använda en tom sträng istället för None där detta är meningsfullt - till exempel på en CharField.

Uppräkningstyper¶

Dessutom tillhandahåller Django enumerationstyper som du kan underklassa för att definiera val på ett koncist sätt:

from django.utils.translation import gettext_lazy as _


class Student(models.Model):
    class YearInSchool(models.TextChoices):
        FRESHMAN = "FR", _("Freshman")
        SOPHOMORE = "SO", _("Sophomore")
        JUNIOR = "JR", _("Junior")
        SENIOR = "SR", _("Senior")
        GRADUATE = "GR", _("Graduate")

    year_in_school = models.CharField(
        max_length=2,
        choices=YearInSchool,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

Dessa fungerar på liknande sätt som enum från Pythons standardbibliotek, men med vissa ändringar:

Enum-medlemsvärden är en tupel av argument som ska användas när den konkreta datatypen konstrueras. Django stöder att lägga till ett extra strängvärde i slutet av denna tuple som ska användas som det mänskliga läsbara namnet, eller label. label kan vara en lat översättningsbar sträng. I de flesta fall kommer alltså medlemsvärdet att vara en (värde, etikett) 2-tupel. Se nedan för :ref:ett exempel på underklassning av val <field-choices-enum-subclassing>` med en mer komplex datatyp. Om en tupel inte tillhandahålls, eller om det sista objektet inte är en (lat) sträng, är ``label :ref:``automatiskt genererad <field-choices-enum-auto-label>` från medlemsnamnet.
En .label-egenskap läggs till på värden för att returnera det mänskligt läsbara namnet.
Ett antal anpassade egenskaper läggs till i uppräkningsklasserna - .choices, .labels, .values och .names - för att göra det lättare att komma åt listor över dessa separata delar av uppräkningen.

Varning

Dessa egenskapsnamn kan inte användas som medlemsnamn eftersom de då skulle stå i konflikt med varandra.
Användningen av enum.unique() är tvingande för att säkerställa att värden inte kan definieras flera gånger. Det är osannolikt att detta förväntas i val för ett fält.

Observera att användning av YearInSchool.SENIOR, YearInSchool['SENIOR'] eller YearInSchool('SR') för att komma åt eller slå upp enum-medlemmar fungerar som förväntat, liksom egenskaperna .name och .value på medlemmarna.

Om du inte behöver översätta de lättlästa namnen kan du låta dem härledas från medlemsnamnet (genom att ersätta understreck med mellanslag och använda titelfas):

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

Eftersom fallet där enumvärdena måste vara heltal är extremt vanligt, tillhandahåller Django en IntegerChoices-klass. Till exempel:

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

Det är också möjligt att använda Enum Functional API med förbehållet att etiketter genereras automatiskt enligt ovan:

>>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD")
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]

Om du behöver stöd för en annan konkret datatyp än int eller str kan du subklassa Choices och den nödvändiga konkreta datatypen, t.ex. date för användning med DateField:

class MoonLandings(datetime.date, models.Choices):
    APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)"
    APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)"
    APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)"
    APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)"
    APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)"
    APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)"

Det finns några ytterligare förbehåll att vara medveten om:

Uppräkningstyper stöder inte :ref:``namngivna grupper <field-choices-named-groups>`.
Eftersom en uppräkning med en konkret datatyp kräver att alla värden matchar typen, kan åsidosättande av blank label inte uppnås genom att skapa en medlem med värdet None. Istället ställer du in attributet __empty__ på klassen:
```
class Answer(models.IntegerChoices):
    NO = 0, _("No")
    YES = 1, _("Yes")

    __empty__ = _("(Unknown)")
```

`db_kolumn`¶

Field.db_column¶

Namnet på den databaskolumn som ska användas för detta fält. Om detta inte anges kommer Django att använda fältets namn.

Om kolumnnamnet i din databas är ett reserverat SQL-ord eller innehåller tecken som inte är tillåtna i Python-variabelnamn - särskilt bindestrecket - är det OK. Django citerar kolumn- och tabellnamn bakom kulisserna.

`db_kommentar`¶

Field.db_comment¶

Kommentaren till den databaskolumn som ska användas för detta fält. Det är användbart för att dokumentera fält för personer med direkt databasåtkomst som kanske inte tittar på din Django-kod. Till exempel:

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

`db_default`¶

Field.db_default¶

Det databasberäknade standardvärdet för detta fält. Detta kan vara ett bokstavligt värde eller en databasfunktion, t.ex. Now:

created = models.DateTimeField(db_default=Now())

Mer komplexa uttryck kan användas, så länge de är uppbyggda av literaler och databasfunktioner:

month_due = models.DateField(
    db_default=TruncMonth(
        Now() + timedelta(days=90),
        output_field=models.DateField(),
    )
)

Databasens standardvärden kan inte referera till andra fält eller modeller. Detta är till exempel ogiltigt:

end = models.IntegerField(db_default=F("start") + 50)

Om både db_default och Field.default` är inställda kommer default att ha företräde när instanser skapas i Python-kod. db_default kommer fortfarande att vara inställt på databasnivå och kommer att användas när rader infogas utanför ORM eller när ett nytt fält läggs till i en migrering.

Om ett fält har ett db_default utan att ett default har angetts och inget värde har tilldelats fältet, returneras ett DatabaseDefault-objekt som fältvärde på osparade modellinstanser. Det faktiska värdet för fältet bestäms av databasen när modellinstansen sparas.

`db_index`¶

Field.db_index¶

Om True, skapas ett databasindex för detta fält.

Använd alternativet indexes istället.

Där det är möjligt, använd alternativet Meta.indexes istället. I nästan alla fall ger indexes mer funktionalitet än db_index. db_index kan bli föråldrad i framtiden.

`db_tablespace`¶

Field.db_tablespace[source]¶

Namnet på database tablespace som ska användas för fältets index, om fältet är indexerat. Standardvärdet är projektets DEFAULT_INDEX_TABLESPACE-inställning, om den är inställd, eller modellens db_tablespace, om det finns någon. Om backend inte stöder tablespaces för index, ignoreras detta alternativ.

`standard`¶

Field.default¶

Standardvärdet för fältet. Detta kan vara ett värde eller ett anropsbart objekt. Om det är anropsbart kommer det att anropas varje gång ett nytt objekt skapas.

Standardvärdet kan inte vara ett föränderligt objekt (modellinstans, list, set, etc.), eftersom en referens till samma instans av det objektet skulle användas som standardvärde i alla nya modellinstanser. Istället kan du paketera det önskade standardvärdet i en callable. Om du till exempel vill ange en standard dict för JSONField, använd en funktion:

def contact_default():
    return {"email": "to1@example.com"}


contact_info = JSONField("ContactInfo", default=contact_default)

lambda kan inte användas för fältalternativ som default eftersom de inte kan serialiseras av migreringar. Se den dokumentationen för andra varningar.

För fält som ForeignKey som mappar till modellinstanser bör standardvärdena vara värdet för det fält som de refererar till (pk om inte to_field är inställt) i stället för modellinstanser.

Standardvärdet används när nya modellinstanser skapas och inget värde har angetts för fältet. När fältet är en primärnyckel används standardvärdet även när fältet är inställt på None.

Standardvärdet kan också ställas in på databasnivå med Field.db_default.

”redigerbar¶

Field.editable¶

Om False, kommer fältet inte att visas i admin eller någon annan ModelForm. Det kommer också att hoppas över under modellvalidering. Standard är True.

`Felmeddelanden`¶

Field.error_messages[source]¶

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.

Felmeddelanden inkluderar null, blank, invalid, invalid_choice, unique och unique_for_date. Ytterligare nycklar för felmeddelanden anges för varje fält i avsnittet ”Fälttyper” nedan.

Dessa felmeddelanden sprids ofta inte till formulär. Se betraktelser-om-modell-felmeddelanden.

`hjälp_text`¶

Field.help_text¶

Extra ”hjälp”-text som ska visas med formulärwidgeten. Det är användbart för dokumentation även om ditt fält inte används i ett formulär.

Observera att detta värde inte är HTML-escaped i automatiskt genererade formulär. Detta gör att du kan inkludera HTML i help_text om du så önskar. Till exempel:

help_text = "Please use the following format: <em>YYYY-MM-DD</em>."

Alternativt kan du använda vanlig text och django.utils.html.escape() för att undkomma alla HTML-specialtecken. Se till att du undandrar all hjälptext som kan komma från icke betrodda användare för att undvika en cross-site scripting-attack.

`primär_nyckel`¶

Field.primary_key¶

Om True, är detta fält primärnyckel för modellen.

Om du inte anger primary_key=True för något fält i din modell och inte har definierat en sammansatt primärnyckel, kommer Django automatiskt att lägga till ett fält för att hålla primärnyckeln. Så du behöver inte ställa in primary_key=True på något av dina fält om du inte vill åsidosätta standardbeteendet för primärnyckeln. Typen av automatiskt skapade primärnyckelfält kan anges per app i AppConfig.default_auto_field eller globalt i inställningen DEFAULT_AUTO_FIELD. För mer information, se Automatiska primärnyckelfält.

primary_key=True innebär null=False och unique=True. Endast ett fält per modell kan ange primary_key=True. Sammansatta primärnycklar måste definieras med hjälp av CompositePrimaryKey i stället för att sätta denna flagga till True för alla fält för att bibehålla denna invariant.

Fältet primary key är skrivskyddat. Om du ändrar värdet på primärnyckeln i ett befintligt objekt och sedan sparar det, skapas ett nytt objekt vid sidan av det gamla.

Primärnyckelfältet sätts till None när deleting ett objekt.

Changed in Django 5.2:

Fältet CompositePrimaryKey har lagts till.

`unique`¶

Field.unique[source]¶

Om True måste detta fält vara unikt i hela tabellen.

Detta verkställs på databasnivå och genom modellvalidering. Om du försöker spara en modell med ett duplicerat värde i ett unique-fält, kommer ett django.db.IntegrityError att skapas av modellens save()-metod.

Detta alternativ är giltigt för alla fälttyper utom ManyToManyField och OneToOneField.

Observera att när unique är True behöver du inte ange db_index, eftersom unique innebär att ett index skapas.

`unique_for_date`¶

Field.unique_for_date¶

Ange detta till namnet på en DateField eller DateTimeField för att kräva att detta fält är unikt för datumfältets värde.

Om du till exempel har ett fält title som har unique_for_date="pub_date", så skulle Django inte tillåta att två poster med samma title och pub_date registreras.

Observera att om du ställer in detta så att det pekar på en DateTimeField, kommer endast datumdelen av fältet att beaktas. Dessutom, när USE_TZ är True, kommer kontrollen att utföras i :ref:current time zone <default-current-time-zone> vid den tidpunkt då objektet sparas.

Detta verkställs av Model.validate_unique() under modellvalidering men inte på databasnivå. Om någon unique_for_date-restriktion involverar fält som inte är en del av en ModelForm (till exempel om ett av fälten är listat i exclude eller har editable=False), kommer Model.validate_unique() att hoppa över valideringen för den specifika restriktionen.

`unika_för_månad`¶

Field.unique_for_month¶

Som unique_for_date, men kräver att fältet är unikt med avseende på månaden.

`unique_for_year`¶

Field.unique_for_year¶

Som unique_for_date och unique_for_month.

`verbose_namn`¶

Field.verbose_name¶

Ett mänskligt läsbart namn för fältet. Om verbose-namnet inte anges kommer Django automatiskt att skapa det med hjälp av fältets attributnamn och konvertera understreck till mellanslag. Se Verbose field names.

`validerare`¶

Field.validators[source]¶

En lista över validerare som ska köras för detta fält. Se validators dokumentation för mer information.

Fälttyper¶

`AutoField`¶

class AutoField(**options)[source]¶

En IntegerField som automatiskt ökar i enlighet med tillgängliga ID:n. Du behöver vanligtvis inte använda detta direkt; ett primärnyckelfält kommer automatiskt att läggas till i din modell om du inte anger något annat. Se Automatiska primärnyckelfält.

`BigAutoField`¶

class BigAutoField(**options)[source]¶

Ett 64-bitars heltal, ungefär som en AutoField förutom att det garanterat passar siffror från 1 till 9223372036854775807.

`BigIntegerField`¶

class BigIntegerField(**options)[source]¶

Ett 64-bitars heltal, ungefär som ett IntegerField förutom att det garanterat passar siffror från -9223372036854775808 till 9223372036854775807. Standardformulärwidgeten för detta fält är en NumberInput.

`BinaryField`¶

class BinaryField(max_length=None, **options)[source]¶

Ett fält för att lagra binära rådata. Det kan tilldelas bytes, bytearray eller memoryview.

Som standard ställer BinaryField in editable till False, i vilket fall den inte kan inkluderas i en ModelForm.

BinaryField.max_length¶: Valfritt. Den maximala längden (i byte) på fältet. Den maximala längden verkställs i Djangos validering med hjälp av MaxLengthValidator.

Missbruk av BinaryField

Även om du kanske funderar på att lagra filer i databasen, tänk på att det är dålig design i 99% o av fallen. Det här fältet är inte en ersättning för korrekt hantering av statiska filer.

`BooleanField`¶

class BooleanField(**options)[source]¶

Ett sant/falskt fält.

Standardformulärwidgeten för detta fält är CheckboxInput, eller NullBooleanSelect om null=True.

Standardvärdet för BooleanField är None när Field.default inte är definierat.

`SammansattPrimärnyckel`¶

New in Django 5.2.

class CompositePrimaryKey(*field_names, **options)[source]¶

Ett virtuellt fält som används för att definiera en sammansatt primärnyckel.

Detta fält måste definieras som modellens pk-attribut. Om det finns kommer Django att skapa den underliggande modelltabellen med en sammansatt primärnyckel.

Argumentet *field_names är en lista med positionella fältnamn som utgör primärnyckeln.

Se Sammansatta primärnycklar för mer information.

`CharField`¶

class CharField(max_length=None, **options)[source]¶

Ett strängfält, för små till stora strängar.

För stora mängder text, använd TextField.

Standardformulärwidgeten för detta fält är en TextInput.

CharField har följande extra argument:

CharField.max_length¶: Den maximala längden (i tecken) på fältet. max_length verkställs på databasnivå och i Djangos validering med hjälp av MaxLengthValidator. Det krävs för alla databasbackends som ingår i Django utom PostgreSQL och SQLite, som stöder obegränsade VARCHAR-kolumner.

Observera

Om du skriver en applikation som måste kunna portas till flera databasbackends bör du vara medveten om att det finns begränsningar för max_length för vissa backends. Se Databas backend notes för mer information.

Changed in Django 5.2:
Stöd för obegränsade VARCHAR-kolumner har lagts till i SQLite.

CharField.db_collation¶: Valfritt. Databasens kollationsnamn för fältet.

Observera

Kollationeringsnamn är inte standardiserade. Därför kommer detta inte att vara portabelt mellan olika databasbackends.

Oracle

Oracle stöder endast kollationering när databasinitialiseringsparametern MAX_STRING_SIZE är inställd på EXTENDED.

`DateField`¶

class DateField(auto_now=False, auto_now_add=False, **options)[source]¶

Ett datum, representerat i Python av en datetime.date-instans. Har några extra, valfria argument:

DateField.auto_now¶

Ställ automatiskt in fältet på now varje gång objektet sparas. Användbart för tidsstämplar för ”senast ändrad”. Observera att det aktuella datumet alltid används; det är inte bara ett standardvärde som du kan åsidosätta.

Fältet uppdateras endast automatiskt när du anropar Model.save(). Fältet uppdateras inte när du gör uppdateringar av andra fält på andra sätt, t.ex. QuerySet.update(), men du kan ange ett anpassat värde för fältet i en sådan uppdatering.

DateField.auto_now_add¶

Ställ automatiskt in fältet på now när objektet skapas för första gången. Användbart för skapande av tidsstämplar. Observera att det aktuella datumet alltid används; det är inte bara ett standardvärde som du kan åsidosätta. Så även om du anger ett värde för det här fältet när du skapar objektet kommer det att ignoreras. Om du vill kunna ändra det här fältet anger du följande i stället för auto_now_add=True:

För DateField: default=date.today - från datetime.date.today()
För :klass:`DateTimeField`: default=timezone.now - från django.utils.timezone.now()

Standardformulärwidgeten för detta fält är en DateInput. Administratören lägger till en JavaScript-kalender och en genväg för ”Today”. Inkluderar ytterligare en nyckel för felmeddelandet invalid_date.

Alternativen auto_now_add, auto_now och default är ömsesidigt uteslutande. Varje kombination av dessa alternativ kommer att resultera i ett fel.

Observera

Som det nu är implementerat kommer fältet att få inställningarna editable=False och blank=True om auto_now eller auto_now_add sätts till True.

Observera

Alternativen auto_now och auto_now_add kommer alltid att använda datumet i default timezone <default-current-time-zone>` vid skapandet eller uppdateringen. Om du behöver något annat kan du överväga att använda din egen anropsbara standard eller åsidosätta save() istället för att använda auto_now eller auto_now_add; eller använda en DateTimeField istället för en DateField och bestämma hur konverteringen från datetime till datum ska hanteras vid visningstillfället.

Varning

Använd alltid DateField med en datetime.date-instans.

Om du har en datetime.datetime-instans rekommenderas det att du konverterar den till en datetime.date först. Om du inte gör det kommer DateField att lokalisera datetime.datetime till default timezone och konvertera den till en datetime.date-instans och ta bort dess tidskomponent. Detta gäller både för lagring och jämförelse.

`DatumTimeField`¶

class DateTimeField(auto_now=False, auto_now_add=False, **options)[source]¶

Ett datum och en tid, representerade i Python av en datetime.datetime-instans. Tar samma extra argument som DateField.

Standardformulärwidgeten för detta fält är en enda DateTimeInput. Administratören använder två separata TextInput-widgetar med JavaScript-genvägar.

Varning

Använd alltid DateTimeField med en datetime.datetime-instans.

Om du har en datetime.date-instans rekommenderas att du konverterar den till en datetime.datetime först. Om du inte gör det kommer DateTimeField att använda midnatt i default timezone för tidskomponenten. Detta gäller både för lagring och jämförelse. För att jämföra datumdelen av en DateTimeField med en datetime.date-instans, använd date lookup.

`DecimalField`¶

class DecimalField(max_digits=None, decimal_places=None, **options)[source]¶

Ett decimaltal med fast precision, representerat i Python av en Decimal-instans. Den validerar indata med hjälp av DecimalValidator.

Har följande krävda argument:

DecimalField.max_digits¶: Det maximala antalet siffror som tillåts i talet. Observera att detta tal måste vara större än eller lika med decimal_places.

DecimalField.decimal_places¶: Antalet decimaler som ska lagras med talet.

Om du t.ex. vill lagra siffror upp till 999,99 med en upplösning på 2 decimaler använder du:

models.DecimalField(..., max_digits=5, decimal_places=2)

Och för att lagra tal upp till cirka en miljard med en upplösning på 10 decimaler:

models.DecimalField(..., max_digits=19, decimal_places=10)

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

Observera

För mer information om skillnaderna mellan klasserna FloatField och DecimalField, se FloatField vs. DecimalField. Du bör också vara medveten om SQLite-begränsningar av decimalfält.

`DurationField`¶

class DurationField(**options)[source]¶

Ett fält för lagring av tidsperioder - modellerat i Python av timedelta. När den används på PostgreSQL är datatypen som används ett intervall och på Oracle är datatypen INTERVAL DAY (9) TO SECOND (6) ``. Annars används en ``bigint av mikrosekunder.

Observera

Aritmetik med DurationField fungerar i de flesta fall. Men på alla andra databaser än PostgreSQL fungerar det inte som förväntat att jämföra värdet på en DurationField med aritmetik på DateTimeField -instanser.

`EmailField`¶

class EmailField(max_length=254, **options)[source]¶

En CharField som kontrollerar att värdet är en giltig e-postadress med hjälp av EmailValidator.

`FileField`¶

class FileField(upload_to='', storage=None, max_length=100, **options)[source]¶

Ett fält för filuppladdning.

Observera

Argumentet primary_key stöds inte och kommer att ge upphov till ett fel om det används.

Har följande valfria argument:

FileField.upload_to¶

Detta attribut ger ett sätt att ställa in uppladdningskatalogen och filnamnet, och kan ställas in på två sätt. I båda fallen skickas värdet till metoden Storage.save().

Om du anger ett strängvärde eller en Path kan det innehålla strftime()-formatering, som ersätts med datumet/tiden för filuppladdningen (så att uppladdade filer inte fyller upp den angivna katalogen). Till exempel:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to="uploads/")
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to="uploads/%Y/%m/%d/")

Om du använder standard FileSystemStorage, kommer strängvärdet att läggas till din MEDIA_ROOT sökväg för att bilda platsen på det lokala filsystemet där uppladdade filer kommer att lagras. Om du använder en annan lagring, kontrollera dokumentationen för den lagringen för att se hur den hanterar upload_to.

upload_to kan också vara en anropbar funktion, t.ex. en funktion. Denna kommer att anropas för att erhålla uppladdningssökvägen, inklusive filnamnet. Denna anropbara funktion måste acceptera två argument och returnera en sökväg i Unix-stil (med snedstreck) som ska skickas vidare till lagringssystemet. De två argumenten är:

Argument	Beskrivning
`instans`	En instans av modellen där `FileField` är definierad. Mer specifikt är detta den särskilda instans där den aktuella filen bifogas. I de flesta fall har det här objektet inte sparats i databasen ännu, så om det använder standardinställningen `AutoField` kanske det ännu inte har något värde för sitt primärnyckelfält.
`filnamn`	Det filnamn som ursprungligen gavs till filen. Detta kan eller kan inte tas med i beräkningen när den slutliga destinationssökvägen bestäms.

Argument

Beskrivning

instans

En instans av modellen där FileField är definierad. Mer specifikt är detta den särskilda instans där den aktuella filen bifogas.

I de flesta fall har det här objektet inte sparats i databasen ännu, så om det använder standardinställningen AutoField kanske det ännu inte har något värde för sitt primärnyckelfält.

filnamn

Det filnamn som ursprungligen gavs till filen. Detta kan eller kan inte tas med i beräkningen när den slutliga destinationssökvägen bestäms.

Till exempel:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return "user_{0}/{1}".format(instance.user.id, filename)


class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage¶: Ett lagringsobjekt eller en anropsbar funktion som returnerar ett lagringsobjekt. Detta hanterar lagring och hämtning av dina filer. Se Hantera filer för mer information om hur du tillhandahåller detta objekt.

Standardformulärwidgeten för detta fält är en ClearableFileInput.

Att använda en FileField eller en ImageField (se nedan) i en modell kräver några steg:

I din inställningsfil måste du definiera MEDIA_ROOT som den fullständiga sökvägen till en katalog där du vill att Django ska lagra uppladdade filer. (Av prestandaskäl lagras inte dessa filer i databasen.) Definiera MEDIA_URL som den publika URL:en för den katalogen. Se till att den här katalogen är skrivbar av webbserverns användarkonto.
Lägg till FileField eller ImageField i din modell och definiera alternativet upload_to för att ange en underkatalog i MEDIA_ROOT som ska användas för uppladdade filer.
Allt som kommer att lagras i din databas är en sökväg till filen (i förhållande till MEDIA_ROOT). Du kommer troligen att vilja använda det praktiska attributet url som tillhandahålls av Django. Om din ImageField till exempel heter mug_shot kan du få den absoluta sökvägen till din bild i en mall med {{ object.mug_shot.url }}.

Anta till exempel att din MEDIA_ROOT är inställd på '/home/media' och upload_to är inställd på 'photos/%Y/%m/%d'. Delen '%Y/%m/%d' i upload_to är strftime()-formatering; '%Y' är det fyrsiffriga året, '%m' är den tvåsiffriga månaden och '%d' är den tvåsiffriga dagen. Om du laddar upp en fil den 15 januari 2007 kommer den att sparas i katalogen /home/media/photos/2007/01/15.

Om du vill hämta den uppladdade filens filnamn på disken eller filens storlek kan du använda attributen name respektive size; för mer information om tillgängliga attribut och metoder, se klassreferensen File och ämnesguiden Hantera filer.

Observera

Filen sparas som en del av att modellen sparas i databasen, så det faktiska filnamnet som används på disken kan man inte lita på förrän efter att modellen har sparats.

Den uppladdade filens relativa URL kan erhållas med hjälp av attributet url. Internt anropar detta url()-metoden för den underliggande Storage-klassen.

Observera att när du hanterar uppladdade filer bör du vara mycket uppmärksam på var du laddar upp dem och vilken typ av filer de är, för att undvika säkerhetshål. Validera alla uppladdade filer så att du är säker på att filerna är vad du tror att de är. Om du till exempel blint låter någon ladda upp filer, utan validering, till en katalog som ligger i din webbservers dokumentrot, kan någon ladda upp ett CGI- eller PHP-skript och köra det skriptet genom att besöka dess URL på din webbplats. Tillåt inte det.

Observera också att även en uppladdad HTML-fil, eftersom den kan köras av webbläsaren (men inte av servern), kan utgöra säkerhetshot som motsvarar XSS- eller CSRF-attacker.

FileField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med argumentet max_length.

`FileField` och `FieldFile`¶

class FieldFile[source]¶

När du öppnar en FileField på en modell får du en instans av FieldFile som en proxy för åtkomst till den underliggande filen.

API:et för FieldFile speglar det för File, med en viktig skillnad: *Objektet som klassen omsluter är inte nödvändigtvis en omslutning kring Pythons inbyggda filobjekt * Istället är det en omslutning kring resultatet av Storage.open()-metoden, som kan vara ett File-objekt, eller det kan vara en anpassad lagrings implementering av File API.

Utöver API:et som ärvs från File, såsom read() och write(), innehåller FieldFile flera metoder som kan användas för att interagera med den underliggande filen:

Varning

Två metoder i den här klassen, save() och delete(), sparar som standard modellobjektet för den associerade FieldFile i databasen.

FieldFile.name¶

Namnet på filen inklusive den relativa sökvägen från roten till Storage för den associerade FileField.

FieldFile.path[source]¶

En skrivskyddad egenskap för att komma åt filens lokala filsystemssökväg genom att anropa path()-metoden i den underliggande Storage-klassen.

FieldFile.size[source]¶

Resultatet av den underliggande Storage.size()-metoden.

FieldFile.url[source]¶

En skrivskyddad egenskap för att komma åt filens relativa URL genom att anropa url()-metoden i den underliggande Storage-klassen.

FieldFile.open(mode='rb')[source]¶

Öppnar eller återöppnar filen som är associerad med denna instans i angivet mode. Till skillnad från Pythons standardmetod open() returnerar den inte en filbeskrivare.

Eftersom den underliggande filen öppnas implicit vid åtkomst till den, kan det vara onödigt att anropa denna metod förutom för att återställa pekaren till den underliggande filen eller för att ändra mode.

FieldFile.close()[source]¶

Uppträder som Pythons standardmetod file.close() och stänger den fil som är kopplad till denna instans.

FieldFile.save(name, content, save=True)[source]¶

Den här metoden tar ett filnamn och filinnehåll och skickar dem till lagringsklassen för fältet och associerar sedan den lagrade filen med modellfältet. Om du manuellt vill associera fildata med FileField-instanser i din modell, används metoden save() för att bevara fildata.

Tar två obligatoriska argument: name som är namnet på filen och content som är ett objekt som innehåller filens innehåll. Det valfria argumentet save styr om modellinstansen sparas eller inte efter att filen som är associerad med detta fält har ändrats. Standardvärdet är True.

Observera att argumentet content ska vara en instans av django.core.files.File, inte Pythons inbyggda filobjekt. Du kan konstruera en File från ett befintligt Python-filobjekt så här:

from django.core.files import File

# Open an existing file using Python's built-in open()
f = open("/path/to/hello.world")
myfile = File(f)

Eller så kan du konstruera en från en Python-sträng så här:

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

För mer information, se Hantera filer.

FieldFile.delete(save=True)[source]¶

Raderar filen som är kopplad till denna instans och rensar alla attribut på fältet. Observera: Den här metoden stänger filen om den råkar vara öppen när delete() anropas.

Det valfria argumentet save styr om modellinstansen sparas eller inte efter att filen som är associerad med detta fält har tagits bort. Standardvärdet är True.

Observera att när en modell tas bort tas inte relaterade filer bort. Om du behöver rensa bort föräldralösa filer måste du hantera det själv (t.ex. med ett anpassat hanteringskommando som kan köras manuellt eller schemaläggas för att köras regelbundet via t.ex. cron).

`FilePathField`¶

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)[source]¶

En CharField vars valmöjligheter är begränsade till filnamnen i en viss katalog på filsystemet. Har några specialargument, varav det första är obligatoriskt:

FilePathField.path¶

Obligatorisk. Den absoluta filsystemssökvägen till en katalog från vilken denna FilePathField ska hämta sina val. Exempel: "/home/images".

path kan också vara en anropsbar funktion, t.ex. en funktion för att dynamiskt ställa in sökvägen vid körning. Exempel:

import os
from django.conf import settings
from django.db import models


def images_path():
    return os.path.join(settings.LOCAL_FILE_DIR, "images")


class MyModel(models.Model):
    file = models.FilePathField(path=images_path)

FilePathField.match¶: Valfritt. Ett reguljärt uttryck, som en sträng, som FilePathField kommer att använda för att filtrera filnamn. Observera att regex kommer att tillämpas på basfilnamnet, inte på hela sökvägen. Exempel: "foo.*\.txt$", vilket matchar en fil som heter foo23.txt men inte bar.txt eller foo23.png.

FilePathField.recursive¶: Valfritt. Antingen True eller False. Standard är False. Anger om alla underkataloger till path ska inkluderas

FilePathField.allow_files¶: Valfritt. Antingen True eller False. Standard är True. Anger om filer på den angivna platsen ska inkluderas. Antingen detta eller allow_folders måste vara True.

FilePathField.allow_folders¶: Valfritt. Antingen True eller False. Standard är False. Anger om mappar på den angivna platsen ska inkluderas. Antingen detta eller allow_files måste vara True.

Det enda potentiella problemet är att match gäller för det grundläggande filnamnet, inte den fullständiga sökvägen. Så i det här exemplet:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…kommer att matcha /home/images/foo.png men inte /home/images/foo/bar.png eftersom match gäller för basfilnamnet (foo.png och bar.png).

FilePathField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med hjälp av argumentet max_length.

`FloatField`¶

class FloatField(**options)[source]¶

Ett flyttal som i Python representeras av en float-instans.

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

FloatField vs. DecimalField

Klassen FloatField blandas ibland ihop med klassen DecimalField. Även om de båda representerar verkliga tal, representerar de dessa tal på olika sätt. FloatField använder Pythons typ float internt, medan DecimalField använder Pythons typ Decimal. För information om skillnaden mellan de två, se Pythons dokumentation för modulen decimal.

`GeneratedField`¶

class GeneratedField(expression, output_field, db_persist=None, **kwargs)[source]¶

Ett fält som alltid beräknas baserat på andra fält i modellen. Detta fält hanteras och uppdateras av databasen själv. Använder SQL-syntaxen GENERATED ALWAYS.

Det finns två typer av genererade kolumner: lagrade och virtuella. En lagrad genererad kolumn beräknas när den skrivs (infogas eller uppdateras) och tar upp lagringsutrymme som om det vore en vanlig kolumn. En virtuell genererad kolumn upptar ingen lagringsplats och beräknas när den läses. En virtuell genererad kolumn liknar alltså en vy och en lagrad genererad kolumn liknar en materialiserad vy.

GeneratedField.expression¶

Ett Expression som används av databasen för att automatiskt ställa in fältvärdet varje gång modellen ändras.

Uttrycken ska vara deterministiska och endast referera till fält inom modellen (i samma databastabell). Genererade fält kan inte referera till andra genererade fält. Databasbackends kan införa ytterligare begränsningar.

GeneratedField.output_field¶: En modellfältsinstans för att definiera fältets datatyp.

GeneratedField.db_persist¶

Bestämmer om databaskolumnen ska ta upp lagringsutrymme som om den vore en riktig kolumn. Om False, fungerar kolumnen som en virtuell kolumn och tar inte upp lagringsutrymme i databasen.

PostgreSQL stöder endast kvarvarande kolumner. Oracle stöder endast virtuella kolumner.

Uppdatera uppgifterna

Eftersom databasen beräknar värdet måste objektet laddas om för att få tillgång till det nya värdet efter save(), till exempel genom att använda refresh_from_db().

Begränsningar i databasen

Det finns många databasspecifika begränsningar för genererade fält som Django inte validerar och databasen kan ge upphov till ett fel, t.ex. PostgreSQL kräver att funktioner och operatörer som refereras till i en genererad kolumn markeras som IMMUTABLE.

Du bör alltid kontrollera att expression stöds i din databas. Kolla in MariaDB, MySQL, Oracle, PostgreSQL eller SQLite docs.

`GenericIPAddressField`¶

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)[source]¶

En IPv4- eller IPv6-adress i strängformat (t.ex. 192.0.2.30 eller 2a02:42fe::4). Standardformulärwidgeten för detta fält är en TextInput.

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.

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

GenericIPAddressField.unpack_ipv4¶: 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'.

Om du tillåter tomma värden måste du tillåta null-värden eftersom tomma värden lagras som null.

`ImageField`¶

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)[source]¶

Ärver alla attribut och metoder från FileField, men validerar också att det uppladdade objektet är en giltig bild.

Förutom de specialattribut som finns för FileField har en ImageField även attributen height och width.

För att göra det lättare att ställa frågor om dessa attribut har ImageField följande valfria argument:

ImageField.height_field¶: Namn på ett modellfält som automatiskt fylls i med bildens höjd varje gång ett bildobjekt ställs in.

ImageField.width_field¶: Namn på ett modellfält som automatiskt fylls i med bildens bredd varje gång ett bildobjekt ställs in.

Kräver biblioteket pillow.

ImageField-instanser skapas i din databas som varchar-kolumner med en maximal standardlängd på 100 tecken. Precis som för andra fält kan du ändra den maximala längden med argumentet max_length.

Standardformulärwidgeten för detta fält är en ClearableFileInput.

`IntegerField`¶

class IntegerField(**options)[source]¶

Ett heltal. Värden är endast tillåtna mellan vissa (databasberoende) punkter. Värden från -2147483648 till 2147483647 är kompatibla i alla databaser som stöds av Django.

Den använder MinValueValidator och MaxValueValidator för att validera inmatningen baserat på de värden som standarddatabasen stöder.

Standardformulärwidgeten för detta fält är en NumberInput när localize är False eller annars TextInput.

`JSONField`¶

class JSONField(encoder=None, decoder=None, **options)[source]¶

Ett fält för lagring av JSON-kodade data. I Python representeras data i Pythons ursprungliga format: ordböcker, listor, strängar, siffror, booleaner och None.

JSONField stöds på MariaDB, MySQL, Oracle, PostgreSQL och SQLite (med JSON1-tillägget aktiverat).

JSONField.encoder¶

En valfri json.JSONEncoder-underklass för att serialisera datatyper som inte stöds av standard JSON serializer (t.ex. datetime.datetime eller UUID). Du kan till exempel använda klassen DjangoJSONEncoder.

Standardvärdet är json.JSONEncoder.

JSONField.decoder¶

En valfri json.JSONDecoder-underklass för att deserialisera värdet som hämtats från databasen. Värdet kommer att vara i det format som valts av den anpassade kodaren (oftast en sträng). Din deserialisering kan behöva ta hänsyn till det faktum att du inte kan vara säker på indatatypen. Du riskerar till exempel att returnera en datetime som faktiskt var en sträng som bara råkade vara i samma format som valts för datetime.

Standardvärdet är json.JSONDecoder.

För att fråga JSONField i databasen, se Fråga om JSONField.

Standardvärde

Om du ger fältet en default, se till att det är en callable som t.ex. dict-klassen eller en funktion som returnerar ett nytt objekt varje gång. Felaktig användning av ett föränderligt objekt som default={} eller default=[] skapar en föränderlig standard som delas mellan alla instanser.

Indexering

Index och Field.db_index skapar båda ett B-trädindex, vilket inte är särskilt användbart när man frågar JSONField. Endast på PostgreSQL kan du använda GinIndex som är bättre lämpad.

PostgreSQL-användare

PostgreSQL har två inbyggda JSON-baserade datatyper: `` json`` och `` jsonb``. Huvudskillnaden mellan dem är hur de lagras och hur de kan frågas. PostgreSQL: s `` json``-fält lagras som den ursprungliga strängrepresentationen av JSON och måste avkodas i farten när det frågas baserat på nycklar. Fältet jsonb lagras baserat på den faktiska strukturen i JSON som tillåter indexering. Avvägningen är en liten extra kostnad för att skriva till fältet jsonb. JSONField använder jsonb.

Oracle-användare

Oracle Database stöder inte lagring av JSON-skalärvärden. Endast JSON-objekt och matriser (representerade i Python med hjälp av dict och list) stöds.

`PositivBigIntegerField`¶

class PositiveBigIntegerField(**options)[source]¶

Som en PositiveIntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från 0 till 9223372036854775807 är kompatibla i alla databaser som stöds av Django.

`PositivIntegerField`¶

class PositiveIntegerField(**options)[source]¶

Som en IntegerField, men måste vara antingen positiv eller noll (0). Värden är endast tillåtna under en viss (databasberoende) punkt. Värden från 0 till 2147483647 är kompatibla i alla databaser som stöds av Django. Värdet 0 accepteras av bakåtkompatibilitetsskäl.

`Positiv liten heltalsfält`¶

class PositiveSmallIntegerField(**options)[source]¶

Som en PositiveIntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från 0 till 32767 är kompatibla i alla databaser som stöds av Django.

`SlugField`¶

class SlugField(max_length=50, **options)[source]¶

Slug är en term för tidningar. En slug är en kort etikett för något, som bara innehåller bokstäver, siffror, understrykningar eller bindestreck. De används i allmänhet i webbadresser.

Precis som en CharField kan du ange max_length (läs även anmärkningen om databasportabilitet och max_length i det avsnittet). Om max_length inte anges kommer Django att använda en standardlängd på 50.

Innebär att Field.db_index sätts till True.

Det är ofta användbart att automatiskt fylla i en SlugField baserat på värdet av något annat värde. Du kan göra detta automatiskt i admin med prepopulated_fields.

Den använder validate_slug eller validate_unicode_slug för validering.

SlugField.allow_unicode¶: Om True, accepterar fältet Unicode-bokstäver utöver ASCII-bokstäver. Standardvärdet är False.

`SmallAutoField`¶

class SmallAutoField(**options)[source]¶

Som en AutoField, men tillåter bara värden under en viss (databasberoende) gräns. Värden från 1 till 32767 är kompatibla i alla databaser som stöds av Django.

`LitenIntegerField`¶

class SmallIntegerField(**options)[source]¶

Som en IntegerField, men tillåter bara värden under en viss (databasberoende) punkt. Värden från -32768 till 32767 är kompatibla i alla databaser som stöds av Django.

`Textfält`¶

class TextField(**options)[source]¶

Ett stort textfält. Standardformulärwidgeten för detta fält är en Textarea.

Om du anger ett max_length-attribut kommer det att återspeglas i Textarea-widgeten i det autogenererade formulärfältet. Det verkställs dock inte på modell- eller databasnivå. Använd en CharField för det.

TextField.db_collation¶: Valfritt. Databasens kollationsnamn för fältet.

Observera

Kollationeringsnamn är inte standardiserade. Därför kommer detta inte att vara portabelt mellan olika databasbackends.

Oracle

Oracle stöder inte kollationer för en TextField.

`TimeField`¶

class TimeField(auto_now=False, auto_now_add=False, **options)[source]¶

En tid, representerad i Python av en datetime.time-instans. Accepterar samma autopopuleringsalternativ som DateField.

Standardformulärwidgeten för detta fält är en TimeInput. Administratören lägger till några JavaScript-genvägar.

`URL-fält`¶

class URLField(max_length=200, **options)[source]¶

En CharField för en URL, validerad av URLValidator.

Standardformulärwidgeten för det här fältet är en URLInput.

Som alla CharField-subklasser tar URLField det valfria argumentet max_length. Om du inte anger max_length används standardvärdet 200.

`UUIDField`¶

class UUIDField(**options)[source]¶

Ett fält för lagring av universellt unika identifierare. Använder Pythons UUID klass. När det används på PostgreSQL och MariaDB 10.7+ lagras detta i en uuid datatyp, annars i en ``char (32) ``.

Universellt unika identifierare är ett bra alternativ till AutoField för primary_key. Databasen kommer inte att generera UUID åt dig, så det rekommenderas att du använder default:

import uuid
from django.db import models


class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

Observera att en callable (med parenteserna utelämnade) skickas till default, inte en instans av UUID.

Uppslagningar på PostgreSQL och MariaDB 10.7+

Att använda iexact, contains, icontains, startswith, istartswith, endswith eller iendswith lookups på PostgreSQL fungerar inte för värden utan bindestreck, eftersom PostgreSQL och MariaDB 10.7+ lagrar dem i en bindestreckad uuid-datatypstyp.

API-referens för fält¶

class Field[source]¶

Field är en abstrakt klass som representerar en kolumn i en databastabell. Django använder fält för att skapa databastabellen (db_type()), för att mappa Python-typer till databasen (get_prep_value()) och vice versa (from_db_value()).

Ett fält är således en grundläggande del i olika Django API:er, i synnerhet models och querysets.

I modeller är ett fält instansierat som ett klassattribut och representerar en viss tabellkolumn, se Modeller. Det har attribut som null och unique, och metoder som Django använder för att mappa fältvärdet till databasspecifika värden.

En Field är en underklass av RegisterLookupMixin och därmed kan både Transform och Lookup` registreras på den för att användas i QuerySet (t.ex. field_name__exact="foo"). Alla :ref:inbyggda lookups <field-lookups> är registrerade som standard.

Alla Djangos inbyggda fält, till exempel CharField, är särskilda implementeringar av Field. Om du behöver ett anpassat fält kan du antingen subklassa något av de inbyggda fälten eller skriva ett Field från början. I båda fallen, se Så här skapar du anpassade modellfält.

description¶

En utförlig beskrivning av fältet, t.ex. för programmet django.contrib.admindocs.

Beskrivningen kan vara av formen:

description = _("String (up to %(max_length)s)")

där argumenten interpoleras från fältets __dict__.

descriptor_class¶: En klass som implementerar descriptor protocol som instansieras och tilldelas attributet för modellinstansen. Konstruktören måste acceptera ett enda argument, Field-instansen. Åsidosättande av detta klassattribut gör det möjligt att anpassa get- och set-beteendet.

För att mappa en Field till en databasspecifik typ, exponerar Django flera metoder:

get_internal_type()[source]¶

Returnerar en sträng som namnger detta fält för backend-specifika ändamål. Som standard returneras klassnamnet.

Se Emulering av inbyggda fälttyper för användning i anpassade fält.

db_type(connection)[source]¶

Returnerar databaskolumnens datatyp för Field, med hänsyn tagen till connection.

Se Anpassade databastyper för användning i anpassade fält.

rel_db_type(connection)[source]¶

Returnerar databasens kolumndatatyp för fält som ForeignKey och OneToOneField som pekar på Field, med hänsyn tagen till connection.

Se Anpassade databastyper för användning i anpassade fält.

Det finns tre huvudsakliga situationer där Django behöver interagera med databasens backend och fält:

när den frågar databasen (Python-värde -> databasens backend-värde)
när den laddar data från databasen (databasens backend-värde -> Python-värde)
när den sparar i databasen (Python-värde -> databasens backend-värde)

Vid frågor används get_db_prep_value() och get_prep_value():

get_prep_value(value)[source]¶

value är det aktuella värdet för modellens attribut och metoden ska returnera data i ett format som har förberetts för att användas som en parameter i en fråga.

Se Konvertera Python-objekt till frågevärden för användning.

get_db_prep_value(value, connection, prepared=False)[source]¶

Konverterar value till ett backend-specifikt värde. Som standard returnerar den value om prepared=True och get_prep_value() om är False.

Se Konvertering av frågevärden till databasvärden för användning.

Vid laddning av data används from_db_value():

from_db_value(value, expression, connection)¶

Konverterar ett värde som returneras av databasen till ett Python-objekt. Det är det omvända av get_prep_value().

Den här metoden används inte för de flesta inbyggda fält eftersom databasens backend redan returnerar rätt Python-typ, eller så gör backend själv konverteringen.

uttryck är detsamma som själv.

Se Konvertera värden till Python-objekt för användning.

Observera

Av prestandaskäl implementeras inte from_db_value som en no-op på fält som inte kräver det (alla Django-fält). Följaktligen får du inte anropa super i din definition.

När du sparar används pre_save() och get_db_prep_save():

get_db_prep_save(value, connection)[source]¶: Samma som get_db_prep_value(), men anropas när fältvärdet måste sparas till databasen. Som standard returneras get_db_prep_value().

pre_save(model_instance, add)[source]¶

Metod som anropas före get_db_prep_save() för att förbereda värdet innan det sparas (t.ex. för DateField.auto_now).

model_instance är den instans som detta fält tillhör och add är om instansen sparas i databasen för första gången.

Det bör returnera värdet på lämpligt attribut från model_instance för detta fält. Attributnamnet finns i self.attname (detta ställs in av Field).

Se Förbehandling av värden före lagring för användning.

Fält får ofta sina värden som en annan typ, antingen från serialisering eller från formulär.

to_python(value)[source]¶

Konverterar värdet till det korrekta Python-objektet. Det fungerar som det omvända av value_to_string(), och anropas också i clean().

Se Konvertera värden till Python-objekt för användning.

Förutom att spara i databasen måste fältet också veta hur det ska serialisera sitt värde:

value_from_object(obj)[source]¶

Returnerar fältets värde för den angivna modellinstansen.

Denna metod används ofta av value_to_string().

value_to_string(obj)[source]¶

Konverterar obj till en sträng. Används för att serialisera fältets värde.

Se Konvertering av fältdata för serialisering för användning.

När man använder model forms, måste Field veta vilket formulärfält den ska representeras av:

formfield(form_class=None, choices_form_class=None, **kwargs)[source]¶

Returnerar standard django.forms.Field för detta fält för ModelForm.

Om formfield() åsidosätts för att returnera None, utesluts detta fält från ModelForm.

Som standard, om både form_class och choices_form_class är None, används CharField. Om fältet har choices och choices_form_class inte är specificerat, används TypedChoiceField.

Se specificerande-form-fält-för-modell-fält för användning.

deconstruct()[source]¶

Returnerar en 4-tupel med tillräckligt med information för att återskapa fältet:

Namnet på fältet i modellen.
Importsökvägen för fältet (t.ex. "django.db.models.IntegerField"). Detta bör vara den mest portabla versionen, så mindre specifik kan vara bättre.
En lista med positionella argument.
En dikt av nyckelordsargument.

Denna metod måste läggas till fält före 1.7 för att migrera dess data med hjälp av Migreringar.

Registrering och hämtning av uppslagsord¶

Field implementerar :ref:lookup registration API <lookup-registration-api>. API:et kan användas för att anpassa vilka uppslagsord som är tillgängliga för en fältklass och dess instanser, och hur uppslagsord hämtas från ett fält.

Referens till fältattribut¶

Varje Field-instans innehåller flera attribut som gör det möjligt att introspektera dess beteende. Använd dessa attribut istället för isinstance-kontroller när du behöver skriva kod som är beroende av ett fälts funktionalitet. Dessa attribut kan användas tillsammans med Model._meta API för att begränsa en sökning efter specifika fälttyper. Anpassade modellfält bör implementera dessa flaggor.

Attribut för fält¶

Field.auto_created¶: Boolesk flagga som anger om fältet skapades automatiskt, t.ex. OneToOneField som används vid modellarv.

Field.concrete¶: Boolesk flagga som anger om fältet har en databaskolumn associerad med sig.

Field.hidden¶: Boolesk flagga som anger om ett fält är dolt och inte ska returneras av Options.get_fields() som standard. Ett exempel är det omvända fältet för en ForeignKey med ett related_name som börjar med '+'.

Field.is_relation¶: Boolesk flagga som anger om ett fält innehåller referenser till en eller flera andra modeller för dess funktionalitet (t.ex. ForeignKey, ManyToManyField, OneToOneField, etc.).

Field.model¶: Returnerar den modell som fältet är definierat för. Om ett fält definieras på en superklass av en modell, kommer model att hänvisa till superklassen, inte klassen för instansen.

Attribut för fält med relationer¶

Dessa attribut används för att fråga efter kardinalitet och andra detaljer i en relation. Dessa attribut finns på alla fält, men de har endast booleska värden (i stället för None) om fältet är en relationstyp (Field.is_relation=True).

Field.many_to_many¶: Boolesk flagga som är True om fältet har en many-to-many-relation; False annars. Det enda fältet som ingår i Django där detta är True är ManyToManyField.

Field.many_to_one¶: Boolesk flagga som är True om fältet har en många-till-en-relation, t.ex. en ForeignKey; annars False.

Field.one_to_many¶: Boolesk flagga som är True om fältet har en en-till-många-relation, t.ex. en GenericRelation eller motsatsen till en ForeignKey; annars False.

Field.one_to_one¶: Boolesk flagga som är True om fältet har en en-till-en-relation, t.ex. ett OneToOneField; annars False.

Field.related_model¶: Pekar på den modell som fältet hänför sig till. Till exempel: Author i ForeignKey(Author, on_delete=models.CASCADE). Den related_model för en GenericForeignKey är alltid None.

Referens till modellfält¶

Alternativ för fält¶

null¶

blank¶

val¶

Uppräkningstyper¶

db_kolumn¶

db_kommentar¶

db_default¶

db_index¶

db_tablespace¶

standard¶

”redigerbar¶

Felmeddelanden¶

hjälp_text¶

primär_nyckel¶

unique¶

unique_for_date¶

unika_för_månad¶

unique_for_year¶

verbose_namn¶

validerare¶

Fälttyper¶

AutoField¶

BigAutoField¶

BigIntegerField¶

BinaryField¶

BooleanField¶

SammansattPrimärnyckel¶

CharField¶

DateField¶

DatumTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FileField och FieldFile¶

FilePathField¶

FloatField¶

GeneratedField¶

GenericIPAddressField¶

ImageField¶

IntegerField¶

JSONField¶

PositivBigIntegerField¶

PositivIntegerField¶

Positiv liten heltalsfält¶

SlugField¶

SmallAutoField¶

LitenIntegerField¶

Textfält¶

TimeField¶

URL-fält¶

UUIDField¶

Relationsfält¶

ForeignKey¶

Databasrepresentation¶

Argument¶

ManyToManyField¶

Databasrepresentation¶

Argument¶

OneToOneField¶

Lata relationer¶

Rekursiv¶

Relativ¶

Absolut¶

API-referens för fält¶

Registrering och hämtning av uppslagsord¶

Referens till fältattribut¶

Attribut för fält¶

Attribut för fält med relationer¶

Additional Information

Support Django!

Contents

Getting help

Download:

`null`¶

`blank`¶

`val`¶

`db_kolumn`¶

`db_kommentar`¶

`db_default`¶

`db_index`¶

`db_tablespace`¶

`standard`¶

`Felmeddelanden`¶

`hjälp_text`¶

`primär_nyckel`¶

`unique`¶

`unique_for_date`¶

`unika_för_månad`¶

`unique_for_year`¶

`verbose_namn`¶

`validerare`¶

`AutoField`¶

`BigAutoField`¶

`BigIntegerField`¶

`BinaryField`¶

`BooleanField`¶

`SammansattPrimärnyckel`¶

`CharField`¶

`DateField`¶

`DatumTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FileField` och `FieldFile`¶

`FilePathField`¶

`FloatField`¶

`GeneratedField`¶

`GenericIPAddressField`¶

`ImageField`¶

`IntegerField`¶

`JSONField`¶

`PositivBigIntegerField`¶

`PositivIntegerField`¶

`Positiv liten heltalsfält`¶

`SlugField`¶

`SmallAutoField`¶

`LitenIntegerField`¶

`Textfält`¶

`TimeField`¶

`URL-fält`¶

`UUIDField`¶

`ForeignKey`¶

`ManyToManyField`¶

`OneToOneField`¶