Model field reference - Field types（Django模塊字段參考 - 字段類型）

Field types（字段類型）

AutoField

class AutoField(**options)

一個IntegerField根據(jù)可用的ID自動遞增。你通常不需要直接使用它; 如果不另外指定，則主鍵字段將自動添加到您的模型中。請參閱自動主鍵字段。

BigAutoField

class BigAutoField(**options)

一個64位整數(shù)，很像一個AutoField不同之處在于它是保證從適合數(shù)字1到9223372036854775807。

BigIntegerField

class BigIntegerField(**options)

一個64位整數(shù)，很像一個IntegerField不同之處在于它是保證從適合數(shù)字-9223372036854775808到 9223372036854775807。這個字段的默認(rèn)表單部件是一個TextInput。

BinaryField

class BinaryField(**options)

用于存儲原始二進制數(shù)據(jù)的字段。它只支持bytes分配。請注意，此字段的功能有限。例如，無法過濾BinaryField值上的查詢集。也不能在一個ModelForm中包含一個BinaryField。

BooleanField

class BooleanField(**options)

一個true/false字段。這個字段的默認(rèn)表單部件是一個 CheckboxInput。如果您需要接受null值，則改用NullBooleanField 。當(dāng)Field.default沒有定義時， BooleanField的默認(rèn)值是None。

CharField

class CharField(max_length=None, **options)

一個字符串字段，用于從小到大的字符串。對于大量的文字，請使用TextField。
這個字段的默認(rèn)表單部件是一個TextInput。
CharField有一個額外的必要參數(shù)：CharField.max_length（字段的最大長度（以字符為單位））。max_length是在數(shù)據(jù)庫級別和Django驗證中強制執(zhí)行的。

注意：如果您正在編寫一個必須可移植到多個數(shù)據(jù)庫后端的應(yīng)用程序，則應(yīng)該知道max_length對某些后端有限制 。有關(guān)詳細(xì)信息，請參閱數(shù)據(jù)庫后端注釋。

DateField

class DateField(auto_now=False, auto_now_add=False, **options)

日期，用Python表示的一個datetime.date實例。有一些額外的，可選的參數(shù)：

DateField.auto_now
每次保存對象時自動將該字段設(shè)置為現(xiàn)在。用于“上次修改”時間戳。
請注意，始終 使用當(dāng)前日期; 它不只是一個默認(rèn)值，你可以覆蓋。
該字段只在調(diào)用Model.save()時自動更新。以其他方式更新其他字段時，字段不會更新，例如QuerySet.update()，您可以在更新中為字段指定自定義值。

DateField.auto_now_add
首次創(chuàng)建對象時自動將字段設(shè)置為現(xiàn)在。用于創(chuàng)建時間戳。
請注意，始終使用當(dāng)前日期；它不只是一個默認(rèn)值，你可以覆蓋。所以即使你在創(chuàng)建對象時為這個字段設(shè)置了一個值，它也將被忽略。
如果您希望能夠修改此字段，請設(shè)置以下內(nèi)容，而不是 auto_now_add=True：
*DateField：default=date.today- 從 datetime.date.today()
*DateTimeField：default=timezone.now- 從 django.utils.timezone.now()

這個字段的默認(rèn)表單部件是一個TextInput。管理員添加了JavaScript日歷和“今天”的快捷方式。包含一個附加的invalid_date錯誤消息key。

選項auto_now_add，auto_now和default互斥。這些選項的任何組合都會導(dǎo)致錯誤。

注意：在當(dāng)前的應(yīng)用中，設(shè)置auto_now或auto_now_add為 True，會導(dǎo)致該字段editable=False和blank=True 設(shè)置。

注意：在auto_now和auto_now_add選項將始終使用的日期默認(rèn)時區(qū)在創(chuàng)建或更新的時刻。如果你需要不同的東西，你可能要考慮簡單地使用自己的可調(diào)用默認(rèn)值或覆蓋save() 而不是使用auto_now或auto_now_add；或者使用一個DateTime字段而不是一個DateField決定如何處理從datetime到date的轉(zhuǎn)換。

DateTimeField

class DateTimeField(auto_now=False, auto_now_add=False, **options)

日期和時間，在Python中表示為datetime.datetime實例。帶有與DateField相同的額外參數(shù)。
這個字段的默認(rèn)表單部件是一個單一的TextInput。管理員使用兩個單獨的TextInput小部件與JavaScript快捷方式。

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

