django1.8 model (2): Field types

此文翻译自djang1.8.2官方文档

Model field reference

这篇文档包含了django提供的字段的options和types的所有的API.

See also
如果内置的字段不能满足需求,你可以试试django-localflavor,它包含了用于特定的国家或文化的各种各样的代码.或者你可以很容易的定制你自己的模型字段.

Note
严格来说,这些模型应该在django.db.models.fields里定义,但是为了方便,他们导入到了django.db.models;标准用法是使用from django.db import models,这样使用字段,models.Field.

Field options

下面的参数所有字段类型都可用,都是可选的.

null

Field.null
如果是True,django会把空值作为NULL存储在数据库里.默认是False.
避免在字符类型的字段(例如CharField,TextField)上使用null,因为如果null=True,空字符串仍然作为空字符串存储,这就是说”没有数据”有2个可能的值:NULL和空字符串.大多数情况下,”没有数据”有2个可能的值是多余的;django的惯例是是哦用空字符串,而不是NULL.
对于字符类型字段和非字符类型字段,如果你希望允许表单提交空值,就应该设置blank=True,因为null参数值作用于数据库存储.

Note
When using the Oracle database backend, the value NULL will be stored to denote the empty string regardless of this attribute.

如果你希望BooleanField能接受null值,请使用NullBooleanField.

blank

Field.blank
如果是True,字段允许是空.默认是False.
注意blank和null不同.null是用于数据库,但blank是用于验证.如果一个字段blank=True,表单验证则允许输入空字符.如果blank=False,字段是必填的.

choices

Field.choices
由2个元素的可迭代对象组成的可迭代对象当作字段的选项.如果有这个参数,默认的表单widget将是一个下拉选而不是标准的文本字段,值为这些选项.
每个元组的第一个元素是设置的模型的值,第二个元素是给人看的名称.例如:

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

通常,最好在模型类里定义choices,给每个值定义一个合适的名字常量:

from django.db import models

class Student(models.Model):
    RRESHMAN = '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 list然后引用它,在模型内定义choices能使类自己保留类信息,并使choices容易引用(例如,Student.SOPHOMORE能在任何地方工作只要导入了Student模型).
另外,出于组织代码的目的,你也可以将选线放到named groups里:

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

每个元组的第一个元素是组的名称.第二个元素是一个由2元素元组组成的可迭代对象,每个2元素元组包含一个值和作为选项的给人看的名称.分组的选项可以和未分组的选项放到一起(就像例子中的unknown选项).
每个有choices的模型字段,django会为字段的值增加一个查询human-readable名称.详情参考数据库API中的get_FOO_display().
注意,choices可以是任何可迭代对象-不一定是列表或元组.你能动态的构造choices.但是如果你使用动态的choices,你最好使用一个有外键的数据库表.choices意味着没有很多改变的静态数据.

django1.7新增
除非字段设置了blank=False,和default,否则下拉选就会渲染一个”——–”标签.在choices里添加一个包含None的元组可以重写这个行为;例如(None, ‘Your String For Display’).另外,你可以使用一个空字符串代替None,只要适用-例如CharField.

db_column

Field.db_column
该字段使用的数据库字段名称.
如果你的数据库字段名是SQL关键字,或者有字符属于非python标识符-比如,连接符(hyphen,-)-这没有问题.django会对字段和表名做合适的引用.

db_index

Field.db_index
如果是True,django-admin sqlindexed会为这个字段输出一个CREATE INDEX语句.

db_tablespace

Field.db_tablespace
如果该字段有索引,database tablespace的名称会用于字段索引.默认是项目的DEFAULT_INDEX_TABLESPACE setting,或是模型的db_tablespace.如果数据库引擎不支持索引的tablespace,那么这个选项会被忽略.

default

Field.default
字段的默认值.可以是一个值或可调用对象.如果是可调用对象,每次新建对象时都会被调用.
默认值不能是可变对象(模型实例,列表,集合等), as a reference to the same instance of that object would be used as the default value in all new model instances.Instead,将想要的默认值封装到一个可调用对象里.例如,如果你有一个自定义的JSONField,想要指定一个字典作为默认值,使用下面的方法:

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

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

注意匿名函数不能用于字段的可选项(例如default)因为不能被migrations序列化.
默认值用于新建模型实例且没有提供字段的值.如果字段是主键,且设置了None,默认值也可以使用.

django1.8更改
在上一个版本中default不能用于None primary key.

editable

Field.editable
如果是False,该字段将不在admin或其他ModelForm里显示.他们也不需要验证.默认为True.