Django 1.10中文文檔-模型參考

時間 2019-12-08

標籤 django 1.10 中文文檔模型參考欄目 Python 简体版

原文原文鏈接

模型字段

本文檔包含了Django提供的所有模型 Field 包括字段選項和字段類型的API參考。html

參見python

若是內建的字段不能知足你的需求, 你能夠蠶食 django-localflavor (documentation), 其中包含對特定國家和文化的各類配套代碼。mysql

同時, 也能夠自定義模型字段.git

註解github

嚴格意義上來說， Model定義在 django.db.models.fields 裏面, 但爲了使用方便，它們被導入到django.db.models 中；通常使用 from django.db import models 導入，而後使用 models.<Foo>Field的形式使用字段。web

字段選項

下列參數是所有字段類型均可用的，並且都是可選擇的。正則表達式

`null`

Field. null

若是爲 True, Django 將把空值在數據庫中存爲 NULL ，默認爲 is False 。sql

不要爲字符串類型字段設置 null ，例如 CharField 和 TextField 。由於這樣會把空字符串存爲 NULL 。若是字符串字段設置了 null=True ，那意味着對於「無數據」有兩個可能的值： null 和空字符串。這種明顯是多餘的，Django 的慣例是使用空字符串而不是NULL。數據庫

不管是字符串字段仍是非字符串字段，若是你但願在表單中容許存在空值，必需要設置 blank=True，由於僅僅影響數據庫存儲。(參見 blank)。express

註解

在使用Oracle 數據庫時，數據庫將存儲 NULL 來表示空字符串，而與這個屬性無關。

若是你但願 BooleanField 接受 null 值, 那麼使用 NullBooleanField 代替。

`blank`

Field. blank

若是爲 True, 則該字段容許爲空。默認爲 False 。

注意它和 null 不一樣。 null 純粹是數據庫範疇的概念，而 blank 是數據驗證範疇。若是字段設置 blank=True, 表單驗證時將容許輸入空值。若是字段設置 blank=False, 則該字段爲必填。

`choices`

Field. choices

它是一個可迭代的結構(e.g., 列表或元組) 。由可迭代的二元組組成 (e.g. [(A, B), (A, B) ...])，用來給字段提供選擇項。若是設置了 choices ，默認表格樣式就會顯示選擇框，而不是標準的文本框，並且這個選擇框的選項就是 choices 中的元組。

每一個元組中的第一個元素，是存儲在數據庫中的值；第二個元素是該選項描述。好比:

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)

固然也能夠在模型類的外部定義choices而後引用它，可是在模型類中定義choices和其每一個choice的name(即元組的第二個元素)能夠保存全部使用choices的信息，也使得choices更容易被應用（例如， Student.SOPHOMORE 能夠在任何引入 Student 模型的地方生效)。

也能夠將選項歸類到已命名的組中用來達成組織整理的目的:

MEDIA_CHOICES = (
    ('Audio', (
            ('vinyl', 'Vinyl'),
            ('cd', 'CD'),
        )
    ),
    ('Video', (
            ('vhs', 'VHS Tape'),
            ('dvd', 'DVD'),
        )
    ),
    ('unknown', 'Unknown'),
)

每一個元組的第一個元素是組的名字。第二個元素是一組可迭代的二元元組，每個二元元組包含一個值和一個適合人看的名字構成一個選項。分組的選項可能會和未分組的選項合在同一個list中。（就像例中的 unknown 選項）。

對於包含 choices 的模型字段, Django 將會加入一個方法來獲取當前字段值的易於理解的名稱 (即元組的第二個值)。參見數據庫API文檔中的 get_FOO_display() 。

choices 只要是可迭代的對象就行 – 並不必定要是列表和元組。這樣你能夠動態構建choices。可是若是你本身搞不定動態的 choices 。你最好仍是使用 ForeignKey 來構建一個合適的數據庫表。而對於靜態數據來講， choices 是不改變的。

除非在字段中設置了 blank=False 不然將選擇框中將包含一個 "---------" 的標籤。只要在添加一個 None 到 choices 元組中就能夠改變這一行爲。e.g. (None, 'Your String For Display') ，或者, 你能夠用一個空字符串代替 None 好比在一個 CharField 。

`db_column`

Field. db_column

數據庫中儲存該字段的列名。若是未指定，那麼Django將會使用Field名做爲字段名。

若是你的數據庫列名是SQL語句的保留字，或者是包含不能做爲Python 變量名的字符，如連字符。這也不會有問題， Django 會在後臺給列名和表名加上雙引號。

`db_index`

Field. db_index

若是爲 True,將會爲這個字段建立數據庫索引。

`db_tablespace`

Field. db_tablespace

The name of the database tablespace to use for this field’s index, if this field is indexed. The default is the project’s DEFAULT_INDEX_TABLESPACE setting, if set, or the db_tablespace of the model, if any. If the backend doesn’t support tablespaces for indexes, this option is ignored.

`default`

Field. default

該字段的默認值. 它能夠是一個值或者一個可調用對象。若是是一個可調用對象，將會在建立新對象時調用。

這個默認值不能夠是一個可變對象(好比 模型實例 , 列表 , 集合 等等)。由於對於全部模型的一個新的實例來講，它們指向同一個引用。或者，把他們封裝爲一個可調用的對象。例如，有一個自定義的 JSONField,想指定一個特定的字典值，能夠這樣:

def contact_default():
    return {"email": "to1@example.com"}

contact_info = JSONField("ContactInfo", default=contact_default)

lambda 表達式不能做爲 default 的參數值，由於她們沒法被migrations序列化。

對於將映射到模型實例的外鍵之類的字段，默認值應該是它們引用的字段的值(除非to字段設置爲pk)，而不是模型實例。

對於將映射到模型實例的字段，例如 ForeignKey 。其默認值應該是他們引用的字段值( 除非to_field 設置了 pk)而不是模型實例。

