(持续更新)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 "", line 741, in source_to_code
  File "", 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: YYYY-MM-DD."
或者，您可以使用纯文本和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.