本文件包含Field的所有API參考，其中包括Django提供的Field引數及Field型別。

如果內建Field無法實現，您可以嘗試使用django-localflavor（documentation），其中包含針對特定國家和文化定製的各種程式碼段。
另外，您可以輕鬆地編寫您自己的自定義模型欄位。

Field 引數

以下引數適用於所有欄位型別，全部都是可選的。

null

Field.null
如果True,Django將以NULL的空值儲存在資料庫中。預設是False
避免在基於字串的Field上使用null，如CharField和TextField

。如果基於字串的Field含null=True屬性，那將意味著它將有兩種可能，一種為”無資料”(NULL)，另一種為”空字串”。多數情況下，這兩種”無資料”的情況是冗餘的，一般Django約定使用空字串，而不是NULL。CharField當同時配置unique=True和blank=True兩個屬性是個例外，在這個情況下，當使用空值儲存多個物件時可以使用null=True來避免唯一的約束違規。
對於基於字串/不基於字串的Field，如果您希望允許在表單Froms中含空值，則還需要同時設定blank=True，null引數僅影響資料庫儲存（請參閱blank）

當使用Oracle資料庫時,無論此屬性如何，都將儲存NULL值以表示空字串

譯者注：

class Student(models.Model):
    name = models.CharField(max_length=10, null=True)

當Field僅設定null=True屬性時，在Django後臺新增Model時name不輸入或輸入空格，將不能被儲存(因為blank屬性預設為False)，如下圖：

通過python manage.py shell進入shell命令列，如下：

> from smodel.models import Student
> student = Student()
> student.name = None
 
  # 設定為None，儲存到資料庫中name欄位為Null
> student.save()
> student.name = ' '  # 設定為空串，儲存到資料庫中name欄位為空串
> student.save()

blank

Field.blank
如果True,這個欄位將允許為空。預設是False

請注意，這不同於null。 null純粹與資料庫相關，而blank與驗證相關。 如果一個欄位有blank = True屬性，表單驗證將允許輸入一個空值。 如果一個欄位有blank = False屬性，則該欄位將是必填的。

譯者注：

class Student(models.Model):
    name = models.CharField(max_length=10, blank=True)

當Field僅設定blank=True屬性時，在Django後臺新增Model時，name不輸入或輸入空格，能被直接儲存，儲存到資料庫中為空串；若同時設定null=True,blank=True屬性，name不輸入或輸入空格，能被直接儲存，儲存到資料庫中為Null

choices

Field.choices

一個可迭代的（例如，一個列表或元組），它本身就包含兩個專案的可迭代項（例如[(A, B), (A, B) ...]）作為該欄位的選項。 如果給定了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)

儘管您可以在模型類之外定義一個選擇列表，然後引用它，但為模型類中的每個選項定義選項和名稱會將所有這些資訊與使用它的類相關聯，並使得選擇易於引用（例如，Student.SOPHOMORE可以在匯入了Student模型的任何地方使用）。
您還可以將可用選項收集到可用於組織目的的命名組中：

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

每個元組中的第一個元素是要應用於該組的名稱， 第二個元素是2元組的迭代，每個2元組包含一個值和一個可讀的名稱作為選項， 已分組選項可以與單個列表中的未分組選項組合（例如本例中的unknown選項）。
對於每個設定了choice的模型欄位，Django將會新增一個方法來去除該欄位當前值的可讀名稱。 請參閱資料庫API文件中的get_FOO_display()。
請注意，choices必須是任何可迭代物件，不一定是列表或元組， 這可以讓你動態地構建choices。 但是如果你發現你需要動態的choices，那麼你最好改換使用使用有ForeignKey的合適的資料庫表， choices意味著是不怎麼會變化的靜態資料。
除非blank = False與default一起在欄位中設定，否則選擇框將使用包含“———”的標籤進行渲染。 要覆蓋此行為，請將元組新增到包含None的choices中；例如(None, 'Your String For Display')。 或者，您可以使用一個空字串來替換None，如果這是有意義的 - 比如在CharField上。

譯者注：

class Student(models.Model):
    YEAR_IN_SCHOOL_CHOICES = (
        (None, 'Your String For Display'),
        ('FR', 'Freshman'),
        ('SO', 'Sophomore'),
        ('JR', 'Junior'),
        ('SR', 'Senior'),
    )
    name = models.CharField(max_length=10, blank=True)
    year_in_school = models.CharField(
        max_length=10, choices=YEAR_IN_SCHOOL_CHOICES, default=None)

