Django文檔——Model字段類型(Field Types)

大部份內容參考自http://wrongwaycn.github.io/django11/topics/db/models/index.html#topics-db-models ,內容是django1.0的中文翻譯。

我的根據django1.5的英文文檔作了部分修改和添加。

字段類型(Field types)

AutoField

它是一個根據 ID 自增加的 IntegerField 字段。一般，你沒必要直接使用該字段。若是你沒在別的字段上指定主 鍵，Django 就會自動添加主鍵字段。

BigIntegerField

64位整數，相似於IntegerField，範圍從-9223372036854775808 到9223372036854775807。默認的form widget 是TextInput。

BooleanField

一個布爾值(true/false)字段。

默認的form widget是CheckboxInput。

若是要使用null做爲空值，可以使用NullBooleanField。

CharField

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

它是一個字符串字段，對小字符串和大字符串都適用。

對於更大的文本，應該使用TextField 。

默認的form widget是TextInput。

CharField 有一個必須傳入的參數：max_length,字段的最大字符數。它做用於數據庫層級和 Django 的數據驗證層級。

CommaSeparatedInterField

class CommaSeparatedIntegerField(max_length=None[, **options])

它用來存放以逗號間隔的整數序列。和 CharField 同樣，必須爲它提供 max_length 參數。並且要注意不一樣數據庫對 max_length 的限制。

DateField

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

該字段利用 Python 的 datetime.date 實例來表示日期。下面是它額外的可選參數：

DateField.auto_now：每一次保存對象時，Django 都會自動將該字段的值設置爲當前時間。通常用來表示 "最後修改" 時間。要注意使用的是當前日期，而並不是默認值，因此

不能經過重寫默認值的辦法來改變保存時間。

DateField.auto_now_add：在第一次建立對象時，Django 自動將該字段的值設置爲當前時間，通常用來表示對象建立時間。它使用的一樣是當前日期，而非默認值。

默認的form widget是TextInput。

Note:當auto_now或者auto_now_add設置爲True時，字段會有editable=True和blank=True的設定。

DateTimeField

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

該字段利用 datetime.datetime 實例表示日期和時間。該字段所按受的參數和 DateField 同樣。

默認的form widget是TextInput。Django 的admin使用兩個帶有 JavaScript 快捷選項TextInput分別表示日期和時間。

DecimalField

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

它是使用 Decimal 實例表示固定精度的十進制數的字段。它有兩個必須的參數：

DecimalField.max_digits：數字容許的最大位數

DecimalField.decimal_places：小數的最大位數

例如，要存儲的數字最大值是999，而帶有兩個小數位，你可使用：

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

要存儲大約是十億級且帶有10個小數位的數字，就這樣寫：

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

默認的form widget是TextInput。

EmailField

  class EmailField([max_length=75, **options])

它是帶有 email 合法性檢測的A CharField 。

Note：最大長度默認爲75，並不能存儲全部與RFC3696/5321兼容的email地址。若是要存儲全部，請設置 

max_length=254。設置爲75是歷史遺留問題。

FileField

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

文件上傳字段

Note：該字段不支持 primary_key 和 unique 參數，不然會拋出 TypeError 異常。

它有一個必須的參數：

FileField.upload_to

用於保存文件的本地文件系統。它根據 MEDIA_ROOT 設置肯定該文件的 url 屬性。

該路徑能夠包含 時間格式串strftime()，能夠在上傳文件的時候替換成當時日期／時間(這樣，就不會出如今上傳文件把某個目錄塞滿的狀況了)。

該參數也能夠是一個可調用項，好比是一個函數，能夠調用函數得到包含文件名的上傳路徑。這個可調用項必需要接受兩個參數，

而且返回一個保存文件用的 Unix-Style 的路徑(用 / 斜槓)。兩個參數分別是：

    instance ：定義了當前 FileField 的 model 實例。更準確地說，就是以該文件爲附件的 model 實例。