默認值會在新實例建立而且沒有給該字段提供值時使用。若是字段爲主鍵，默認值也會在設置爲 None````None 時使用。

`editable`

Field. editable

若是設爲 False , 這個字段將不會出如今admin或者其餘 ModelForm 中。同時也會跳過模型驗證。默認是 True。

`error_messages`

Field. error_messages: error_messages 參數用於重寫默認的錯誤提示，經過字典的key來匹配將要改變的錯誤類型。

錯誤提示的key包括 null, blank, invalid, invalid_choice, unique, 和 unique_for_date 。下面的字段類型中的 error_messages 的 keys 是不同的。

`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特定的字符。請確保你所使用的help text可以避免一些不信任用戶的跨站腳本攻擊。

`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, FileField 的其餘全部字段。

當設置了 unique 爲 True 後，能夠沒必要再指定 db_index, 由於 unique 也會建立索引。

`unique_for_date`

Field. unique_for_date

設置爲 DateField 或者 DateTimeField 字段的名字，表示要求該字段對於相應的日期字段值是惟一的。

例如，字段 title 設置了 unique_for_date="pub_date" ，那麼Django將不會容許在同一 pub_date 的兩條記錄的 title 相同。

須要注意的是，若是你設置的是一個 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 field names.

`validators`

Field. validators

該字段將要運行的一個Validator的列表。更多信息參見 validators 文檔。

註冊和查詢

Field 實現了查詢註冊API 。該API 能夠用於自定義一個字段類型的查詢，以及如何從一個字段獲取查詢。

字段類型

`AutoField`

class django.db.models. AutoField ( **options )

一個根據實際ID自動增加的 IntegerField 。一般不須要直接使用它,若是表中沒有設置主鍵時，將會自動添加一個自增主鍵。參考自增主鍵。

`BigAutoField`

class django.db.models. BigAutoField ( **options )

一個64位整數, 和 AutoField 相似，不過它的範圍是 1 到 9223372036854775807 。

`BigIntegerField`

class django.db.models. BigIntegerField ( **options )

一個64位整數, 和 IntegerField 相似，不過它容許的值範圍是 -9223372036854775808 到 9223372036854775807 。這個字段默認的表單組件是一個 TextInput.

`BinaryField`

class django.db.models. BinaryField ( **options )

這是一個用來存儲原始二進制碼的字段。支持 bytes 賦值。注意這個字段只有頗有限的功能。好比，不能在一個 BinaryField 值的上進行查詢過濾。 ModelForm 中也不容許包含 BinaryField 。

濫用 BinaryField

可能你想使用數據庫來存儲文件，可是99%的狀況下這都是很差的設計。這個字段不是代替靜態文件的最佳方式。

`BooleanField`

class django.db.models. BooleanField ( **options )

一個 true/false 字段。

這個字段的默認表單部件是 CheckboxInput 。

若是要容許 null 值，那麼可使用 NullBooleanField 代替。

若是 Field.default 沒有指定，: BooleanField 的默認值將是 None 。

`CharField`

class django.db.models. CharField ( max_length=None, **options )

字符字段。

對於比較大的文本內容,請使用 TextField 類型。

這個字段的默認表單部件是 TextInput.

CharField 字段有個額外參數:

CharField. max_length: 字段容許的最大字符串長度。這將在數據庫中和表單驗證時生效。

註解

若是你在寫一個須要導出到多個不一樣數據庫後端的應用，你須要注意某些後端對 max_length 有一些限制，查看數據庫後端注意事項來獲取更多的細節。

MySQL users

若是你使用的是 MySQLdb 1.2.2 設置的是 utf8_bin 校對 (這不是默認項), 你必須瞭解一些問題。詳細請參考 MySQL 數據庫注意事項。

`CommaSeparatedIntegerField`

class django.db.models. CommaSeparatedIntegerField ( max_length=None, **options )

1.9 版後已移除: 這個字段可使用 CharField 的 validators=[validate_comma_separated_integer_list] 代替。

一個逗號分隔的整數字段。和 CharField 同樣， max_length 是必填參數，同時再數據庫移植時也須要注意。

`DateField`

class django.db.models. 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 。在admin中會添加一個JavaScript的日期插件，帶有一個「Today」的快捷按鈕。也包含 invalid_date 錯誤消息。

選項 auto_now_add, auto_now, 和 default 是相互排斥的，他們之間的任何組合將會發生錯誤的結果。

註解

在當前框架實現中, 設置 auto_now 或者 auto_now_add 爲 True 都會使字段同時獲得兩個設置 editable=False 和 blank=True 。

註解

auto_now 和 auto_now_add 這兩個設置會在對象建立或更新時，老是使用 default timezone 的日期。你能夠考慮一下簡單地使用你本身的默認調用或者重寫 save() 方法來代替使用 auto_now和 auto_now_add;也可使用 DateTimeField 類型代替 DateField ，而後在顯示時間的時候再決定如何從 datetime 轉換到 date。

`DateTimeField`

class django.db.models. DateTimeField ( auto_now=False, auto_now_add=False, **options )

時間和日期, 表現爲 Python 中的 datetime.datetime 實例。和 DateField 有相同的額外參數。

默認的表單部件是一個 TextInput 。admin頁面使用兩個帶有 JavaScript控件的 TextInput 。

`DecimalField`

class django.db.models. DecimalField ( max_digits=None, decimal_places=None, **options )

十進制數，表現爲Python中 Decimal 實例，有兩個必填參數:

DecimalField. max_digits: 容許的最大位數包括小數點後的位數。必須大於等於 decimal_places。

DecimalField. decimal_places: 小數點後的位數。

舉個例子，要儲存最大爲 999 帶有兩位小數的數字，須要這樣設置:

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

而要存儲那些將近10億，而且要求達到小數點後十位精度的數字:

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

