Django 模型字段参考

更多请查看原文：Django 1.8.2 文档

字段选项(Field options)

下列参数是全部字段类型都可用的，而且都是可选择的。

null

Field.null
如果为True，Django 将空值以NULL 存储到数据库中。默认值是 False。

字符串字段例如CharField 和TextField 要避免使用null，因为空字符串值将始终储存为空字符串而不是NULL。如果字符串字段的null=True，那意味着对于“无数据”有两个可能的值：NULL 和空字符串。在大多数情况下，对于“无数据”声明两个值是赘余的，Django 的惯例是使用空字符串而不是NULL。

无论是字符串字段还是非字符串字段，如果你希望在表单中允许空值，你将还需要设置blank=True，因为null 仅仅影响数据库存储（参见blank）。

注意

在使用Oracle 数据库时，数据库将存储NULL 来表示空字符串，而与这个属性无关。

如果你希望BooleanField 接受null 值，请用 NullBooleanField 代替。

blank

Field.blank
如果为True，则该字段允许为空白。 默认值是 False。

注意它与null不同。null 纯粹是数据库范畴的概念，而blank 是数据验证范畴的。如果字段设置blank=True，表单验证时将允许输入空值。如果字段设置blank=False，则该字段为必填。

choices

Field.choices
它是一个可迭代的结构(比如，列表或是元组)，由可迭代的二元组组成(比如[(A, B), (A, B) …])，用来给这个字段提供选择项。如果设置了 choices ，默认表格样式就会显示选择框，而不是标准的文本框，而且这个选择框的选项就是 choices 中的元组。

每个元组中的第一个元素，是存储在数据库中的值；第二个元素是该选项更易理解的描述。 比如:

YEAR_IN_SCHOOL_CHOICES = (    ('FR', 'Freshman'),    ('SO', 'Sophomore'),    ('JR', 'Junior'),    ('SR', 'Senior'),)

一般来说，最好在模型类内部定义choices，然后再给每个值定义一个合适名字的常量。

from django.db import modelsclass 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 模型的位置生效)。

你也可以归类可选的choices到已命名的组中用来达成组织整理的目的:

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

每个元组的第一个元素是组的名字。第二个元素是一组可迭代的二元元组，每一个二元元组包含一个值和一个给人看的名字构成一个选项。分组的选项可能会和未分组的选项合在同一个list中。 （就像例中的unknown选项）。

对于有choices set的模型字段, Django 将会加入一个方法来获取当前字段值的易于理解的名称(即元组的第二个值)参见数据库API文档中的get_FOO_display()。

请注意choices可以是任何可迭代的对象 – 不是必须是列表或者元组。这一点使你可以动态的构建choices。但是如果你发现你自己搞不定动态的choices，你最好还是使用ForeignKey来构建一个合适的数据库表。如果有数据变动的话，choices意味着那些变动不多的静态数据。

                New in Django 1.7.

除非blank=False 和default一起在字段中被设置，否则，可选择菜单将会有”———” 的标签。要重写这个行为, 需要加入一个包含None的元组到 choices里面; 例如 (None, ‘Your String For Display’). 或者, 你可以在操作有意义的地方用一个空字符串代替None - 比如在一个 CharField.

db_column

Field.db_column¶
数据库中用来表示该字段的名称。如果未指定，那么Django将会使用Field名作为字段名.

如果你的数据库列名为SQL语句的保留字，或者是包含不能作为Python 变量名的字符，如连字符，没问题。Django 会在后台给列名和表名加上双引号。

db_index

Field.db_index
若值为 True, 则 django-admin sqlindexes 将会为此字段输出 CREATE INDEX 语句。（译注：为此字段创建索引）

db_tablespace

Field.db_tablespace
如果该字段有索引的话，database tablespace的名称将作为该字段的索引名。 如果DEFAULT_INDEX_TABLESPACE 已经设置，则默认值是由DEFAULT_INDEX_TABLESPACE指定, 如果没有设置则由 db_tablespace 指定，如果后台数据库不支持表空间，或者索引，则该选项被忽略

default

Field.default
该字段的默认值. 它可以是一个值或者一个可调用对象. 如果是一个可调用对象，那么在每一次创建新对象的时候，它将会调用一次.

这个默认值不可以是一个可变对象（如字典，列表，等等）,因为对于所有模型的一个新的实例来说，它们指向同一个引用。或者，把他们包装为一个可调用的对象。例如，你有一个自定义的JSONField，并且想指定一个特定的字典值，可以如下使用：

def contact_default():    return {"email": "[e-mail]"}contact_info = JSONField("ContactInfo", default=contact_default)

请注意lambdas 函数不可作为如 default 这类可选参数的值.因为它们无法被 migrations命令序列化. 请参见文档其他部分。

默认值会在新实例创建并且没有给该字段提供值时使用。如果字段为主键，默认值也会在设置为None时使用。

                    Changed in Django 1.8:

之前的版本不会使用None作为主键

editable

Field.editable
如果设为False, 这个字段将不会出现在 admin 或者其他 ModelForm. 他们也会跳过 模型验证. 默认是True.

error_messages

Field.error_messages
error_messages 参数能够让你重写默认抛出的错误信息。通过指定 key 来确认你要重写的错误信息。

error_messages 的 key 值包括 null, blank, invalid, invalid_choice, unique, 和 unique_for_date. 其余的 error_messages 的 keys 是不一样的在不同的章节下 Field types 。

New in Django 1.7.

这个 unique_for_date 的 error_messages 的key 是在 1.7 中加的。

help_text¶

Field.help_text¶
额外的 ‘help’ 文本将被显示在表单控件form中。即便你的字段没有应用到一个form里面，这样的操作对文档化也很有帮助。