如果下拉列表想達到不必填的效果，則新增blank = True屬性即可；如果下拉列表想達到必填、且預設不選擇任一”有意義”的選項時，可以同時設定blank = False（Django預設配置）與default屬性，choices中新增(None, 'Your String For Display')。這時候在新增Model時，下拉列表預設顯示Your String For Display，這時候如果直接儲存將會提示year_in_school必填，選擇非Your String For Display儲存，將不會出現問題。另外，如果沒有default屬性，則預設展示第一個元素（Your String For Display）。
值得強調的是：下拉列表顯示的是第二個元素，儲存到資料庫的是第一個元素。如(‘FR’, ‘Freshman’)，頁面將顯示Freshman，儲存到資料庫為FR。

db_column

Field.db_column

用於此欄位Field的資料庫列的名稱。 如果沒有給出，Django將使用該欄位的名稱。
如果您的資料庫列名是SQL保留字，或者包含Python變數名中不允許使用的字元 - 特別是連字元 - 這沒關係， Django將在後臺對列名及表名做合適的引用。

譯者注：

class Persion(models.Model):
    short-name = models.CharField(max_length=10) # 有連字元

呼叫python manage.py makemigrations報錯，如下（沒看到後臺做什麼比較好的處理）：

  File "<frozen importlib._bootstrap_external>", line 741, in source_to_code
  File "<frozen importlib._bootstrap>", line 205, in _call_with_frames_removed
  File "D:\PycharmProjects\model_study\smodel\models.py", line 25
    short-name = models.CharField(max_length=10)
    ^
SyntaxError: can't assign to operator

db_index

Field.db_index

如果True，則會為該欄位建立資料庫索引。

db_tablespace

Field.db_tablespace

如果此欄位已編入索引，則資料庫表空間的名稱會被用於此欄位索引。 預設值是專案的DEFAULT_INDEX_TABLESPACE設定（如果已設定）或模型的db_tablespace（如果有）。 如果資料庫不支援索引的表空間，則此選項將被忽略。

譯者注：
PostgreSQL,Oracle支援資料庫表空間，SQLite,MySQL不支援。

default

Field.default

欄位的預設值。 這可以是一個值或一個可呼叫的物件。 如果可呼叫，則每次建立新物件時都會被呼叫。
預設不能是可變物件（模型例項，list，set等），因為對該物件的同一例項的引用將用作所有新模型例項中的預設值。 相反，可以將所需的預設值包裝為可呼叫的物件中。 例如，如果你想為JSONField指定一個預設的dict，可以使用一個函式：

def contact_default():
    return {"email": "[email protected]"}

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

lambda不能用於像default這樣的欄位選項，因為它們不能被遷移序列化。 檢視該文件以瞭解其他警告。
對於對映到模型例項的欄位，如ForeignKey欄位，預設值應該是它們引用欄位的值（pk除非to_field設定了），而不是模型例項。
當建立新的模型例項並且未為該欄位提供值時使用預設值。 當該欄位是主鍵時，欄位設定為None時也使用預設值。

editable

Field.editable

如果False，該欄位將不會顯示在admin管理員或任何其他ModelForm中，它們在模型驗證中也會被跳過，預設是True。

error_messages

Field.error_messages

error_messages引數可以覆蓋該欄位將丟擲的預設訊息，僅需要傳入一個您所需要覆蓋的包含這些錯誤資訊的key的字典就行。
error message字典的key包括null, blank, invalid, invalid_choice, unique,和unique_for_date，Django為部分Field types中的每個欄位指定其他額外的錯誤訊息key。
這些錯誤訊息通常不會傳到表單，請檢視Considerations regarding model’s error_messages

譯者注：
error_messages一般在Form中做欄位合法性校驗時使用。

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意味著建立索引。

Changed in Django 1.11:
在舊版本中，unique = True不能用於FileField。

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_year

Field.unique_for_year

verbose_name

Field.verbose_name

為欄位命名一個可讀性比較好的名字。如果verbose_name屬性沒有指定，Django將以該欄位的屬性名稱自動的建立，若欄位中含下劃線，則轉化為空格。詳見Verbose field names。

validators

Field.validators

Registering and fetching lookups
Field implements the lookup registration API. The API can be used to customize which lookups are available for a field class, and how lookups are fetched from a field.