該字段默認的表單部件是 NumberInput ，若是 localize 設置爲 False 則是 TextInput 。

註解

關於更多 FloatField 和 DecimalField 的區別信息，請參考 FloatField vs. DecimalField 。

`DurationField`

class django.db.models. DurationField ( **options )

用做存儲一段時間的字段類型 - 相似Python中的 timedelta 。.當數據庫使用的是 PostgreSQL, 該數據類型使用的是一個 interval ，而在Oracle上，則使用的是 INTERVAL DAY(9) TO SECOND(6) 。其餘狀況使用微秒的的 bigint 。

註解

DurationField 的算數運算在多數狀況下能夠很好的工做。然而，在除了 PostgreSQL以外的其餘數據庫中, 將 DurationField 和 DateTimeField 的實例比較則不會獲得正確的結果。

`EmailField`

class django.db.models. EmailField ( max_length=254, **options )

一個檢查輸入的email地址是否合法的 CharField 類型。它使用 EmailValidator 來驗證輸入合法性。

`FileField`

class django.db.models. FileField ( upload_to=None, max_length=100, **options )

上傳文件字段。

註解

primary_key 和 unique 在這個字段中不支持, 若是使用在拋出 TypeError 異常。

擁有兩個可選參數:

FileField. 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 風格的路徑（帶有前向/）給存儲系統。將傳遞的兩個參數爲:

Argument Description

Argument	Description
`instance`	定義 `FileField` 的模型的實例更準確地說，就是當前文件的所在的那個實例。大部分狀況下，這個實例將尚未保存到數據庫中，若它用到默認的 `AutoField` 字段，它的主鍵字段還可能沒有值。
`filename`	最初給文件的文件名。在肯定最終目標路徑時，可能不會考慮到這一點。

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)

FileField. storage: 一個Storage 對象，用於你的文件的存取。參見 Managing files 查看如何提供這個對象的細節。

這個字段的默認表單部件是一個 ClearableFileInput 。

在模式中使用 FileField 類型或 ImageField (見下文) 須要以下幾步:

在 settings 文件中, 將Django儲存文件的的完整路徑設置到 MEDIA_ROOT 項。 (從性能上考慮，不要將這些文件存在數據庫中) 定義一個 MEDIA_URL 做爲基礎目錄的URL。確保web server帳戶對這個目錄有讀寫權限。
添加 FileField 或者 ImageField 到模型中, 定義屬性 upload_to 用來存放上傳的文件，應該是MEDIA_ROOT 的子目錄。
數據庫中存放的僅是這個文件的路徑 (相對於 MEDIA_ROOT)。而後使用 url 屬性來獲取。例如, 一個叫作 mug_shot 的 ImageField 字段，可使用 {{ object.mug_shot.url }} 來獲取它的絕對路徑。

假如, 你將 MEDIA_ROOT 設置爲 '/home/media', upload_to 屬性設置爲 'photos/%Y/%m/%d' 。 upload_to的 '%Y/%m/%d' 部分是 strftime() 的格式化字符。 '%Y' 表示四位數的年份, '%m' 表示兩位數的月份， '%d' 表示兩位數的日份。若是文件上傳時間是 Jan. 15, 2007,將被存到目錄 /home/media/photos/2007/01/15 。

若是想要知道上傳文件的磁盤文件名或文件大小，可使用 name 和 size 屬性獲得；關於更多支持的方法和屬性。請參考 File 的參考文檔 Managing files 。

註解

文件做爲模型存儲在數據庫中的一部分，磁盤上文件名在模型保存完畢以前是不可靠的。

上傳的文件對應的URL能夠經過使用 url 屬性得到. 其實在內部，是調用 Storage 類的 url() 方法。

值得注意的是，不管任什麼時候候處理上傳文件時，都應該密切關注文件將被上傳到哪裏，上傳的文件類型，以免安全漏洞。 檢查全部上傳文件 確保上傳的文件是被容許的文件。例如，若是你盲目的容許其餘人在無需認證的狀況下上傳文件至你的web服務器的root目錄中，那麼別人能夠上傳一個CGI或者PHP腳本而後經過訪問一個你網站的URL來執行這個腳本。因此，不要容許這種事情發生。

甚至是上傳HTML文件也須要注意，它能夠經過瀏覽器（雖然不是服務器）執行，也能夠引起至關因而XSS或者CSRF攻擊的安全威脅。

FileField 對象在數據庫中以最大長度100個字節的 varchar 類型存在。和普通字段同樣。也可使用 max_length 參數限制。

`FileField` 和 `FieldFile`

class django.db.models.fields.files. FieldFile

當添加一個 FileField 字段到模型中時，其實是一個 FieldFile 實例做爲將要訪問文件的代理。

The API of FieldFile mirrors that of File, with one key difference: The object wrapped by the class is not necessarily a wrapper around Python’s built-in file object. Instead, it is a wrapper around the result of the Storage.open() method, which may be a File object, or it may be a custom storage’s implementation of the File API.

In addition to the API inherited from File such as read() and write(), FieldFile includes several methods that can be used to interact with the underlying file:

警告

Two methods of this class, save() and delete(), default to saving the model object of the associated FieldFile in the database.

FieldFile. name

文件的名稱，Storage 的根路徑， FileField 的相對路徑。

FieldFile. size

下面 Storage.size() 方法的返回結果。

FieldFile. url

經過下面 Storage 類的 url() 方法只讀地訪問文件的URL。

FieldFile. open ( mode='rb' )

在指定模式下打開或重寫與該實例相關聯的文件，和Python的標準 open() 方法不一樣的是，它不返回文件描述符。

因爲底層文件在訪問它時隱式地打開，所以調用此方法可能沒有必要，除非將指針重置到底層文件或更改模式。

FieldFile. close ( )

相似Python的 file.close() 方法，關閉相關文件。

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

這個方法會將文件名以及文件內容傳遞到字段的storage類中,並將模型字段與保存好的文件關聯。 I 若是想要手動關聯文件數據到你的模型中的 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")