一個固定精度的十進制數(shù)，在Python中表示為Decimal實例。有兩個必要的參數(shù)：

DecimalField.max_digits
號碼中允許的最大位數(shù)。請注意，這個數(shù)字必須大于或等于decimal_places。

DecimalField.decimal_places
與數(shù)字一起存儲的小數(shù)位數(shù)。

例如，要存儲最大為999且?guī)в?位小數(shù)的數(shù)字，您可以使用：

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

而要存儲最大10億且?guī)в?0位小數(shù)的數(shù)字：

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

此字段的默認(rèn)表單控件是NumberInput當(dāng)localize為False或 TextInput以其他方式。

注意：關(guān)于FloatField 和 DecimalField 類的更多信息，請查閱FloatField vs. DecimalField.

DurationField

class DurationField(**options)

一個用于存儲時間周期的字段，類似于Python中的timedelta。當(dāng)使用PostgreSQL時，數(shù)據(jù)類型是interval，在使用Oracle時，數(shù)據(jù)類型為INTERVAL DAY(9) TO SECOND(6)。其他數(shù)據(jù)庫存存儲類型為bigint，以毫秒計算。

注意：DurationField的算法可用于大多數(shù)情況。但是在PostgreSQL以外的所有數(shù)據(jù)庫上，將DurationField的值與DateTimeField實例上的算術(shù)值進行比較將無法按預(yù)期進行。

EmailField

class EmailField(max_length=254, **options)

一個符合email地址規(guī)則的CharField字段。 它使用EmailValidator來驗證輸入。

FileField

class FileField(upload_to=None, max_length=100, **options)

一個用于文件上傳的字段。

注意：不支持primary_key參數(shù)， 如果使用將報錯。

有兩個參數(shù)選項：

  • FileField.upload_to
    這個屬性規(guī)定了上傳文件的路徑和名稱，并可以通過兩種方式設(shè)置。 在這兩種情況下，該值都傳遞給Storage.save()方法。
    如果指定一個字符串值，它可能包含的strftime()格式，這將是由文件上傳（以便上傳的文件不填寫指定的目錄）的日期/時間進行更換。 例如：
class MyModel(models.Model):
    # 文件將被上傳到`MEDIA_ROOT/uploads`目錄
    upload = models.FileField(upload_to='uploads/')
    # 或者...
    # 文件將被存儲于`MEDIA_ROOT/uploads/2015/01/30`目錄
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

如果你使用的是默認(rèn)的FileSystemStorage，則字符串值將被追加到您的MEDIA_ROOT路徑中，以形成上傳文件將存儲在本地文件系統(tǒng)上的位置。 如果您正在使用不同的存儲，請檢查存儲的文檔以了解它如何處理upload_to。
upload_to也可以是一個可調(diào)用的，比如一個函數(shù)。 這將被調(diào)用來獲取上傳路徑，包括文件名。 這個可調(diào)用的方法必須接受兩個參數(shù)，并返回一個Unix風(fēng)格的路徑（帶正斜杠）傳遞給存儲系統(tǒng)。 這兩個參數(shù)是：

Argument Description
instance An instance of the model where the FileField is defined. More specifically, this is the particular instance where the current file is being attached.
In most cases, this object will not have been saved to the database yet, so if it uses the default AutoField, it might not yet have a value for its primary key field.
filename The filename that was originally given to the file. This may or may not be taken into account when determining the final destination path.

例如：

def user_directory_path(instance, filename):
    # 文件將被上傳到：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
    存儲對象，用于處理文件的存儲和檢索。 有關(guān)如何提供此對象的詳細(xì)信息，請參閱管理文件。
    該字段的默認(rèn)表單部件是ClearableFileInput。
    在模型中使用FileField或ImageField（見下文）需要幾個步驟：
  1. 在您的設(shè)置文件中，您需要將MEDIA_ROOT定義為您希望Django存儲上傳文件的目錄的完整路徑。 （對于性能，這些文件不存儲在數(shù)據(jù)庫中。）將MEDIA_URL定義為該目錄的基本公用URL。 確保該目錄可由Web服務(wù)器的用戶帳戶寫入。
  2. 將FileField或ImageField添加到模型中，定義upload_to選項以指定MEDIA_ROOT的子目錄以用于上傳的文件。
  3. 所有將存儲在數(shù)據(jù)庫中的文件都是一個路徑（相對于MEDIA_ROOT）。 你很可能會想使用Django提供的便捷url屬性。 例如，如果您的ImageField被稱為mug_shot，則可以使用{{object.mug_shot.url}}在模板中獲取圖像的絕對路徑。

