(持續更新)Django 2.0.5 關於Model field reference的中文官方翻譯及增加譯者注內容

原文鏈接： https://docs.djangoproject.com/en/2.0/ref/models/fields/

本文檔包含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_date類似，但僅要求該字段的月份在表中是唯一的。

---

unique_for_year

Field.unique_for_year

跟unique_for_date和unique_for_month類似。

---

verbose_name

Field.verbose_name

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

---

validators

Field.validators

校驗該字段合法性的一個列表。詳見validators documentation

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.