其餘更多信息, 參見 Managing files.

FieldFile. delete ( save=True )

刪除與此實例關聯的文件，並清除該字段的全部屬性。注意:若是在調用 delete() 時有打開操做，該方法將關閉該文件。

save 控制模型實例在關聯的文件被修改時是否保存，默認爲 True 。

注意，model刪除的時候，與之關聯的文件並不會被刪除。若是你要把文件也清理掉，你須要本身處理

`FilePathField`

class django.db.models. FilePathField ( path=None, match=None, recursive=False, max_length=100, **options )

一個 CharField 內容只限於文件系統內特定目錄下的文件名，有幾個特殊參數, 其中第一個是 必須的:

FilePathField. path: 必傳。 FilePathField 應該獲得的選擇目錄的絕對文件系統路徑。例如: "/home/images".

FilePathField. match: 可選。一個字符串形式的正則表達式。FilePathField 使用其過濾文件名。 regex將應用於基本文件名，而不是所有路徑。例如："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 由於 match 只做用於基本文件名 (foo.png 和 bar.png)。

FilePathField 再數據庫中以 varchar 類型存在默認最大長度爲 100 個字節。和普通一段同樣，可使用 max_length 參數修改長度限制。

`FloatField`

class django.db.models. FloatField ( **options )

用Python的一個 float 實例來表示一個浮點數。

若是屬性 localize 爲 False 則默認表單部件是一個 NumberInput ，不然是一個 TextInput 。

FloatField vs. DecimalField

有時候 FloatField 類可能會和 DecimalField 類產生混淆。雖然它們表示都表示實數，可是兩者表示數字的方式不同。 FloatField 使用Python內部的 float 類型，而 DecimalField 使用的是Python的 Decimal 類型。想要了解更多兩者的差異, 能夠查看Python文檔中的 decimal 模塊。

`ImageField`

class django.db.models. ImageField ( upload_to=None, height_field=None, width_field=None, max_length=100, **options )

繼承了:class:FileField 類的全部方法和屬性，並且還對上傳的對象進行校驗，確保它是個有效的image。

除了從 FileField 繼承的屬性外， ImageField 類還增長了 height 和 width 屬性。

爲了更便捷的去用這些屬性值, ImageField 有兩個額外的可選參數:

ImageField. height_field: 該屬性的設定會在模型實例保存時,自動填充圖片的高度。

ImageField. width_field: 該屬性的設定會在模型實例保存時,自動填充圖片的寬度。

ImageField須要 Pillow 庫支持。

ImageField 實例在數據庫中以 varchar 類型存在，默認最大長度爲100個字節，和普通字段同樣。也可使用 max_length 參數限制。

該字段默認的表單部件是一個 ClearableFileInput 。

`IntegerField`

class django.db.models. IntegerField ( **options )

一個整數。在Django全部支持的數據庫中，-2147483648 到 2147483647 範圍纔是合法的。若是設置了 localize 爲 False ,那麼默認表單部件將是一個 NumberInput 不然是一個 TextInput 。

`GenericIPAddressField`

class django.db.models. GenericIPAddressField ( protocol='both', unpack_ipv4=False, **options )