例如，假設(shè)你的MEDIA_ROOT設(shè)置為/home/media，upload_to設(shè)置為photos/%y/%m/%d。upload_to的%y/%m/%d部分是strftime()格式；%y是四位數(shù)年份，%m是兩位數(shù)月份，％d是兩位數(shù)字日期。 如果您在2007年1月15日上傳文件，它將被保存在/home/media/photos/2007/01/15目錄中。

如果你想檢索上傳文件的磁盤文件名或文件大小，則可以分別使用名稱和大小屬性; 有關(guān)可用屬性和方法的更多信息，請參閱文件類參考和管理文件主題指南。

注意：該文件作為模型保存在數(shù)據(jù)庫中的一部分進行保存，因此在保存模型之后，不能依賴磁盤上使用的實際文件名。

上傳的文件的相對URL可以使用url屬性獲取。在內(nèi)部，它調(diào)用底層存儲類的url()方法。

請注意，無論何時處理上傳的文件，都應(yīng)密切注意您上傳的文件的位置以及它們的類型，以避免安全漏洞。驗證所有上傳的文件，以確保這些文件是您認(rèn)為的文件。例如，如果您盲目地讓某人上傳文件（無需驗證）到Web服務(wù)器文檔根目錄中的某個目錄，則有人可以上傳CGI或PHP腳本，并通過訪問您網(wǎng)站上的URL來執(zhí)行該腳本。不要這樣做。

還要注意的是，即使是上傳的HTML文件，由于它可以被瀏覽器執(zhí)行（盡管不是由服務(wù)器執(zhí)行），也可能造成等同于XSS或CSRF攻擊的安全威脅。

FileField實例在數(shù)據(jù)庫中被創(chuàng)建為默認(rèn)最大長度為100個字符的varchar列。與其他字段一樣，您可以使用max_length參數(shù)更改最大長度。

FileField and FieldFile
class FieldFile

當(dāng)您訪問模型上的FileField時，將為您提供FieldFile的實例作為訪問基礎(chǔ)文件的代理。

FieldFile的API反映了File的特性，主要區(qū)別在于：由類包裝的對象不一定是Python內(nèi)置文件對象的包裝。 相反，它是Storage.open()方法（可能是File對象）的結(jié)果的一個包裝，也可能是File API的自定義存儲實現(xiàn)。

除了從File繼承的API（例如read()和write()之外，FieldFile還包括幾個可用于與基礎(chǔ)文件進行交互的方法：

警告：這個類的兩個方法save()和delete()默認(rèn)保存關(guān)聯(lián)的FieldFile的模型對象到數(shù)據(jù)庫中。

FieldFile.name

文件的名稱，包括從相關(guān)FileField的Storage的根目錄的相對路徑。

FieldFile.size

底層Storage.size()方法的結(jié)果。

FieldFile.url

通過調(diào)用基礎(chǔ)Storage類的url()方法來訪問文件的相對URL的只讀屬性。

FieldFile.open（模式= 'RB'）

以指定模式打開或重新打開與此實例關(guān)聯(lián)的文件。與標(biāo)準(zhǔn)的Python open()方法不同，它不返回文件描述符。

由于底層文件在訪問時隱式打開，因此可能不需要調(diào)用此方法，除非將指針重置為底層文件或更改模式。

FieldFile.close()

行為與標(biāo)準(zhǔn)的Python file.close()方法相似，并關(guān)閉與此實例關(guān)聯(lián)的文件。

FieldFile.save（name，content，save = True）

此方法將文件名和文件內(nèi)容傳遞給字段的存儲類，然后將存儲的文件與模型字段相關(guān)聯(lián)。如果要手動將文件數(shù)據(jù)與模型上的FileField實例相關(guān)聯(lián)，則使用save()方法來保留該文件數(shù)據(jù)。

需要兩個必需的參數(shù)：名稱是文件的名稱，內(nèi)容是包含文件內(nèi)容的對象。可選的save參數(shù)控制在與該字段關(guān)聯(lián)的文件被更改后是否保存模型實例。默認(rèn)為True。

