大部分內容參考自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。