一條IPv4或IPv6地址, 字符串格式是 (e.g. 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' 時纔可使用。

若是容許空值，則必須容許null值，由於空值存儲爲null。

`NullBooleanField`

class django.db.models. NullBooleanField ( **options )

相似 BooleanField, 可是它容許 NULL 值。能夠用它來代替 BooleanField 字段設置 null=True 的狀況。它的默認表單是 NullBooleanSelect 。

`PositiveIntegerField`

class django.db.models. PositiveIntegerField ( **options )

相似 IntegerField 類型, 但必須是整數或者零 (0)。取值範圍是 0 到 2147483647 。容許 0 是爲了向後兼容。

`PositiveSmallIntegerField`

class django.db.models. PositiveSmallIntegerField ( **options )

相似 PositiveIntegerField 類型，但其容許的值必須小於某個特定值 (有數據庫決定)。在Django所支持的數據庫中 0 到 32767 內的值是絕對容許的。

`SlugField`

class django.db.models. SlugField ( max_length=50, **options )

Slug 是一個新聞術語，一般叫作短標題。slug只能包含字母、數字、下劃線或者是連字符。一般它們是用來放在URL裏的。

相似 CharField 類型，能夠指定 max_length (請參閱該部分中的有關數據庫可移植性的說明和max_length ) 若是沒有指定 max_length 屬性，將默認使用50。

同時 Field.db_index 設置爲 True 。

比較可行的作法是根據其餘值的內容自動預填 SlugField 的值。在admin中可使用prepopulated_fields 來實現。

SlugField. allow_unicode: 若是設置爲 True, 該字段除了ASCII以外，還接受Unicode字母。默認爲 False.

`SmallIntegerField`

class django.db.models. SmallIntegerField ( **options )

相似 IntegerField, 但只容許某些特定的值 (數據庫決定)。在Django所支持的數據庫中 -32768 到 32767 以前是絕對容許的。

`TextField`

class django.db.models. TextField ( **options )

大文本字段。默認的表單部件是一個 Textarea 。

若是指定了 max_length 屬性, 它將會在渲染頁面時表單部件 Textarea 中體現出來，可是卻不會在模型和數據庫中有這個限制。若是須要這樣清使用 CharField 類型。

MySQL 用戶

若是在 MySQLdb 1.2.1p2 中使用該字段，而且是 utf8_bin 排序規則(默認*不是* 這個) 則須要注意幾個問題。參考 MySQL database notes 。

`TimeField`

class django.db.models. TimeField ( auto_now=False, auto_now_add=False, **options )

時間字段, 相似於Python datetime.time 實例. 和 DateField 具備相同的選項.

默認的表單部件是一個 TextInput. 在Admin中添加了一些JavaScript快捷方式。

`URLField`

class django.db.models. URLField ( max_length=200, **options )

一個 CharField 類型的URL.

默認的表單部件是一個 TextInput.

與全部 CharField 子類同樣, URLField 接受 max_length 可選參數. 若是沒有特別指定 max_length 默認長度是200.

`UUIDField`

class django.db.models. UUIDField ( **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

注意傳入的是一個可調用的對象(即一個省略括號的方法) 而不是傳入一個 UUID 實例給 default .

關係字段

Django 一樣定義了一系列的字段來描述數據庫之間的關聯.

`ForeignKey`

class django.db.models. ForeignKey ( othermodel, on_delete, **options )

多對一關係. 須要一個位置參數: 與該模型關聯的類.

on_delete 如今能夠用做第二個位置參數(以前它一般只是做爲一個關鍵字參數傳遞). 在Django 2.0中，這將是一個必傳的參數。

若要建立一個遞歸的關聯 —— 對象與本身具備多對一的關係 —— 請使用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

production/models.py

from django.db import models
from products.models import AbstractCar

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

# Car.manufacturer will point to `production.Manufacturer` here.

若要引用在其它應用中定義的模型，必須使用帶有完整標籤名的模型來顯式指定。例如，若是上面提到的 Manufacturer 模型是在一個名爲 production 的應用中定義的，就應該這樣使用它:

class Car(models.Model):
    manufacturer = models.ForeignKey(
        'production.Manufacturer',
        on_delete=models.CASCADE,
    )

當兩個應用有相互導入狀況時，這種引用將會頗有幫助。

ForeignKey 會自動建立數據庫索引。若是你建立外鍵是爲了一致性而不是用來Join，或者若是你將建立其它索引例如部分或多列索引，也許想要避免索引的開銷。這時能夠經過設置 db_index 爲 False 來取消。

數據庫中表示

在背後，Django 會在字段名上添加 "_id" 來建立數據庫中的列名。在上面的例子中，Car 模型的數據庫表將會擁有一個 manufacturer_id 列。（也能夠顯式指定 db_column ）。可是，你的代碼永遠不該該處理數據庫中的列名稱，除非你須要編寫自定義的SQL。你應該只關注你的模型對象中的字段名稱。

參數

ForeignKey 接受一系列可選參數來標識關聯關係的具體細節。

ForeignKey. on_delete

當一個 ForeignKey 引用的對象被刪除時, django將模擬 on_delete 參數指定的SQL約束行爲。舉個例子, 若是你有一個能夠爲空的 ForeignKey ，在其引用的對象被刪除的時你想把這個 ForeignKey 設置爲空. 能夠這樣:

user = models.ForeignKey( User, models.SET_NULL, blank=True, null=True, )

1.9 版後已移除: on_delete 在Django 2.0 將成爲一個必需的參數。在舊版本默值認爲 CASCADE.

on_delete 在 django.db.models 中可選的值有:

django.db.models. CASCADE

級聯刪除。Django模擬了SQL約束在DELETE CASCADE上的行爲，並刪除ForeignKey的對象。
django.db.models. PROTECT

拋出 ProtectedError 異常以阻止被引用對象的刪除, 它是 django.db.IntegrityError 的一個子類.
django.db.models. SET_NULL

從新設置 ForeignKey 爲null; 僅在 null 設置 True 時才能使用.
django.db.models. SET_DEFAULT

將 ForeignKey 設置爲默認值; 這時必須設置 ForeignKey 的默認值參數.

django.db.models. SET ( )

設置 ForeignKey 爲 SET() 的接收值, 若是傳遞的是一個可調用對象，則爲調用後的結果。在大部分情形下，傳遞一個可調用對象用於避免 models.py 在導入時執行查詢:

from django.conf import settings
from django.contrib.auth import get_user_model
from django.db import models

def get_sentinel_user():
    return get_user_model().objects.get_or_create(username='deleted')[0]

class MyModel(models.Model):
    user = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.SET(get_sentinel_user),
    )

django.db.models. DO_NOTHING

不作任何動做. 若是刪除關聯數據時, 除非手動添加 ON DELETE 約束, 不然會引起 IntegrityError 異常.

ForeignKey. limit_choices_to

當這個字段使用 ModelForm 或者Admin 渲染時（默認狀況下，查詢集中的全部對象均可以使用）, 爲這個字段設置一個可用的選項。它能夠是一個字典、一個 Q 對象或者一個返回字典或 Q 的可調用對象.

例如:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={'is_staff': True},
)

這樣使在 ModelForm 對應的字段只列出 Users 的 is_staff=True. 這在Django 的Admin 中也可能有用處。

使用可調用對象的形式一樣很是有用，好比和Python的 datetime 模塊一塊兒使用來限制選擇的時間範圍. 例如:

def limit_pub_date_choices():
    return {'pub_date__lte': datetime.date.utcnow()}

limit_choices_to = limit_pub_date_choices

若是 limit_choices_to 自己或者返回的是一個 Q object 對象, 這對複合查詢頗有用. 當字段沒有在模型的 ModelAdmin 中的 raw_id_fields 中列出時, 它將只會影響Admin中的選項.

註解

若是 limit_choices_to 是可調用對象, 那麼這個對象將在每次建立新表單實例的時候調用. 它也可能在模型校驗的時候調用, 例如被management命令或者Admin檢驗. Admin會屢次構造查詢集來驗證表單在各類邊緣狀況下的輸入, 因此這個可調用對象可能會被調用屢次.

ForeignKey. related_name

這個名稱用於使關聯的對象反查到源對象. 它仍是 related_query_name 的默認值（關聯的模型進行反向過濾時使用的名稱）. 完整的解釋和示例參見關聯對象文檔 . 請注意，在抽象模型定義關係時，必須設置此值；當您這樣作時, 可使用一些特殊語法 .

