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.
val¶
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.labelkan 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 ett exempel pÄ underklassning av val med en mer komplex datatyp. Om en tupel inte tillhandahÄlls, eller om det sista objektet inte Àr en (lat) strÀng, Àrlabelautomatiskt genererad 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,.valuesoch.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 namngivna grupper.
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.
db_tablespace¶
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¶
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.
FĂ€ltet CompositePrimaryKey har lagts till.
unique¶
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 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¶
En lista över validerare som ska köras för detta fÀlt. Se validators dokumentation för mer information.
FÀlttyper¶
AutoField¶
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¶
Ett 64-bitars heltal, ungefÀr som en AutoField förutom att det garanterat passar siffror frÄn 1 till 9223372036854775807.
BigIntegerField¶
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¶
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¶
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¶
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¶
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_lengthverkstÀlls pÄ databasnivÄ och i Djangos validering med hjÀlp avMaxLengthValidator. Det krÀvs för alla databasbackends som ingÄr i Django utom PostgreSQL och SQLite, som stöder obegrÀnsadeVARCHAR-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_lengthfö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¶
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Ändatetime.date.today()För
DateTimeField:default=timezone.now- frÄndjango.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.
Varning
On PostgreSQL and MySQL, arithmetic operations on a DateField with a
timedelta return a datetime instead of a date.
This occurs because Pythonâs timedelta is converted to SQL
INTERVAL, and the SQL operation date +/- interval returns a
timestamp on these databases.
To ensure a date result, use one of the following approaches. Either
explicitly cast the result to a date:
import datetime
from django.db.models import DateField, F
from django.db.models.functions import Cast
qs = MyModel.objects.annotate(
previous_day=Cast(
F("date_field") - datetime.timedelta(days=1),
output_field=DateField(),
)
)
Or on PostgreSQL only, use integer arithmetic to represent days:
from django.db.models import DateField, ExpressionWrapper, F
qs = MyModel.objects.annotate(
previous_day=ExpressionWrapper(
F("date_field") - 1, # Subtract 1 day as integer
output_field=DateField(),
)
)
DatumTimeField¶
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¶
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¶
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¶
En CharField som kontrollerar att vÀrdet Àr en giltig e-postadress med hjÀlp av EmailValidator.
FileField¶
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
Pathkan det innehÄllastrftime()-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 dinMEDIA_ROOTsö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 hanterarupload_to.upload_tokan 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
instansEn 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
AutoFieldkanske det Ànnu inte har nÄgot vÀrde för sitt primÀrnyckelfÀlt.filnamnDet 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_ROOTsom 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.) DefinieraMEDIA_URLsom den publika URL:en för den katalogen. Se till att den hÀr katalogen Àr skrivbar av webbserverns anvÀndarkonto.LÀgg till
FileFieldellerImageFieldi din modell och definiera alternativetupload_toför att ange en underkatalog iMEDIA_ROOTsom 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 attributeturlsom tillhandahÄlls av Django. Om dinImageFieldtill exempel hetermug_shotkan 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¶
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.
En skrivskyddad egenskap för att komma Ät filens lokala filsystemssökvÀg genom att anropa path()-metoden i den underliggande Storage-klassen.
Resultatet av den underliggande Storage.size()-metoden.
En skrivskyddad egenskap för att komma Ät filens relativa URL genom att anropa url()-metoden i den underliggande Storage-klassen.
Ă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.
UpptrÀder som Pythons standardmetod file.close() och stÀnger den fil som Àr kopplad till denna instans.
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.
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
FilePathFieldska hÀmta sina val. Exempel:"/home/images".pathkan 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
FilePathFieldkommer 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 heterfoo23.txtmen intebar.txtellerfoo23.png.
- FilePathField.recursive¶
Valfritt. Antingen
TrueellerFalse. Standard ÀrFalse. Anger om alla underkataloger tillpathska inkluderas
- FilePathField.allow_files¶
Valfritt. Antingen
TrueellerFalse. Standard ÀrTrue. Anger om filer pÄ den angivna platsen ska inkluderas. Antingen detta ellerallow_foldersmÄste varaTrue.
- FilePathField.allow_folders¶
Valfritt. Antingen
TrueellerFalse. Standard ÀrFalse. Anger om mappar pÄ den angivna platsen ska inkluderas. Antingen detta ellerallow_filesmÄste varaTrue.
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¶
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¶
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
Expressionsom 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¶
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 till192.0.2.1. Standard Àr inaktiverat. Kan endast anvÀndas nÀrprotocolÀ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¶
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¶
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.datetimeellerUUID). Du kan till exempel anvÀnda klassenDjangoJSONEncoder.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 endatetimesom faktiskt var en strÀng som bara rÄkade vara i samma format som valts fördatetime.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.
PositivBigIntegerField¶
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¶
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¶
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¶
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 ÀrFalse.
SmallAutoField¶
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¶
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¶
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¶
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¶
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¶
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
modelsochquerysets.I modeller Àr ett fÀlt instansierat som ett klassattribut och representerar en viss tabellkolumn, se Modeller. Det har attribut som
nullochunique, och metoder som Django anvÀnder för att mappa fÀltvÀrdet till databasspecifika vÀrden.En
FieldÀr en underklass avRegisterLookupMixinoch dÀrmed kan bÄdeTransformochLookup`registreras pÄ den för att anvÀndas iQuerySet(t.ex.field_name__exact="foo"). Alla inbyggda lookups Àr registrerade som standard.Alla Djangos inbyggda fÀlt, till exempel
CharField, Àr sÀrskilda implementeringar avField. Om du behöver ett anpassat fÀlt kan du antingen subklassa nÄgot av de inbyggda fÀlten eller skriva ettFieldfrÄ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
Fieldtill 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 tillconnection.Se Anpassade databastyper för anvÀndning i anpassade fÀlt.
- rel_db_type(connection)[source]¶
Returnerar databasens kolumndatatyp för fÀlt som
ForeignKeyochOneToOneFieldsom pekar pÄField, med hÀnsyn tagen tillconnection.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()ochget_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
valuetill ett backend-specifikt vÀrde. Som standard returnerar denvalueomprepared=Trueochget_prep_value()om ÀrFalse.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 somsjÀlv.Se Konvertera vÀrden till Python-objekt för anvÀndning.
Observera
Av prestandaskÀl implementeras inte
from_db_valuesom en no-op pÄ fÀlt som inte krÀver det (alla Django-fÀlt). Följaktligen fÄr du inte anropasuperi din definition.
NÀr du sparar anvÀnds
pre_save()ochget_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 returnerasget_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örDateField.auto_now).model_instanceÀr den instans som detta fÀlt tillhör ochaddÀ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_instanceför detta fÀlt. Attributnamnet finns iself.attname(detta stÀlls in avField).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Ä iclean().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
objtill 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ÄsteFieldveta vilket formulÀrfÀlt den ska representeras av:- formfield(form_class=None, choices_form_class=None, **kwargs)[source]¶
Returnerar standard
django.forms.Fieldför detta fÀlt förModelForm.Om
formfield()ÄsidosÀtts för att returneraNone, utesluts detta fÀlt frÄnModelForm.Som standard, om bÄde
form_classochchoices_form_classÀrNone, anvÀndsCharField. Om fÀltet harchoicesochchoices_form_classinte Àr specificerat, anvÀndsTypedChoiceField.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 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.
OneToOneFieldsom anvÀnds vid modellarv.
- Field.concrete¶
Boolesk flagga som anger om fÀltet har en databaskolumn associerad med sig.
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 enForeignKeymed ettrelated_namesom 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
modelatt 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
Trueom fÀltet har en many-to-many-relation;Falseannars. Det enda fÀltet som ingÄr i Django dÀr detta ÀrTrueÀrManyToManyField.
- Field.many_to_one¶
Boolesk flagga som Àr
Trueom fÀltet har en mÄnga-till-en-relation, t.ex. enForeignKey; annarsFalse.
- Field.one_to_many¶
Boolesk flagga som Àr
Trueom fÀltet har en en-till-mÄnga-relation, t.ex. enGenericRelationeller motsatsen till enForeignKey; annarsFalse.
- Field.one_to_one¶
Boolesk flagga som Àr
Trueom fÀltet har en en-till-en-relation, t.ex. ettOneToOneField; annarsFalse.
Pekar pÄ den modell som fÀltet hÀnför sig till. Till exempel:
AuthoriForeignKey(Author, on_delete=models.CASCADE). Denrelated_modelför enGenericForeignKeyÀr alltidNone.