大多數狀況下，在保存該文件時， model 實例對象還並無保存到數據庫，這是由於它頗有可能使用默認的 AutoField，而此時它尚未從數據庫中得到主鍵值。

    filename ：上傳文件的原始名稱。在生成最終路徑的時候，有可能會用到它。

還有一個可選的參數：

FileField.storage

負責保存和獲取文件的對象。

默認的form widget是FileInput。

Note：在 model 中使用 FileField 或 ImageField 要按照如下的步驟：

1.在項目settings文件中，你要定義 MEDIA_ROOT ，將它的值設爲用來存放上傳文件的目錄的完整路徑。(基於性能的考慮，Django 沒有將文件保存在數據庫中).

而後定義 MEDIA_URL ，將它的值設爲表示該目錄的網址。 

要確保 web 服務器所用的賬號擁有對該目錄的寫權限。

2.在 model 裏面添加 FileField 或 ImageField ，而且確認已定義了 upload_to 項，讓 Django 知道應該用 

MEDIA_ROOT 的哪一個子目錄來保存文件。

3.存儲在數據庫當中的僅僅只是文件的路徑(並且是相對於 MEDIA_ROOT 的相對路徑)。你可能已經想到利用 

Django 提供的 url 這個方便的屬性。舉個例子，若是你的 ImageField 名稱是 mug_shot，那麼你能夠在模板 

中使用

{{ object.mug_shot.url }}

就能獲得圖片的完整網址。

例如，假設你的 MEDIA_ROOT 被設爲 '/home/media'，upload_to 被設爲 'photos/%Y/%m/%d'。 upload_to 中 

的 '%Y/%m/%d' 是一個strftime()， '%Y' 是四位的年份，'%m' 是兩位的月份， '%d' 是兩位的日子。若是你 

在2007年01月15號上傳了一個文件，那麼這個文件就保存在 /home/media/photos/2007/01/15 目錄下。

若是你想獲得上傳文件的本地文件名稱，文件網址，或是文件的大小，你可使用 name, url 和 size 屬性。

Note：在上傳文件時，要警戒保存文件的位置和文件的類型，這麼作的緣由是爲了不安全漏洞。對每個上傳 

文件都要驗證，這樣你才能確保上傳的文件是你想要的文件。舉個例子，若是你盲目地讓別人上傳文件，而沒有 

對上傳文件進行驗證，若是保存文件的目錄處於 web 服務器的根目錄下，萬一有人上傳了一個 CGI 或是 PHP 

腳本，而後經過訪問腳本網址來運行上傳的腳本，那可就太危險了。千萬不要讓這樣的事情發生！

默認狀況下，FileField 實例在數據庫中的對應列是 varchar(100) ，和其餘字段同樣，你能夠利用max_length 參數改變字段的最大長度。

FileField and FieldFile

  class FieldFile

當你訪問一個Model的FileField字段時，會獲得一個FieldFile的實例做爲代理去訪問底層文件。實例有幾種屬性和方法能夠用來和文件數據進行互動。

FieldFile.url

經過只讀的方式調用底層存儲(Storage)類的 url() 方法，來訪問該文件的相對URL。

FieldFile.open(mode='rb')

相似於python的open()方法。

FieldFile.close()

相似於python的close()方法。

FieldFile.save(name,content,save=True)

這種方法將filename和文件內容傳遞到該字段而後存儲到該模型。該方法須要兩個必須的參數：name， 文件的名稱， content， 包含文件內容的對象。save 參數是可選的，主 

要是控制文件修改後實例是否保存。默認是 True 。須要注意的是，content 參數是 django.core.files.File 的一個實例，不是Python的內置File對象。你可使 

用他從現有的Python文件對象中構建一個文件，以下所示：

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/tmp/hello.world')
myfile = File(f)

或者從字符串中構造：

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

FieldFile.delete(save=True)

刪除此實例相關的文件，並清除該字段的全部屬性。

Note：當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.gif。

FilePathField.recursive

可選參數。它的值是 True 或 False。默認值是 False。它指定是否包含 path 下的子目錄。

FilePathField.allow_files