請注意，content參數(shù)應(yīng)該是django.core.files.File的一個實例，而不是Python的內(nèi)置文件對象。你可以像這樣從現(xiàn)有的Python文件對象構(gòu)造一個文件：

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字符串構(gòu)建，例如：

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

有關(guān)更多信息，請參閱管理文件。

FieldFile.delete（save=True）

刪除與此實例關(guān)聯(lián)的文件，并清除該字段上的所有屬性。 注意：這個方法會在調(diào)用delete()的時候關(guān)閉文件。

可選的save參數(shù)控制在與該字段關(guān)聯(lián)的文件被刪除后是否保存模型實例。 默認(rèn)為True。

請注意，刪除模型時，相關(guān)文件不會被刪除。 如果您需要清理孤立的文件，則需要自己處理（例如，使用自定義管理命令，可以手動運行或計劃通過例如cron定期運行）。

FilePathField

class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)

一個CharField，其選擇僅限于文件系統(tǒng)上某個目錄中的文件名。有三個特殊的論點，其中第一個是必需的：

FilePathField.path

必須。FilePathField應(yīng)該從中選擇的目錄的絕對文件系統(tǒng)路徑。例如：/ home / images。

FilePathField.match

可選的。FilePathField將用來過濾文件名的正則表達(dá)式，作為字符串。請注意，正則表達(dá)式將應(yīng)用于基本文件名，而不是完整路徑。例如：foo.*\.txt$，它將匹配一個名為foo23.txt但不是bar.txt或foo23.png的文件。

FilePathField.recursive

可選的。True或False。默認(rèn)是False。指定是否應(yīng)該包含路徑的所有子目錄。

FilePathField.allow_files

可選的。True或False。默認(rèn)是True。指定是否應(yīng)該包含指定位置的文件。這個選項或者allow_folders必須有一個為True。

FilePathField.allow_folders

可選的。True或False。默認(rèn)是False。指定是否應(yīng)該包含指定位置的文件夾。這個或者allow_files必須是True。

當(dāng)然，這些參數(shù)可以一起使用。

一個潛在的問題是匹配適用于基本文件名，而不是完整路徑。所以，這個例子：

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

...匹配/home/images/foo.png，但不匹配/home/images/foo/bar.png，因為匹配適用于基本文件名（foo.png和bar.png）。

FilePathField實例在數(shù)據(jù)庫中創(chuàng)建，默認(rèn)最大長度為100個字符的varchar列。與其他字段一樣，您可以使用max_length參數(shù)更改最大長度。

FloatField

class FloatField(**options)

由浮點實例在Python中表示的浮點數(shù)。

當(dāng)localize為False或TextInput時，此字段的默認(rèn)表單窗口小部件為NumberInput。

FloatField vs DecimalField
FloatField類有時與DecimalField類混合在一起。 盡管它們都代表實數(shù)，但它們代表的數(shù)字不同。 FloatField在內(nèi)部使用Python的float類型，而DecimalField使用Python的Decimal類型。 有關(guān)這兩者之間的區(qū)別的信息，請參閱Python的十進制模塊的文檔。

ImageField

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)

從FileField繼承所有的屬性和方法，但也驗證上傳的對象是一個有效的圖像。
除了可用于FileField的特殊屬性外，ImageField還具有高度和寬度屬性。
為了便于查詢這些屬性，ImageField有兩個額外的可選參數(shù)：

  • ImageField.height_field
    每次保存模型實例時將使用圖像的高度自動填充模型字段的名稱。
  • ImageField.width_field
    每次保存模型實例時將使用圖像寬度自動填充模型字段的名稱。

需要Pillow庫。
ImageField實例在數(shù)據(jù)庫中被創(chuàng)建為默認(rèn)最大長度為100個字符的varchar列。 與其他字段一樣，您可以使用max_length參數(shù)更改最大長度。
該字段的默認(rèn)表單部件是ClearableFileInput。

IntegerField

class IntegerField(**options)

一個整數(shù)字段。在Django支持的所有數(shù)據(jù)庫中，值從-2147483648到2147483647都是安全的。 當(dāng)localize為False或TextInput時，此字段的默認(rèn)表單窗口小部件為NumberInput。

GenericIPAddressField

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)

以字符串格式（例如192.0.2.30或2a02:42fe::4）的IPv4或IPv6地址。 該字段的默認(rèn)表單窗口小部件是一個TextInput。

