Django 2.1.3 模型層 欄位型別
目錄
- 1.欄位選項
- null
- blank
- choices
- db_column
- db_index
- db_tablespace
- default
- editable
- error_messages
- help_text
- primary_key
- unique
- unique_for_date
- unique_for_month
- unique_for_year
- verbose_name
- validators
- 2.欄位型別
- AutoField
- BigAutoField
- BigIntegerField
- BinaryField
- BooleanField
- CharField
- DateField
- DateTimeField
- DecimalField
- DurationField
- EmailField
- FileField
- FilePathField
- FloatField
- ImageField
- IntegerField
- GenericIPAddressField
- NullBooleanField
- PositiveIntegerField
- PositiveSmallIntegerField
- SlugField
- SmallIntegerField
- TextField
- TimeField
- URLField
- UUIDField
- 3.關係欄位
- 3.1 ForeignKey
- 3.2 ManyToManyField
- 3.2.1 引數
- ManyToManyField.related_name
- ManyToManyField.related_query_name
- ManyToManyField.limit_choices_to
- ManyToManyField.symmetrical
- ManyToManyField.through
- ManyToManyField.through_fields
- ManyToManyField.db_table
- ManyToManyField.db_constraint
- ManyToManyField.swappable
- 3.3 OneToOneField
未完待續…
本文件包含所有Field的API參考,包括Django提供的 欄位選項 和 欄位型別。
也可以看看
如果內建欄位不起作用,您可以嘗試使用django-localflavor(文件),其中包含對特定國家和文化有用的各種程式碼片段。
此外,您可以輕鬆編寫自己的 自定義模型欄位。↑
注意
從技術上講,這些模型是在django.db.models.fields
中定義的,但為方便起見,它們被匯入到django.db.models
; 標準慣例是使用 from django.db import models和引用欄位 models.XXXField。
1.欄位選項
以下引數可用於所有欄位型別。一切都是可選的。
null
Field.null
如果為True,Django將NULL在資料庫中儲存空值。預設是False。
避免在基於字串的欄位上使用null,例如 CharField和TextField。如果基於字串的欄位具有 null=True
,則表示它具有“無資料”屬性的兩個可能值:NULL和空字串。在大多數情況下,為“無資料”提供兩個可能的值是多餘的; Django約定是使用空字串,而不是 NULL。一個例外是當CharField設定了unique=True
和blank=True
。在這種情況下,在使用空值儲存多個物件時,需要null=True
來避免唯一約束違規。
對於基於字串和非基於字串的欄位,您還可能需要設定blank=True
來表示是否允許在表單中允許空值,因為 null引數僅影響資料庫儲存(請參閱參考資料blank)。
注意
使用Oracle資料庫後端時,無論此屬性如何,都將儲存NULL值以表示空字串。
blank
Field.blank
如果為True,該欄位允許為空。預設是False。
請注意,這不同於null。null純粹與資料庫相關,而blank與驗證相關。如果欄位有blank=True,則表單驗證將允許輸入空值。如果欄位有blank=False,則需要該欄位。
choices
Field.choices
可迭代的(例如,列表或元組),其由恰好兩個專案(例如[(A, B), (A, B) ...]
)的可迭代物件組成,以用作該欄位的選擇。如果給出了choice,則通過模型驗證強制執行,預設表單部件將是具有這些選項而不是標準文字欄位的選擇框。
每個元組中的第一個元素是要在模型上設定的實際值,第二個元素是人類可讀的名稱。例如:
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
)
通常,最好在模型類中定義choices,併為每個值定義適當命名的常量:
from django.db import models
class Student(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
JUNIOR = 'JR'
SENIOR = 'SR'
YEAR_IN_SCHOOL_CHOICES = (
(FRESHMAN, 'Freshman'),
(SOPHOMORE, 'Sophomore'),
(JUNIOR, 'Junior'),
(SENIOR, 'Senior'),
)
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)
雖然您可以在模型類之外定義選擇列表然後引用它,但是為模型類中的每個選項定義選項和名稱會將所有資訊儲存在使用它的類中,並使選擇易於引用(例如,Student.SOPHOMORE 將在Student模型已匯入的任何地方工作)。
您還可以將可用選項收集到可用於組織目的的命名組中:
MEDIA_CHOICES = (
('Audio', (
('vinyl', 'Vinyl'),
('cd', 'CD'),
)
),
('Video', (
('vhs', 'VHS Tape'),
('dvd', 'DVD'),
)
),
('unknown', 'Unknown'),
)
每個元組中的第一個元素是要應用於組的名稱。第二個元素是一個可迭代的2元組,每個2元組包含一個值和一個人類可讀的選項名稱。分組選項可以與單個列表中的未分組選項組合(例如本示例中的unknown)。
譯者注:此種用法的效果如下,粗體是不可選的。
對於已設定choices的每個模型欄位,Django將新增一個方法來檢索欄位當前值的可讀名稱。請參閱 get_FOO_display() 資料庫API文件。
>>> from filter.models import NoBody
>>> p = NoBody.objects.get(id=1)
>>> p.get_media_display()
'Vinyl'
>>>
請注意,choice可以是任何可迭代物件 - 不一定是列表或元組。這使您可以動態構造選擇。但是,如果你發現自己 choices變得動態,你可能最好使用一個合適的資料庫表ForeignKey。如果有可能的話,choices用於靜態資料,變化不大的資料。
除非在欄位上設定blank=False
, 否則將使用選擇框呈現default為"---------"
(如上面的圖)。要覆蓋此行為,請將一個包含None的元組新增到choices中 ; 例如(None, 'Your String For Display')
。或者在CharField,您可以使用空字串替代None,這樣看起來更有意義 。
效果圖:
db_column
Field.db_column
用於此欄位的資料庫列的名稱。如果沒有給出,Django將使用該欄位的名稱。
如果您的資料庫列名是SQL保留字,或者包含Python變數名中不允許的字元 - 特別是連字元 - 沒關係。Django在幕後引用了列名和表名。
db_index
Field.db_index
如果為True,將為此欄位建立資料庫索引。
db_tablespace
Field.db_tablespace
如果此欄位已建立索引,則用於此欄位表示索引的資料庫表空間名稱。預設值為專案的 DEFAULT_INDEX_TABLESPACE設定。如果後端不支援索引的表空間,則忽略此選項。
default
Field.default
欄位的預設值。這可以是值或可呼叫物件。如果可呼叫,則每次建立新物件時都會呼叫它。
預設不能是可變物件(模型例項,list,set等),作為該物件的相同例項的引用將被用作在所有新的模型例項的預設值。應該將所需的預設值包裝在可呼叫的函式中。例如,如果要為JSONField指定一個預設的dict ,使用函式:
def contact_default():
return {"email": "[email protected]"}
contact_info = JSONField("ContactInfo", default=contact_default)
匿名函式lambdas不能用於欄位選項的default,因為它們無法通過 遷移進行序列化。請參閱其他警告的文件。
對於ForeignKey對映到模型例項的欄位,default值應該是它們引用的欄位的值(除非已設定 to_field,否則就是pk)而不是模型例項。
建立新模型例項並且未為該欄位提供值時,將使用預設值。當欄位是主鍵時,預設值也會在欄位設定為None時使用。
editable
Field.editable
預設是True。如果為False,該欄位將不會顯示在admin或任何其他ModelForm中 。在模型驗證期間也會跳過它們。
error_messages
Field.error_messages
該error_messages引數允許您覆蓋該欄位將引發的預設訊息。傳入一個字典,其中的鍵與您要覆蓋的錯誤訊息相匹配。
錯誤訊息鍵包括null,blank,invalid,invalid_choice, unique,和unique_for_date。在下面的“ 欄位型別”部分中為每個欄位指定了其他錯誤訊息鍵。
這些錯誤訊息通常不會傳播到表單。請參閱 有關模型的error_messages的注意事項。
help_text
Field.help_text
使用表單部件顯示額外的“幫助”文字。即使您的欄位未在表單上使用,它也對文件很有用。
請注意,此值不會在自動生成的表單中進行HTML轉義。如果您願意,這可以讓您的help_text包含HTML 。例如:
help_text="Please use the following format: <em>YYYY-MM-DD</em>."
或者,您可以使用純文字和django.utils.html.escape()
轉義任何HTML特殊字元。確保您轉義可能來自不受信任的使用者的任何幫助文字,以避免跨站點指令碼攻擊。
primary_key
Field.primary_key
如果為True,此欄位是模型的主鍵。
如果沒有為模型中的任何欄位指定primary_key=True
,Django將自動新增一個AutoField來儲存主鍵,因此除非要覆蓋預設的主鍵行為,否則不需要設定任何欄位為primary_key=True
。有關更多資訊,請參閱 自動主鍵欄位。
primary_key=True
實現了null=False和 unique=True。物件上只允許一個主鍵。
主鍵欄位是隻讀的。如果更改現有物件上主鍵的值然後儲存它,則將建立一個與舊物件並排的新物件。
unique
Field.unique
如果為True,該欄位在整個表中必須是唯一的。
這在資料庫級別和模型驗證中強制執行。如果您嘗試在unique 欄位中使用save()方法儲存具有重複值的模型,將引發django.db.IntegrityError
。
此選項適用於除ManyToManyField和 OneToOneField 之外的所有欄位型別。
請注意,當unique=True,你並不需要指定 db_index,因為unique意味著索引的建立。
unique_for_date
Field.unique_for_date
將其設定在名為DateField或DateTimeField欄位上,它要求此欄位對於日期值或日期和時間值是唯一的。
舉例來說,如果你有一個欄位title有 unique_for_date="pub_date"
,那麼Django不允許兩個記錄具有相同的title和pub_date。
請注意,如果將其設定為指向 DateTimeField,則僅考慮該欄位的日期部分。此外,當USE_TZ= True
時,將在當前時區檢查的物件被儲存的時間。
這在模型驗證期間通過Model.validate_unique() 強制執行,但不在資料庫級別強制執行。如果任何unique_for_date約束涉及不屬於ModelForm的欄位(例如,如果其中一個欄位在exclude中或具有 editable=False
屬性),Model.validate_unique()則將跳過對該特定約束的驗證。
unique_for_month
Field.unique_for_month
像unique_for_date,但要求該欄位在月份方面是獨一無二的。
unique_for_year
Field.unique_for_year
像unique_for_date和unique_for_month。
verbose_name
Field.verbose_name
該欄位的人類可讀名稱。如果沒有給出詳細名稱,Django將使用欄位的屬性名稱自動建立它,將下劃線轉換為空格。請參見verbose備註名稱。
validators
Field.validators
要為此欄位執行的驗證程式列表。有關更多資訊,請參閱驗證器文件。
註冊和獲取查詢
Field實現查詢註冊API。API可用於自定義類中哪些欄位可用於查詢,以及如何從欄位中提取並查詢。
2.欄位型別
AutoField
class AutoField(**options)
一個IntegerField,根據可用ID自動遞增。您通常不需要直接使用它; 如果不另行指定,主鍵欄位將自動新增到模型中。請參見 自動主鍵欄位。
BigAutoField
class BigAutoField(**options)
一個64位整數,很像一個AutoField,不同之處在於它是保證數字從1到9223372036854775807
。
BigIntegerField
classBigIntegerField(** options)
一個64位整數,很像一個IntegerField不同之處在於它是保證數字從-9223372036854775808 到 9223372036854775807
。此欄位的預設表單部件是TextInput。
BinaryField
class BinaryField(max_length=None, **options)
用於儲存原始二進位制資料的欄位。它可以分配 bytes, bytearray或memoryview。
預設情況下,BinaryField設定editable為False,在這種情況下,它不能包含在ModelForm中。
在Django 2.1中更改:
較舊的版本不允許設定editable為True,新版可以。
BinaryField 有一個額外的可選引數:
BinaryField.max_length
欄位的最大長度(以字元為單位)。在Django的驗證中使用MaxLengthValidator強制執行最大長度 。
濫用 BinaryField
雖然您可能會考慮將檔案儲存在資料庫中,但請考慮在99%的情況下這是不好的設計。此欄位不要來做靜態檔案處理。
BooleanField
class BooleanField(**options)
一個真/假欄位。
此欄位的預設表單部件是CheckboxInput,或者NullBooleanSelect(需要null=True)。
預設值BooleanField是None,當Field.default 沒有定義的時候。
在Django 2.1中更改:
在舊版本中,此欄位不允許null=True,因此您必須使用NullBooleanField。現在不鼓勵使用後者,因為它可能會在Django的未來版本中被棄用。
CharField
class CharField(max_length=None, **options)
字串欄位,用於從小到大的字串。
對於大量文字,請使用TextField。
此欄位的預設表單部件是TextInput。
CharField 有一個額外的必要引數:
CharField.max_length
欄位的最大長度(以字元為單位)。max_length在資料庫級別和Django的驗證中使用 MaxLengthValidator 強制執行 。
注意
如果您正在編寫一個必須可移植到多個數據庫後端的應用程式,您應該知道在某些後端max_length存在限制 。有關詳細資訊,請參閱 資料庫後端說明。↑
DateField
class DateField(auto_now=False, auto_now_add=False, **options)
日期,由Python中的datetime.date例項表示。有一些額外的可選引數:
DateField.auto_now
每次儲存物件時自動將欄位設定為現在。對“最後修改”的時間戳有用。請注意,始終 使用當前日期; 它不僅僅是您可以覆蓋的預設值。
該欄位僅在呼叫Model.save()時自動更新。在以其他方式更新其他欄位時,不會更新該欄位,例如QuerySet.update(),儘管您可以在更新中為該欄位指定自定義值。
DateField.auto_now_add
首次建立物件時自動將欄位設定為現在。用於建立時間戳。請注意,始終使用當前日期; 它不僅僅是您可以覆蓋的預設值。因此,即使您在建立物件時為此欄位設定了值,也會將其忽略。如果您希望能夠修改此欄位,請設定以下內容而不是 auto_now_add=True:
- 對於DateField:default=date.today- from datetime.date.today()
- 對於DateTimeField:default=timezone.now- from django.utils.timezone.now()
此欄位的預設表單部件是TextInput。管理員添加了一個JavaScript日曆,以及“今天”的快捷方式。包含一個可選的invalid_date錯誤訊息鍵值。
auto_now_add,auto_now和default是互斥的。這些選項的任何組合都將導致錯誤。
注意
當前實現,設定auto_now或auto_now_add為True會導致該欄位擁有editable=False和blank=True 的設定(所以你在編輯的時候看不見該欄位)。↑
注意
在auto_now和auto_now_add選項將在建立或更新日期的時候,使用始終使用的預設時區。如果您需要不同的東西,您可能需要考慮簡單地使用您自己的可呼叫預設值或覆蓋save() 而不是使用auto_now或auto_now_add; 或者使用一個DateTimeField決定如何在顯示時處理從datetime到date的轉換。↑
DateTimeField
class DateTimeField(auto_now=False, auto_now_add=False, **options)
日期和時間,由Python的datetime.datetime例項表示。採用和DateField相同的額外引數。
此欄位的預設表單部件是單個 TextInput。管理員使用兩個單獨的 TextInput部件和JavaScript快捷方式。
DecimalField
class DecimalField(max_digits=None, decimal_places=None, **options)
一個固定精度的十進位制數,由Python的 Decimal例項表示。它使用DecimalValidator驗證輸入 。
有兩個必需的引數:
DecimalField.max_digits
數字中允許的最大位數(不包含小數點)。請注意,此數字必須大於或等於decimal_places。
DecimalField.decimal_places
與數字一起儲存的小數位數。
例如,要儲存999,精度為2位小數的數字,您可以使用:
models.DecimalField(..., max_digits=5, decimal_places=2)
儲存大約10億的數字,精度為10位小數:
models.DecimalField(..., max_digits=19, decimal_places=10)
此欄位的預設表單控制元件是NumberInput 或者TextInput(需要設定localize=False
)。
注意
有關FloatField和DecimalField類之間差異的更多資訊 ,請參閱FloatField與DecimalField。
DurationField
class DurationField(**options)
用於儲存時間段的欄位 - 用Python中的timedelta。在PostgreSQL上使用時,使用的資料型別是interval,在Oracle上使用時,資料型別是INTERVAL DAY(9) TO SECOND(6);其它使用bigint微秒。
譯者注:我這裡使用的是Mysql
注意
DurationField計算在大多數情況下都適用。但是,在除PostgreSQL之外的所有資料庫上,將DurationField 與DateTimeField例項進行比較或計算將無法按預期工作。
EmailField
class EmailField(max_length=254, **options)
一個CharField,使用EmailValidator檢查該值是否使用一個有效的電子郵件地址 。
FileField
class FileField(upload_to=None, max_length=100, **options)
檔案上傳欄位。
注意
不支援primary_key
,如果使用則會引發錯誤。↑
有兩個可選引數:
upload_to
此屬性提供了設定上傳目錄和檔名的方法,可以通過兩種方式進行設定。在這兩種情況下,都將值傳遞給 Storage.save()方法。
如果指定字串值,則可能包含strftime() 格式,該格式將替換為檔案上傳的日期/時間(以便上傳的檔案不會填滿給定目錄)。例如:
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/')
如果使用預設的 FileSystemStorage,則字串值將附加到MEDIA_ROOT路徑中,以在本地檔案系統上形成將儲存上傳檔案的位置。如果您使用的是其他儲存,請檢查該儲存的文件以瞭解其處理upload_to的方式。
upload_to也可以是可呼叫的,例如函式。這將被呼叫以獲取上傳路徑,包括檔名。這個可呼叫的東西必須接受兩個引數並返回一個Unix風格的路徑(帶有正斜槓)以傳遞給儲存系統。這兩個引數是:
引數 | 描述 |
---|---|
instance | FileField所在模型的例項 。更具體地說,這是附加當前檔案的特定例項。 在大多數情況下,此物件尚未儲存到資料庫,因此如果它使用預設的AutoField,則可能還沒有其主鍵欄位的值。 |
filename | 最初提供給檔案的檔名。在確定最終目的地路徑時可能會或可能不會考慮這一點。 |
例如:
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)
storage
儲存物件,用於處理檔案的儲存和檢索。有關如何提供此物件的詳細資訊,請參閱管理檔案。
此欄位的預設表單部件是 ClearableFileInput。
使用方法
在模型中使用FileField或ImageField(見下文)需要幾個步驟:
(1)在您的設定檔案中,您需要定義MEDIA_ROOT為Django儲存上傳檔案的目錄的完整路徑(為了提高效能,這些檔案不會儲存在資料庫中。)。定義 MEDIA_URL為該目錄的基本公共URL。確保Web伺服器的使用者帳戶可以寫入此目錄。
(2)將FileField或ImageField新增到模型中,定義upload_to選項以指定MEDIA_ROOT用於上傳檔案的子目錄 。
(3)所有儲存在資料庫中的都是檔案的路徑(相對於MEDIA_ROOT)。你很可能想要使用Django提供的便利的url
屬性。例如,如果您ImageField欄位叫 mug_shot
,則可以在模板中獲取影象的絕對路徑 {{ object.mug_shot.url }}
。
例如,假設您MEDIA_ROOT設定為'/home/media'
,並 upload_to設定為'photos/%Y/%m/%d'
。'%Y'
是四位數的年份,'%m'
是兩位數的月份,'%d'
是兩位數的一天。如果您在2007年1月15日上傳檔案,它將儲存在目錄/home/media/photos/2007/01/15
中。
如果要檢索上傳檔案的磁碟檔名或檔案大小,可以分別使用name和 size屬性; 有關可用屬性和方法的更多資訊,請參閱 File 類引用和管理檔案 主題指南。
注意
該檔案是作為將模型儲存在資料庫中的一部分儲存的,因此在儲存模型之前,不能依賴磁碟上使用的實際檔名。↑
可以使用url屬性獲取上傳檔案的相對URL 。在內部,它呼叫底層Storage類的url()方法。
請注意,無論何時處理上傳的檔案,都應密切關注上傳檔案的位置以及檔案型別,以避免安全漏洞。驗證所有上傳的檔案,以確保檔案符合您的認可。例如,如果您盲目地讓某人上傳檔案而不進行驗證,則將檔案上傳到Web伺服器文件根目錄中的目錄,然後有人可以上傳CGI或PHP指令碼並通過訪問您網站上的URL來執行該指令碼。不要允許。(譯者注:可以使用編輯器的上傳功能,這樣會減少不安全檔案的漏洞,例如,KindEditor)
另請注意,即使是上傳的HTML檔案,因為它可以由瀏覽器執行(雖然不是由伺服器執行),但可能會造成相當於XSS或CSRF攻擊的安全威脅。
FileField例項在資料庫中建立為預設最大長度為100個字元的varchar 列。與其他欄位一樣,您可以使用max_length引數更改最大長度。
FileField和FieldFile
class FieldFile
當您訪問模型的FileField時,您將獲得一個FieldFile例項用於訪問基礎檔案的代理例項。
FieldFile的API 是File的映象,有一個關鍵區別:由類包裝的物件不一定是Python的內建檔案物件的包裝器。相反,它是Storage.open() 方法結果的包裝器,可以是File物件,也可以是自定義儲存的File API 實現。
除了從File繼承了API 諸如 read()和write(),FieldFile包括可用於與下面的檔案互動的幾種方法:
警告
這個類中,有兩種方法save()和delete(),預設儲存和FieldFile模型相關的物件在資料庫中。
FieldFile.name
Storage根路徑的與FileField關聯的相對路徑的檔名 。
FieldFile.size
底層Storage.size()方法的結果。
FieldFile.url
一個只讀屬性,用於通過呼叫基礎Storage類的url()方法來訪問檔案的相對URL 。
FieldFile.open(mode=‘rb’)
開啟或重新開啟與指定的 mode例項關聯的檔案。與標準Python open()方法不同,它不返回檔案描述符。
由於底層檔案在訪問時會隱式開啟,因此除了重置指向底層檔案的指標或更改mode外,可能無需呼叫此方法。
FieldFile.close()
行為類似於標準Python file.close()方法,並關閉與此例項關聯的檔案。
FieldFile.save(name, content, save=True)
此方法獲取檔名和檔案內容,並將它們傳遞給該欄位的儲存類,然後將儲存的檔案與模型欄位相關聯。如果要手動將檔案資料與FileField模型上的例項關聯 ,則該save() 方法用於保留該檔案資料。
採用兩個必需引數:name檔案的名稱,以及 content包含檔案內容的物件。
可選save引數控制是否在更改與此欄位關聯的檔案後儲存模型例項。預設為 True。
請注意,content引數應該是 django.core.files.File的例項,而不是Python的內建檔案物件。您可以從現有的Python檔案物件構造一個File如下:
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)
或者您可以從Python字串構造一個,如下所示:
from django.core.files.base import ContentFile
myfile = ContentFile("hello world")
有關更多資訊,請參閱管理檔案。
FieldFile.delete(save=True)
刪除與此例項關聯的檔案,並清除該欄位上的所有屬性。注意:如果檔案在delete()呼叫時恰好開啟,則此方法將關閉該檔案 。
可選save引數控制是否在刪除與此欄位關聯的檔案後儲存模型例項。預設為 True。
請注意,刪除模型時,不會刪除相關檔案。如果您需要清理孤立檔案,則需要自己處理(例如,使用可以手動執行或計劃通過例如cron定期執行的自定義管理命令)。
FilePathField
class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)
一個CharField,僅限於檔案系統上某個目錄中的檔名。有三個特殊引數,其中第一個是必需的:
FilePathField.path
需要。一個目錄的絕對檔案系統路徑,FilePathField從中可以選擇它。示例:"/home/images"
。
FilePathField.match
可選的。作為字串的正則表示式,FilePathField 用於過濾檔名。請注意,正則表示式將應用於基本檔名,而不是完整路徑。例如:"foo.*\.txt$"
,這將匹配一個名為foo23.txt
而不是 bar.txt或 foo23.png。
FilePathField.recursive
可選的。True或False。預設是False。指定是否path應包含所有子目錄
FilePathField.allow_files
可選的。True或False。預設是True。指定是否應包含指定位置的檔案。無論是這個還是 allow_folders必須為True。
FilePathField.allow_folders
可選的。True或False。預設是False。指定是否應包括指定位置的資料夾。無論是這個還是allow_files必須為True。
當然,這些引數可以一起使用。
一個潛在的問題是match適用於基本檔名,而不是完整路徑。所以,這個例子:
FilePathField(path="/home/images", match="foo.*", recursive=True)
將匹配/home/images/foo.png
但不是 /home/images/foo/bar.png 。
FilePathField例項在資料庫中建立為預設最大長度為100個字元varchar 的列。與其他欄位一樣,您可以使用max_length引數更改最大長度。
FloatField
class FloatField(**options)
由在Python中的float例項表示的浮點數。
此欄位的預設表單控制元件是NumberInput 或 TextInput(需要設定當localize=False
)。
FloatField 與 DecimalField
FloatField類有時夾雜了 DecimalField類。雖然它們都代表實數,但它們代表的數字不同。 FloatField內部使用Python的float型別,而DecimalField使用Python的Decimal型別。有關兩者之間差異的資訊,請參閱Python文件的 decimal模組。
ImageField
class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)
從FileField中繼承所有屬性和方法,但也驗證上傳的物件是否是有效影象。
除了可用FileField的屬性,一個ImageField也具有height和width屬性。
為了便於查詢這些屬性,ImageField有兩個額外的可選引數:
ImageField.height_field
每次儲存模型例項時,將使用影象高度自動填充的模型欄位的名稱。
ImageField.width_field
每次儲存模型例項時,將使用影象寬度自動填充的模型欄位的名稱。
需要 Pillow庫。
ImageField例項在資料庫中建立為預設最大長度為100個字元的varchar 列。與其他欄位一樣,您可以使用max_length引數更改最大長度。
此欄位的預設表單部件是 ClearableFileInput。
IntegerField
class IntegerField(**options)
整數。從-2147483648到2147483647
,在Django支援的所有資料庫中都是安全的。
它使用MinValueValidator和 MaxValueValidator根據預設資料庫支援的值驗證輸入。
此欄位的預設表單控制元件是NumberInput 或 TextInput(需要設定當localize=False
)。
GenericIPAddressField
class GenericIPAddressField(protocol=‘both’, unpack_ipv4=False, **options)
IPv4或IPv6地址,採用字串格式(例如192.0.2.30
或 2a02:42fe::4
)。此欄位的預設表單部件是TextInput。
IPv6地址規範化遵循 RFC 4291#section-2.2第 2.2節,包括該節第3段中建議使用的IPv4格式,如 ::ffff:192.0.2.0
。例如,2001:0::0:01
將被標準化為 2001::1
,::ffff:0a0a:0a0a
到::ffff:10.10.10.10
。所有字元都轉換為小寫。
GenericIPAddressField.protocol
限制指定協議的有效輸入。可接受的值是’both’(預設),‘IPv4’ 或’IPv6’。匹配不區分大小寫。
GenericIPAddressField.unpack_ipv4
解包IPv4對映地址,如::ffff:192.0.2.1
。如果啟用此選項,則該地址將被解壓縮到 192.0.2.1
。預設禁用,只能在protocol設定為'both
’時使用。
如果允許留空(blank=True
),則必須允許空值(NULL),因為空值儲存為NULL。
NullBooleanField
class NullBooleanField(**options)
就像BooleanField用null=True
。使用BooleanField代替此欄位,因為它可能在Django的未來版本中被棄用。
PositiveIntegerField
class PositiveIntegerField(**options)
像一個IntegerField,但必須是正數或零(0)。值從0到2147483647
在Django支援的所有資料庫中安全。由於向後相容性原因,接受0。
PositiveSmallIntegerField
class PositiveSmallIntegerField(**options)
像PositiveIntegerField,但只允許某個範圍下的值(取決於資料庫)。從0到32767
在Django支援的所有資料庫中安全。
SlugField
class SlugField(max_length=50, **options)
Slug是一個報紙術語。slug 是一種短標籤,只包含字母,數字,下劃線或連字元。它們通常用於URL。
像CharField一樣,您可以指定max_length(閱讀有關資料庫可移植性的說明以及max_length部分中的說明)。如果max_length未指定,Django將使用預設長度50。
實現了db_index=True
。
根據某些其他值的值自動預填充SlugField通常很有用。您可以在管理員中自動執行此操作 prepopulated_fields。
它用validate_slug
或 validate_unicode_slug
來進行驗證。
SlugField.allow_unicode
如果為True,該欄位除ASCII字母外還接受Unicode字母。預設為False。
SmallIntegerField
class SmallIntegerField(**options)
像一個IntegerField,但只允許在某個(資料庫相關的)範圍下的值。從-32768到32767
,在Django支援的所有資料庫中安全。
TextField
class TextField(**options)
一個大的文字欄位。此欄位的預設表單部件是 Textarea。
如果指定max_length屬性,它將影響自動生成的表單Textarea欄位部件。但是,它不會在模型或資料庫級別強制執行。使用一個 CharField。
TimeField
class TimeField(auto_now=False, auto_now_add=False, **options)
一個時間,由Python 中 datetime.time例項表示。同DateField,接受相同的自動填充選項。
此欄位的預設表單部件是TextInput。管理員添加了一些JavaScript快捷方式。
URLField
class URLField(max_length=200, **options)
一個CharField,應用於URL,經過URLValidator驗證 。
此欄位的預設表單部件是 TextInput。
與所有CharField子類一樣,URLField採用可選 max_length引數。如果未指定 max_length,則使用預設值200。
UUIDField
class URLField(max_length=200, **options)
用於儲存唯一通用識別符號的欄位。使用Python的 UUID類。在PostgreSQL上使用時,它以uuid資料型別儲存,否則以char(32)儲存。
通用唯一識別符號是AutoField(primary_key)
的一個很好的替代品。資料庫不會為您生成UUID,因此建議使用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
請注意,傳遞給default的是一個可呼叫函式(省略括號),而不是UUID的例項。
3.關係欄位
Django還定義了一組表示關係的欄位。
3.1 ForeignKey
class ForeignKey(to, on_delete, **options)
多對一的關係。需要兩個位置引數:與模型相關的類 和 on_delete選項。
要建立遞迴關係 - 與自身具有多對一關係的物件(譯者注:比如父評論和評論) - 使用
models.ForeignKey('self', on_delete=models.CASCADE)
如果需要在尚未定義的模型上建立關係,可以使用模型的名稱,而不是模型物件本身:
from django.db import models
class Car(models.Model):
manufacturer = models.ForeignKey(
'Manufacturer',
on_delete=models.CASCADE,
)
# ...
class Manufacturer(models.Model):
# ...
pass
這種在抽象模型上定義的關係何時被解析呢?當模型作為具體模型被子類化並且與抽象模型app_label無關時被解析:
#products/models.py
from django.db import models
class AbstractCar(models.Model):
manufacturer = models.ForeignKey('Manufacturer', on_delete=models.CASCADE)
class Meta:
abstract = True