注意这 不 会自动添加 HTML 标签。需要你在 help_text 包含自己需要的格式。例如:

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 。更多内容 请参考 Automatic primary key fields.

primary_key=True 暗含着null=False 和unique=True. 一个对象上只能拥有一个主键.

主键字段是只读的。如果你改变了一个已存在对象上的主键并且保存的话，会创建一个新的对象，而不是覆盖旧的.

unique¶

Field.unique¶
如果为 True, 这个字段在表中必须有唯一值.

这是一个在数据库级别的强制性动作,并且通过模型来验证。如果你试图用一个重复的值来保存unique 字段，那么一个django.db.IntegrityError就会通过模型的save() 函数抛出来。

除了ManyToManyField、OneToOneField和FileField 以外的其他字段类型都可以使用这个设置。

注意当设置unique 为True 时，你不需要再指定 db_index，因为unique 本身就意味着一个索引的创建。

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¶
一个字段的可读性更高的名称。如果用户没有设定冗余名称字段，Django会自动将该字段属性名中的下划线转换为空格，并用它来创建冗余名称。可以参照 Verbose field names.

validators¶

Field.validators¶
该字段将要运行的一个Validator 的列表。更多信息参见Validators 的文档。

注册和获取查询¶
Field 实现了查询注册API。该API 可以用于自定义一个字段类型的可用的查询，以及如何从一个字段获取查询。

            字段类型 （Field types）¶

自增字段

class AutoField(**options)¶
一个根据实际ID自动增长的IntegerField . 你通常不需要直接使用;如果不指定,一个主键字段将自动添加到你创建的模型中.详细查看 主键字段.

BigIntegerField

class BigIntegerField([**options])
一个64位整数, 类似于一个 IntegerField ,它的值的范围是 -9223372036854775808 到9223372036854775807之间. 这个字段默认的表单组件是一个TextInput.

BinaryField

class BinaryField([**options])
这是一个用来存储原始二进制码的Field. 只支持bytes 赋值，注意这个Field只有很有限的功能。例如，不大可能在一个BinaryField 值的数据上进行查询

Abusing BinaryField

尽管你可能想使用数据库来存储你的文件，但是99%的情况下这都是不好的设计。这个字段 不是替代static files 的合理操作.

BooleanField

class BooleanField(**options)¶
true/false 字段。

此字段的默认表单挂件是一个CheckboxInput.

如果你需要设置null 值，则使用NullBooleanField 来代替BooleanField。

如果Field.default没有指定的话， BooleanField 的默认值是 None。

CharField

class CharField(max_length=None[, **options])¶
一个用来存储从小到很大各种长度的字符串的地方

如果是巨大的文本类型, 可以用 TextField.

这个字段默认的表单样式是 TextInput.

CharField必须接收一个额外的参数:

CharField.max_length
字段的最大字符长度.max_length将在数据库层和Django表单验证中起作用, 用来限定字段的长度.

Note

如果你在写一个需要导出到多个不同数据库后端的应用，你需要注意某些后端对max_length有一些限制，查看数据库后端注意事项来获取更多的细节

MySQL的使用者们:

如果你在使用该字段的同时使用MySQLdb 1.2.2以及 utf8_bin 校对 其一般不是 默认情况), 你必须了解一些问题. 详细请参考 MySQL database notes .

CommaSeparatedIntegerField

class CommaSeparatedIntegerField(max_length=None[, **options])¶
一个逗号分隔的整数字段。像 CharField一样， 需要一个max_length 参数， 同时数据库移植时也需要注意。

DateField

class DateField([auto_now=False, auto_now_add=False, **options])¶
这是一个使用Python的datetime.date实例表示的日期. 有几个额外的设置参数:

DateField.auto_now
每次保存对象时，自动设置该字段为当前时间。用于”最后一次修改”的时间戳。注意，它总是使用当前日期；和你可以覆盖的那种默认值不一样。

DateField.auto_now_add¶
当对象第一次被创建时自动设置当前时间。用于创建时间的时间戳. 它总是使用当前日期；和你可以覆盖的那种默认值不一样。

该字段默认对应的表单控件是一个TextInput. 在管理员站点添加了一个JavaScript写的日历控件，和一个“Today”的快捷按钮.包含了一个额外的invalid_date错误消息键.

auto_now_add, auto_now, and default 这些设置是相互排斥的. 他们之间的任何组合将会发生错误的结果.

Note

在目前的实现中，设置auto_now或者auto_now_add为True将为让这个字段同时得到editable=False和blank=True这两个设置.

Note

auto_now and auto_now_add这两个设置会在对象创建或更新的时刻,总是使用default timezone(默认时区)的日期. 如果你不想这样，你可以考虑一下简单地使用你自己的默认调用或者重写save()(在save()函数里自己添加保存时间的机制.译者注)而不是使用auto_now or auto_now_add; 或者使用DateTimeField字段类来替换DateField 并且在给用户呈现时间的时候,决定如何处理从datetime到date的转换.

DateTimeField¶

class DateTimeField([auto_now=False, auto_now_add=False, **options])¶
它是通过Python datetime.datetime实例表示的日期和时间. 携带了跟DateField一样的额外参数.

该字段默认对应的表单控件是一个单个的TextInput(单文本输入框). 管理界面是使用两个带有 JavaScript控件的 TextInput 文本框.

DecimalField

class 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)

该字段默认的窗体组件是 TextInput.

Note

想获取更多关于 FloatField 和 DecimalField 差异, 请参照 FloatField vs. DecimalField

更多请查看原文：Django 1.8.2 文档