若是你不想讓Django建立反向關聯, 能夠設置 related_name 爲 '+' 或者以 '+' 結尾. 例如, 下面這行將確保 User 模型將不會有到這個模型的反向關聯:

user = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name='+',
)

ForeignKey. related_query_name

這個名稱用於目標模型的反向過濾. 若是設置了 related_name 或者 default_related_name, 將用它們做爲默認值. 不然默認值就是模型的名稱:

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)

# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")

Like related_name, related_query_name supports app label and class interpolation via . 像 related_name 同樣, related_query_name 能夠經過一些特殊語法來支持應用標籤和類插值.

ForeignKey. to_field: 關聯到的關聯對象的字段名稱. 默認狀況下, Django 使用關聯對象的主鍵. 若是引用其餘字段, 該字段必須具備 unique=True.

ForeignKey. db_constraint

決定是否在數據庫中爲這個外鍵建立約束. 默認值爲 True, 這個符合大多數場景; 將此設置爲 False 會對數據完整性很是不利. 即使如此，有一些場景你也許須要這麼設置：

有遺留的無效數據.
正在對數據庫縮容.

若是設置成 False``時，訪問一個不存在的關聯對象將拋出 ``DoesNotExist 異常.

ForeignKey. swappable

若是該 ForeignKey 指向一個可切換swappable的模型, 該屬性將決定遷移框架的行爲. 若是設置爲 True -默認值- ，那麼若是 ForeignKey 指向的模型與 settings.AUTH_USER_MODEL 匹配（或其它可切換的模型），該關聯關係會被保存在遷移migration中，且使用的是對setting 中引用而不是直接對模型的引用。

只有當你的模型想永遠指向切換後的模型 —— 例如若是它是專門爲你的自定義用戶模型設計的模型時，這時就能夠將它設置成 False.

設置爲 False 並不表示你能夠引用可切換的模型,即便在它被切換出去以後 —— False 只是表示生成的遷移中ForeignKey 將始終引用你指定的準確模型（因此，若是用戶試圖容許一個你不支持的User 模型時將會失敗）。

若是對此有疑問，請保留它的默認值 True.

`ManyToManyField`

class django.db.models. ManyToManyField ( othermodel, **options )

一個多對多關聯關係. 必須傳入一個關鍵字參數：與該模型關聯的類，它與 ForeignKey 的徹底同樣，包括 recursive 和 lazy 關係類型.

能夠經過字段的 RelatedManager 進行關聯對象的添加/刪除和建立.

數據庫表示

在數據庫層, Django 經過建立一箇中間表來表示多對多關係. 默認狀況下, 這張中間表的名稱是由使用多對多字段的名稱和包含這張表的模型的名稱組合產生. 因爲某些數據庫表名字支持的長度有限, 這種狀況下, 表的名稱將自動截短到64個字符並加上一個惟一哈希值. 這意味着你可能會看到像 author_books_9cdf4 這樣的表名；這是沒有問題的. 你可使用 db_table 選項手動提供中間表的名稱.

參數

ManyToManyField 接收一個參數集來控制關聯關係功能 – 全部選項 – 都是可選的.

ManyToManyField. related_name: 和 ForeignKey.related_name 相同.

ManyToManyField. related_query_name: 和 ForeignKey.related_query_name 相同.

ManyToManyField. limit_choices_to

和 ForeignKey.limit_choices_to 相同.

若是 ManyToManyField 使用 through 自定義中間表時, limit_choices_to 無效.

ManyToManyField. symmetrical

只用於與自身進行關聯的ManyToManyField. 例以下面的模型:

from django.db import models

class Person(models.Model):
    friends = models.ManyToManyField("self")

當Django 處理這個模型的時候, 它定義了該模型具備一個與自身具備多對多關聯的 ManyToManyField. 所以它不會向 Person 類添加 person_set 屬性. Django會假定這個 ManyToManyField 字段是對稱的 —— 即, 若是我是你的朋友，那麼你也是個人朋友.

若是你但願與 self 進行多對多關聯的關係是非對稱的，能夠設置 symmetrical 爲 False. 這會強制讓Django給反向的關聯關係添加一個描述器, 以使得 ManyToManyField 的關聯關係不是對稱的.

ManyToManyField. through

Django會自動建立一個表來管理多對多關係. 不過, 若是你但願手動指定這個中間表, 可使用through 選項來告訴Django模型你想使用的中間表.

這個選項最多見的使用場景是用來關聯更多的數據.

若是沒有顯式指定 through 的模型, 仍然會有一個隱式的 through 模型類，你能夠用它來直接訪問對應的表示關聯關係的數據表. 它由三個字段來鏈接模型。

若是源模型和目標模型不相同, 則生成如下字段:

id: 關係的主鍵.
<containing_model>_id: 聲明 ManyToManyField 的模型的 id.
<other_model>_id: 被 ManyToManyField 選項指向的模型的 id.

若是 ManyToManyField 選項的源模型和目標模型是同一個, 則生成如下字段:

id: 關係的主鍵.
from_<model>_id: 源模型實例的 id.
to_<model>_id: 目標模型實例的 id.

這個類可讓一個給定的模型像普通的模型那樣查詢與之相關聯的記錄。

ManyToManyField. through_fields

只能在自定義中間模型的時候使用. 一般狀況下Django會自行決定使用中間模型的哪些字段來創建多對多關聯. 可是，在以下模型中:

from django.db import models

class Person(models.Model):
    name = models.CharField(max_length=50)

class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(
        Person,
        through='Membership',
        through_fields=('group', 'person'),
    )

class Membership(models.Model):
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

Membership 有兩個到 Person 到外鍵(person 和 inviter), 這樣會致使關係不清晰, Django不知道使用哪個外鍵。在這種狀況下, 必須使用 through_fields 明確指定Django應該使用哪些外鍵，就像上面例子同樣.

