前言

本文档包含了Django提供的全部模型字段的字段选项 和 字段类型的API参考。

如果内建的字段不能满足你的需要，你可以尝试对特定国家和文化有效的包含配套代码的 django-localflavor。当然，你也可以很容易的编写你自定义的字段。

严格意义上来讲， model 是定义在django.db.models.fields里面，但为了使用方便，它们被导入到 django.db.models中；标准上，我们导入from django.db import models ，然后使用 models.<Foo>Field的形式使用字段。

字段选项

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

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 中的元组。

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

1
2
3
4
5
6

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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)

尽管你可以在模型类的外部定义choices然后引用它，在模型类中定义choices和其每个choice的name可以保存所有的关于应用到此信息的类的信息， 也使得choices更容易被应用（例如， Student.SOPHOMORE 可以在任何引入Student 模型的位置生效)。

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

1
2
3
4
5
6
7
8
9
10
11
12
13

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意味着那些变动不多的静态数据，如果有的（变动）话。

除非字段中默认了blank=False，那么---------就会在选择框中被渲染出来。你也可以向元祖中添加一个包含None的choices来覆盖这个行为（比如：(None, 'Your String For Display')）。

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，并且想指定一个特定的字典值，可以如下使用：

1
2
3
4

def contact_default():
    return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)

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

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