IPv6地址規(guī)范化遵循RFC 4291#section-2.2，包括使用該節(jié)第3段中建議的IPv4格式，如::ffff:192.0.2.0。 例如，2001:0::0:01將被標(biāo)準(zhǔn)化為2001::1，::ffff:0a0a:0a0a標(biāo)準(zhǔn)化為::ffff:10.10.10.10。 所有的字符都被轉(zhuǎn)換成小寫字母。

GenericIPAddressField.protocol

限制有效的輸入到指定的協(xié)議。 接受的值是both（默認(rèn)），IPv4或IPv6。 匹配不區(qū)分大小寫。

GenericIPAddressField.unpack_ipv4

解包IPv4映射的地址，如::ffff:192.0.2.1。 如果啟用該選項，則該地址將被解包到192.0.2.1。 默認(rèn)是禁用的。 只能在協(xié)議設(shè)置為both時使用。
如果允許空白值，則必須允許空值，因為空白值存儲為空。

NullBooleanField

class NullBooleanField(**options)

類似一個BooleanField，但允許NULL作為其中一個選項。 使用這個而不是一個null = True的BooleanField。 此字段的默認(rèn)表單窗口小部件是NullBooleanSelect。

PositiveIntegerField

class PositiveIntegerField(**options)

類似IntegerField，但必須是正數(shù)或零(0)。 在Django支持的所有數(shù)據(jù)庫中，從0到2147483647的值是安全的。 出于向下兼容性的原因，接受值0。

PositiveSmallIntegerField

class PositiveSmallIntegerField(**options)

類似PositiveIntegerField，但只允許某個（數(shù)據(jù)庫相關(guān)）點下的值。 在Django支持的所有數(shù)據(jù)庫中，值從0到32767是安全的。

SlugField

class SlugField(max_length=50, **options)

Slug 是一個新聞術(shù)語。一個Slug是一個短的標(biāo)簽的東西，只包含字母，數(shù)字，下劃線或連字符。 它們通常用在URL中。
類似CharField，你可以指定max_length（同樣可以讀取關(guān)于數(shù)據(jù)庫可移植性和max_length的注釋）。 如果未指定max_length，則Django將使用默認(rèn)長度50。

暗示將Field.db_index設(shè)置為True。

根據(jù)其他值的值自動預(yù)填充SlugField通常是有用的。 您可以使用prepopulated_fields在管理員中自動執(zhí)行此操作。

SlugField.allow_unicode

如果為True，則該字段除ASCII字母外還接受Unicode字母。 默認(rèn)為False。

SmallIntegerField

class SmallIntegerField(**options)

像IntegerField一樣，但只允許在某個（數(shù)據(jù)庫相關(guān)）點下的值。 在Django支持的所有數(shù)據(jù)庫中，-32768到32767的值是安全的。

TextField

class TextField(**options)

一個大的文本字段。 該字段的默認(rèn)表單窗口小部件是一個Textarea。
如果你指定了max_length屬性，它將會反映在自動生成的表單字段的Textarea小部件中。 但是，它不是在模型或數(shù)據(jù)庫級別執(zhí)行的。 為此使用CharField。

TimeField

class TimeField(auto_now=False, auto_now_add=False, **options)

一個時間，用Python表示一個datetime.time實例。 接受與DateField相同的自動填充選項。

該字段的默認(rèn)表單窗口小部件是一個TextInput。 管理員添加了一些JavaScript快捷方式。

URLField

class URLField(max_length=200, **options)

一個符合URL標(biāo)準(zhǔn)的CharField。
該字段的默認(rèn)表單窗口小部件是一個TextInput。
像所有CharField子類一樣，URLField接受可選的max_length參數(shù)。 如果您不指定max_length，則使用默認(rèn)值200。

UUIDField

class UUIDField(**options)

用于存儲通用唯一標(biāo)識符的字段。 使用Python的UUID類。 在PostgreSQL上使用時，它將以uuid數(shù)據(jù)類型存儲，否則以char(32)存儲。
對于primary_key，通用唯一標(biāo)識符是AutoField的一個很好的選擇。 數(shù)據(jù)庫不會為你生成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

請注意，可調(diào)用（使用括號省略）傳遞給默認(rèn)值，而不是UUID的實例。

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

友情鏈接更多精彩內(nèi)容