through_fields 接受一個二元元組 ('field1', 'field2'), 其中 field1 是指向定義了 ManyToManyField 的模型的外鍵名字(本例中是 group), field2 就是目標模型的外鍵的名 (本例中是 person).

當中間模型具備多個外鍵指向多對多關聯關係模型中的任何一個（或兩個）時, 就必須指定 through_fields. 當用到中間模型有多個外鍵指向該模型時，而你想顯式指定Django應該用到的兩個字段, 這一樣適用於遞歸關聯關係.

遞歸的關聯關係使用的中間模型始終定義爲非對稱的 – 也就是 symmetrical=False – 因此具備源和目標的概念. 這種狀況下，'field1' 將做爲關係的源，而 'field2' 做爲目標.

ManyToManyField. db_table: 用於存儲多對多關係數據而建立的表的名稱. 若是沒有設置, Django將基於定義關聯關係的模型和字段設置一個默認名稱.

ManyToManyField. db_constraint

決定是否爲中間表中的外鍵建立約束. 默認值 True，這適合大多數場景；如將此設置爲 False可能對數據完整性很是友好. 即使如此，有一些場景也許須要這麼設置：

存在遺留的無效數據.
正要對數據庫縮容.

不能夠同時設置 db_constraint 和 through.

ManyToManyField. swappable

若是該 ManyToManyField 指向一個可切換swappable的模型, 該屬性將決定遷移框架的行爲. 若是設置爲 True, -默認值- ，那麼若是 ManyToManyField 指向的模型與 settings.AUTH_USER_MODEL 匹配（或其它可切換的模型）, 該關聯關係會被保存在遷移migration中，且使用的是對setting 中引用而不是直接對模型的引用.

若是對此有疑問，請保留它的默認值 True.

ManyToManyField 不支持 validators.

null 不起任何做用，由於在數據庫層不須要關係.

`OneToOneField`

class django.db.models. OneToOneField ( othermodel, on_delete, parent_link=False, **options )

一對一關聯關係. 在概念上, 它相似於設置了 unique=True 的 ForeignKey, 可是，一對一關係的「reverse」部分將直接返回單個對象.

on_delete 如今能夠用做第二個位置參數 (之前它一般只做爲關鍵字參數傳遞).: 在Django 2.0中，這將是一個必傳的參數.

這是最有效的一種方式,即做爲一個模型的主鍵,在某種程度上又「擴展」了另外一個模型; 例如，多表繼承就是經過將一個隱式一對一關係從子模型添加到父模型來實現的.

須要一個位置參數：與該模型關聯的類. 它的工做方式與 ForeignKey 徹底一致, 包括全部與 recursive 和 lazy 相關的選項.

若是沒有指定 OneToOneField 的 related_name 參數，Django將使用當前模型的小寫的名稱做爲默認值.

例以下面例子:

from django.conf import settings
from django.db import models

class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='supervisor_of',
    )

這將使 User 模型具備如下屬性:

>>> user = User.objects.get(pk=1)
>>> hasattr(user, 'myspecialuser')
True
>>> hasattr(user, 'supervisor_of')
True

反向訪問關聯關係時, 若是關聯的對象不存在對應的實例, 將拋出 DoesNotExist 異常. 例如, 若是一個 User 沒有 MySpecialUser 指定的supervisor:

>>> user.supervisor_of
Traceback (most recent call last):
    ...
DoesNotExist: User matching query does not exist.

除此以外, OneToOneField 除了接收 ForeignKey 接收的全部額外的參數以外, 還有另一個參數:

OneToOneField. parent_link: 當它爲 True 並在繼承自另外一個 concrete model 的模型中使用時，表示該字段應該用於反查的父類的連接，而不是在子類化時隱式建立的 OneToOneField.

OneToOneField 的使用示例參見 One-to-one關聯關係.

Field API參考

class django.db.models. Field

Field 是一個抽象的類, 用來表示數據庫中的表的列.

Django使用字段建立數據庫表(db_type()), 將Python類型映射到數據庫(get_prep_value()), 反之亦然(from_db_value()).

在各個版本的Django API中field是最根本的部分, 尤爲是 models 和 querysets.

在模型中, 字段被實例化爲類的屬性, 並表現爲一個特定的表的列，詳情參考模型. 它具備許多屬性，如 null 和 unique 等, 以及用於將字段值映射到數據庫特定值的方法.

Field 是 RegisterLookupMixin 的子類，所以能夠在其上註冊 Transform 和 Lookup，也就能夠在 QuerySet 中使用(例如 field_name__="foo"). 全部內置查詢都是默認註冊好的.

Django的全部內建字段，如 CharField 都是 Field 的特殊實現. 若是須要自定義字段，則能夠將任何內置字段重載，也能夠重寫一個新的 Field. 不管哪一種狀況，請參考 Writing custom model fields.

description

字段的詳細描述，例如用於 django.contrib.admindocs 應用程序.

描述能夠是如下形式:

description = _("String (up to %(max_length)s)")

其中參數從字段的 __dict__ 去獲取.

爲了將 Field 映射到數據庫特定類型，Django開放了幾種方法:

get_internal_type ( )

返回一個命名此字段的字符串用於後端特定用途. 默認狀況下, 它返回類名.

有關自定義字段中的用法，請參見 Emulating built-in field types.

db_type ( connection )

返回 Field 的數據庫列數據類型，同時考慮 connection.

有關自定義字段中使用 Custom database types.

rel_db_type ( connection )

返回指向 Field 的字段的數據庫列數據類型，例如 ForeignKey 和 OneToOneField, 並考慮 connection.

有關自定義字段中使用 Custom database types.

有三種主要狀況，Django須要與數據庫後端和字段交互:

當它查詢數據庫 (Python value -> database backend value)
當它從數據庫加載數據 (database backend value -> Python value)
當它保存到數據庫 (Python value -> database backend value)