該項屬於Django1.5新增內容。可選參數，它的值是 True 或 False。默認值是 True。它指定是否包含指定位置的文件。該項與allow_folders 必須有一個是 True。

FilePathField.allow_folders

Django1.5新增內容。可選參數，它的值是True或False。默認是False。它指定是否包含指定位置的目錄。該項與allow_files必須有一個是 True。

前面已經提到了 match 只匹配文件名稱，而不是文件路徑。因此下面這個例子：

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

將匹配 /home/images/foo.gif ，而不匹配 /home/images/foo/bar.gif。這是由於 match 只匹配文件名
(foo.gif 和 bar.gif).

默認狀況下， FilePathField 實例在數據庫中的對應列是varchar(100) 。和其餘字段同樣，你能夠利用 max_length 參數改變字段的最大長度。

FloatField

 class FloatField([**options])

該字段在 Python 中使用float 實例來表示一個浮點數。

默認的form widget是TextInput。

請注意FloatField與DecimalField的區別。

ImageField

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

和 FileField 同樣，只是會驗證上傳對象是否是一個合法的圖象文件。

除了那些在 FileField 中有效的參數以外， ImageField 還可使用 File.height and File.width 兩個屬性 。

它有兩個可選參數：

ImageField.height_field

保存圖片高度的字段名稱。在保存對象時，會根據該字段設定的高度，對圖片文件進行縮放轉換。

ImageField.width_field

保存圖片寬度的字段名稱。在保存對象時，會根據該字段設定的寬度，對圖片文件進行縮放轉換。

默認狀況下， ImageField 實例對應着數據庫中的varchar(100) 列。和其餘字段同樣，你可使 用 max_length 參數來改變字段的最大長度。

IntegerField

  class IntegerField([**options])

整數字段。默認的form widget是TextInput。

IPAddressField

 class IPAddressField([**options])

以字符串形式(好比 "192.0.2.30")表示 IP 地址字段。默認的form widget是TextInput。

GenericIPAddressField

 class GenericIPAddressField([**options])

Django1.4新增。

以字符串形式(好比 "192.0.2.30"或者"2a02:42fe::4")表示 IP4或者IP6 地址字段。默認的form widget是TextInput。

IPv6的地址格式遵循RFC 4291 section 2.2。好比若是這個地址其實是IPv4的地址，後32位能夠用10進制數表示，例如 "::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’ 時才能夠啓用。

NullBooleanField

 class NullBooleanField([**options])

與 BooleanField 類似，但多了一個 NULL 選項。建議用該字段代替使用 null=True 選項的 BooleanField 。 

默認的form widget是NullBooleanSelect。

PositiveIntegerField

class PositiveIntegerField([**options])

和 IntegerField 類似，但字段值必須是非負數。

PositiveSmallIntegerField

 class PositiveSmallIntegerField([**options])

和 PositiveIntegerField 相似，但數值的取值範圍較小，受限於數據庫設置。

SlugField

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

Slug 是一個新聞術語，是指某個事件的短標籤。它只能由字母，數字，下劃線或連字符組成。通賞狀況下，它被用作網址的一部分。

和 CharField 相似，你能夠指定 max_length (要注意數據庫兼容性和本節提到的 max_length )。若是沒有指定 max_length ，Django 會默認字段長度爲50。

該字段會自動設置 Field.db_index to True。

基於其餘字段的值來自動填充 Slug 字段是頗有用的。你能夠在 Django 的管理後臺中使用prepopulated_fields 來作到這一點。

SmallIntegerField

 class SmallIntegerField([**options])

和 IntegerField 相似，但數值的取值範圍較小，受限於數據庫的限制。

TextField

 class TextField([**options])

大文本字段。默認的form widget是Textarea。

TimeField

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

該字段使用 Python 的 datetime.time 實例來表示時間。它和 DateField 接受一樣的自動填充的參數。

默認的form widget是TextInput。

URLField

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

保存 URL 的 CharField 。

和全部 CharField 子類同樣，URLField 接受可選的 max_length 參數，該參數默認值是200。