查詢時, get_db_prep_value() 和 get_prep_value() 將被用到:

get_prep_value ( value )

value 是模型屬性的當前值, 該方法應返回用做查詢的參數的格式數據.

有關使用方法，請參閱 Converting Python objects to query values.

get_db_prep_value ( value, connection, prepared=False )

將 value 轉換爲特定後端值. 若是設置 prepared=True，則默認返回 value. 若是爲 False 則返回 get_prep_value().

有關使用方法，請參閱 Converting query values to database values.

加載數據時 from_db_value() 將被使用:

from_db_value ( value, expression, connection, context )

將數據庫返回的值轉換爲Python對象. 它與 get_prep_value() 相反.

此方法不使用於大多數內置字段, 由於這些字段在數據庫後端已返回正確的Python類型，或後端自己執行轉換.

有關使用方法，請參閱 Converting values to Python objects.

註解

出於性能緣由，from_db_value 沒有在不須要它的字段上實現(全部Django字段). 所以，您不能在定義中調用 super.

保存數據時, pre_save() 和 get_db_prep_save() 將被使用:

get_db_prep_save ( value, connection ): 相似於 get_db_prep_value(), 但僅僅在字段值必定會保存到數據庫時調用. 默認返回get_db_prep_value().

pre_save ( model_instance, add )

在 get_db_prep_save() 以前調用, 以在保存以前準備好值. (e.g. for DateField.auto_now).

model_instance 是該字段所屬的實例， add 是首次將實例保存到數據庫.

它會返回此字段的 model_instance 適當屬性的值. 屬性名稱位於 self.attname (這個由 Field設置)

有關使用方法，請參閱 Preprocessing values before saving.

字段一般以不一樣的類型接收它們的值，不管是序列化仍是表單.

to_python ( value )

將value值轉換爲正確的python對象. 它做爲 value_to_string() 的反向操做，也是在 clean()中調用.

有關使用方法，請參閱 Converting values to Python objects.

除了保存到數據庫，字段還須要知道如何序列化值:

value_to_string ( obj )

將 obj 轉換成字符串. 用於序列化字段的值.

有關使用方法，請參閱 Converting field data for serialization.

使用 model forms 時, Field 須要知道應由哪一個表單字段表示:

formfield ( form_class=None, choices_form_class=None, **kwargs )

返回 ModelForm 該字段的默認 django.forms.Field.

默認狀況下, 若是 form_class 和 choices_form_class 都是 None, 則使用 CharField. 若是字段沒有指定 choices 和 choices_form_class, 則使用 TypedChoiceField.

有關用法, 參見 Specifying the form field for a model field.

deconstruct ( )

返回足夠多信息的4元元祖, 用來從新建立字段:

模型中的字段名稱.
字段的導入路徑 (e.g. "django.db.models.IntegerField").

這最好是可以兼容的版本，因此不要太具體更好.
位置參數列表.
關鍵詞參數列表.

必須將此方法添加到1.7以前的字段, 才能使用 Migrations 遷移其數據.

字段屬性參考

每一個 Field 實例包含幾個容許內省其行爲的屬性. 當須要編寫依賴於字段功能的代碼時，就可使用這些屬性而不是 isinstance 檢查. 這些屬性能夠與 Model._meta API 一塊兒使用, 縮小搜索特定字段類型的範圍.自定義模型字段應實現這些標誌.

字段屬性

Field. auto_created: 布爾標誌, 指示是否自動建立字段, 例如模型繼承使用的 OneToOneField.

Field. concrete: 布爾標誌, 指示字段是否具備與其相關聯的數據庫列.

Field. hidden: 布爾標誌, 指示字段是否用於支持另外一個非隱藏字段的功能. (e.g. content_type 和 object_id 構成了字段 GenericForeignKey). hidden 標誌用於區分模型上的公共字段子集構成模型上的全部字段.

註解

Options.get_fields() 默認不返回隱藏字段. 能夠經過設置 include_hidden=True 返回隱藏字段.

Field. is_relation: 布爾標誌，表示字段是否包含對一個或多個其餘模型的引用. (e.g. ForeignKey, ManyToManyField, OneToOneField, etc.).

Field. model: 返回定義字段的模型。若是在模型的超類上定義了一個字段，model 將引用父類，而不是實例的類.

關係字段屬性

這些屬性用於查詢關係的基數和其餘詳細信息. 這些屬性存在於全部字段中; 可是, 若是該字段是關係類型 ( Field.is_relation=True) 它們將只有布爾值 (而不是 None).

Field. many_to_many: 布爾標誌, 若是該字段具備多對多關係，則爲 True; 不然 False. Django中只有 ManyToManyField爲 True.

Field. many_to_one: 布爾標誌, 若是字段具備多對一關聯關係則爲 True. 好比 ForeignKey; 其餘爲 False.

Field. one_to_many: 布爾標誌, 若是字段具備一對多關聯關係則爲 True . 好比 GenericRelation 或者反向 ForeignKey; 其餘狀況爲 False.

Field. one_to_one: 布爾標誌, 若是字段具備一對一關聯關係則爲 True .好比 OneToOneField; 其餘狀況爲 False.

Field. related_model: 指向字段關聯的模型. 例如, ForeignKey(Author, on_delete=models.CASCADE) 中的 Author .GenericForeignKey 中的 related_model 始終爲 None.

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。

Django 1.10中文文檔-模型參考

模型字段

字段選項

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

註冊和查詢

字段類型

AutoField

BigAutoField

BigIntegerField

BinaryField

BooleanField

CharField

CommaSeparatedIntegerField

DateField

DateTimeField

DecimalField

DurationField

EmailField

FileField

FileField 和 FieldFile

FilePathField

FloatField

ImageField

IntegerField

GenericIPAddressField

NullBooleanField

PositiveIntegerField

PositiveSmallIntegerField

SlugField

SmallIntegerField

TextField

TimeField

URLField

UUIDField