模型字段¶

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

参见

如果内建的字段不能满足你的需求, 你可以蚕食 django-localflavor (documentation), 其中包含对特定国家和文化的各种配套代码。

注解

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

字段选项¶

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

`null`¶

Field.null¶

如果为 True, Django 将把空值在数据库中存为 NULL ，默认为 is False 。

不要为字符串类型字段设置 null ，例如 CharField 和 TextField 。因为这样会把空字符串存为 NULL 。如果字符串字段设置了 null=True ，那意味着对于“无数据”有两个可能的值： null 和空字符串。这种明显是多余的，Django 的惯例是使用空字符串而不是NULL。

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

注解

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

如果你希望 BooleanField 接受 null 值, 那么使用 NullBooleanField 代替。

`blank`¶

Field.blank¶

如果为 True, 则该字段允许为空。默认为 False 。

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

`choices`¶

Field.choices¶

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

当然也可以在模型类的外部定义choices然后引用它，但是在模型类中定义choices和其每个choice的name(即元组的第二个元素)可以保存所有使用choices的信息，也使得choices更容易被应用（例如， Student.SOPHOMORE 可以在任何引入 Student 模型的地方生效)。

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

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

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

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

choices 只要是可迭代的对象就行 – 并不一定要是列表和元组。这样你可以动态构建choices。但是如果你自己搞不定动态的 choices 。你最好还是使用 ForeignKey 来构建一个合适的数据库表。而对于静态数据来说， choices 是不改变的。

除非在字段中设置了 blank=False 否则将选择框中将包含一个 "---------" 的标签。只要在添加一个 None 到 choices 元组中就可以改变这一行为。e.g. (None, 'Your String For Display') ，或者, 你可以用一个空字符串代替 None 比如在一个 CharField 。

`db_column`¶

Field.db_column¶

数据库中储存该字段的列名。如果未指定，那么Django将会使用Field名作为字段名。

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

`db_index`¶

Field.db_index¶

如果为 True,将会为这个字段创建数据库索引。

`db_tablespace`¶

Field.db_tablespace¶

The name of the database tablespace to use for this field’s index, if this field is indexed. The default is the project’s DEFAULT_INDEX_TABLESPACE setting, if set, or the db_tablespace of the model, if any. If the backend doesn’t support tablespaces for indexes, this option is ignored.

`default`¶

Field.default¶

该字段的默认值. 它可以是一个值或者一个可调用对象。如果是一个可调用对象，将会在创建新对象时调用。

这个默认值不可以是一个可变对象(比如 模型实例 , 列表 , 集合 等等)。因为对于所有模型的一个新的实例来说，它们指向同一个引用。或者，把他们封装为一个可调用的对象。例如，有一个自定义的 JSONField,想指定一个特定的字典值，可以这样:

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

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

lambda 表达式不能作为 default 的参数值，因为她们无法被migrations序列化。

对于将映射到模型实例的外键之类的字段，默认值应该是它们引用的字段的值(除非to字段设置为pk)，而不是模型实例。

对于将映射到模型实例的字段，例如 ForeignKey 。其默认值应该是他们引用的字段值( 除非 to_field 设置了 pk)而不是模型实例。

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

`editable`¶

Field.editable¶

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

`error_messages`¶

Field.error_messages¶: error_messages 参数用于重写默认的错误提示，通过字典的key来匹配将要改变的错误类型。

错误提示的key包括 null, blank, invalid, invalid_choice, unique, 和 unique_for_date 。下面的字段类型中的 error_messages 的 keys 是不一样的。

`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特定的字符。请确保你所使用的help text能够避免一些不信任用户的跨站脚本攻击。

`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, FileField 的其他所有字段。

当设置了 unique 为 True 后，可以不必再指定 db_index, 因为 unique 也会创建索引。

`unique_for_date`¶

Field.unique_for_date¶

设置为 DateField 或者 DateTimeField 字段的名字，表示要求该字段对于相应的日期字段值是唯一的。

例如，字段 title 设置了 unique_for_date="pub_date" ，那么Django将不会允许在同一 pub_date 的两条记录的 title 相同。

需要注意的是，如果你设置的是一个 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 可以用于自定义一个字段类型的查询，以及如何从一个字段获取查询。

字段类型¶

`AutoField`¶

class AutoField(**options)¶

一个根据实际ID自动增长的 IntegerField 。通常不需要直接使用它,如果表中没有设置主键时，将会自动添加一个自增主键。参考自增主键。

`BigAutoField`¶

class BigAutoField(**options)¶

New in Django 1.10:

一个64位整数, 和 AutoField 类似，不过它的范围是 1 到 9223372036854775807 。

`BigIntegerField`¶

class BigIntegerField(**options)¶

一个64位整数, 和 IntegerField 类似，不过它允许的值范围是 -9223372036854775808 到 9223372036854775807 。这个字段默认的表单组件是一个 TextInput.

`BinaryField`¶

class BinaryField(**options)¶

这是一个用来存储原始二进制码的字段。支持 bytes 赋值。注意这个字段只有很有限的功能。比如，不能在一个 BinaryField 值的上进行查询过滤。 ModelForm 中也不允许包含 BinaryField 。

滥用 BinaryField

可能你想使用数据库来存储文件，但是99%的情况下这都是不好的设计。这个字段不是代替静态文件的最佳方式。

`BooleanField`¶

class BooleanField(**options)¶

一个 true/false 字段。

这个字段的默认表单部件是 CheckboxInput 。

如果要允许 null 值，那么可以使用 NullBooleanField 代替。

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

`CharField`¶

class CharField(max_length=None, **options)¶

字符字段。

对于比较大的文本内容,请使用 TextField 类型。

这个字段的默认表单部件是 TextInput.

CharField 字段有个额外参数:

CharField.max_length¶: 字段允许的最大字符串长度。这将在数据库中和表单验证时生效。

注解

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

MySQL users

如果你使用的是 MySQLdb 1.2.2 设置的是 utf8_bin 校对 (这不是默认项), 你必须了解一些问题。详细请参考 MySQL 数据库注意事项。

`CommaSeparatedIntegerField`¶

class CommaSeparatedIntegerField(max_length=None, **options)¶

1.9 版后已移除: 这个字段可以使用 CharField 的 validators=[validate_comma_separated_integer_list] 代替。

一个逗号分隔的整数字段。和 CharField 一样， max_length 是必填参数，同时再数据库移植时也需要注意。

`DateField`¶

class DateField(auto_now=False, auto_now_add=False, **options)¶

日期, 表现为 Python中 datetime.date 的实例。但是有几个额外的设置参数:

DateField.auto_now¶

当保存对象时，自动设置改字段为当前时间。比如用于字段 “修改时间”。注意这会始终使用当前时间，并不是一个默认值。

这个字段只会在调用 Model.save() 方法时自动更新。更新其他字段或使用这他更新方法时，这个字段不会更新，比如 QuerySet.update() 方法。

DateField.auto_now_add¶

当字段被首次创建时被设置为当前时间。适用于创建日期，注意这会始终使用当前时间，并不是一个可以重写的默认值。因此就算你在创建时指定了日期，也会被忽略掉。如果你希望修改这个值，请设置以下内容，而不是 auto_now_add=True:

对于 DateField: default=date.today - from datetime.date.today()
对于 DateTimeField: default=timezone.now - from django.utils.timezone.now()

这个字段的默认表单部件是 TextInput 。在admin中会添加一个JavaScript的日期插件，带有一个 “Today” 的快捷按钮。也包含 invalid_date 错误消息。

选项 auto_now_add, auto_now, 和 default 是相互排斥的，他们之间的任何组合将会发生错误的结果。

注解

在当前框架实现中, 设置 auto_now 或者 auto_now_add 为 True 都会使字段同时得到两个设置 editable=False 和 blank=True 。

注解

auto_now 和 auto_now_add 这两个设置会在对象创建或更新时，总是使用 default timezone 的日期。你可以考虑一下简单地使用你自己的默认调用或者重写 save() 方法来代替使用 auto_now 和 auto_now_add;也可以使用 DateTimeField 类型代替 DateField ，然后在显示时间的时候再决定如何从 datetime 转换到 date。

`DateTimeField`¶

class DateTimeField(auto_now=False, auto_now_add=False, **options)¶

时间和日期, 表现为 Python 中的 datetime.datetime 实例。和 DateField 有相同的额外参数。

默认的表单部件是一个 TextInput 。admin页面使用两个带有 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)

该字段默认的表单部件是 NumberInput ，如果 localize 设置为 False 则是 TextInput 。

注解

关于更多 FloatField 和 DecimalField 的区别信息，请参考 FloatField vs. DecimalField 。

`DurationField`¶

class DurationField(**options)¶

用作存储一段时间的字段类型 - 类似Python中的 timedelta 。.当数据库使用的是 PostgreSQL, 该数据类型使用的是一个 interval ，而在Oracle上，则使用的是 INTERVAL DAY(9) TO SECOND(6) 。其他情况使用微秒的的 bigint 。

注解

DurationField 的算数运算在多数情况下可以很好的工作。然而，在除了 PostgreSQL之外的其他数据库中, 将 DurationField 和 DateTimeField 的实例比较则不会得到正确的结果。

`EmailField`¶

class EmailField(max_length=254, **options)¶

一个检查输入的email地址是否合法的 CharField 类型。它使用 EmailValidator 来验证输入合法性。

`FileField`¶

class FileField(upload_to=None, max_length=100, **options)¶

上传文件字段。

注解

primary_key 和 unique 在这个字段中不支持, 如果使用在抛出 TypeError 异常。

拥有两个可选参数:

FileField.upload_to¶

用于设置文件路径和文件名, 有两种设置方法，但都是通过 Storage.save() 方法设置。

你如果路劲包含 strftime() 格式，将被替换为实际的日期/时间作为文件路径 (这样上传的文件就不会到指定的文件夹)。例如:

class MyModel(models.Model):
    # file will be uploaded to MEDIA_ROOT/uploads
    upload = models.FileField(upload_to='uploads/')
    # or...
    # file will be saved to MEDIA_ROOT/uploads/2015/01/30
    upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

如果使用了默认的 FileSystemStorage, 这个字符串将会再添加上 MEDIA_ROOT 路径。如果想使用其他储存方法，请查看储存文档如何处理 upload_to 。

upload_to 也可以是一个可调用的对象。将调用它来获取上传路径，包括文件名。这个可调用对象必须接受两个参数，并且返回一个Unix 风格的路径（带有前向/）给存储系统。将传递的两个参数为:

Argument Description

instance

定义 FileField 的模型的实例更准确地说，就是当前文件的所在的那个实例。

大部分情况下，这个实例将还没有保存到数据库中，若它用到默认的 AutoField 字段，它的主键字段还可能没有值。

filename 最初给文件的文件名。在确定最终目标路径时，可能不会考虑到这一点。

例如:

def user_directory_path(instance, filename):
    # file will be uploaded to MEDIA_ROOT/user_<id>/<filename>
    return 'user_{0}/{1}'.format(instance.user.id, filename)

class MyModel(models.Model):
    upload = models.FileField(upload_to=user_directory_path)

FileField.storage¶: 一个Storage 对象，用于你的文件的存取。参见 Managing files 查看如何提供这个对象的细节。

这个字段的默认表单部件是一个 ClearableFileInput 。

在模式中使用 FileField 类型或 ImageField (见下文) 需要如下几步:

在 settings 文件中, 将Django储存文件的的完整路径设置到 MEDIA_ROOT 项。 (从性能上考虑，不要将这些文件存在数据库中) 定义一个 MEDIA_URL 作为基础目录的URL。确保web server账户对这个目录有读写权限。
添加 FileField 或者 ImageField 到模型中, 定义属性 upload_to 用来存放上传的文件，应该是 MEDIA_ROOT 的子目录。
数据库中存放的仅是这个文件的路径 (相对于 MEDIA_ROOT)。然后使用 url 属性来获取。例如, 一个叫做 mug_shot 的 ImageField 字段，可以使用 {{ object.mug_shot.url }} 来获取它的绝对路径。

假如, 你将 MEDIA_ROOT 设置为 '/home/media', upload_to 属性设置为 'photos/%Y/%m/%d' 。 upload_to 的 '%Y/%m/%d' 部分是 strftime() 的格式化字符。 '%Y' 表示四位数的年份, '%m' 表示两位数的月份， '%d' 表示两位数的日份。如果文件上传时间是 Jan. 15, 2007,将被存到目录 /home/media/photos/2007/01/15 。

如果想要知道上传文件的磁盘文件名或文件大小，可以使用 name 和 size 属性得到；关于更多支持的方法和属性。请参考 File 的参考文档 Managing files 。

注解

文件作为模型存储在数据库中的一部分，磁盘上文件名在模型保存完毕之前是不可靠的。

上传的文件对应的URL可以通过使用 url 属性获得. 其实在内部，是调用 Storage 类的 url() 方法。

值得注意的是，无论任何时候处理上传文件时，都应该密切关注文件将被上传到哪里，上传的文件类型，以避免安全漏洞。 检查所有上传文件 确保上传的文件是被允许的文件。例如，如果你盲目的允许其他人在无需认证的情况下上传文件至你的web服务器的root目录中，那么别人可以上传一个CGI或者PHP脚本然后通过访问一个你网站的URL来执行这个脚本。所以，不要允许这种事情发生。

甚至是上传HTML文件也需要注意，它可以通过浏览器（虽然不是服务器）执行，也可以引发相当于是XSS或者CSRF攻击的安全威胁。

FileField 对象在数据库中以最大长度100个字节的 varchar 类型存在。和普通字段一样。也可以使用 max_length 参数限制。

`FileField` 和 `FieldFile`¶

class FieldFile¶

当添加一个 FileField 字段到模型中时，实际上是一个 FieldFile 实例作为将要访问文件的代理。

The API of FieldFile mirrors that of File, with one key difference: The object wrapped by the class is not necessarily a wrapper around Python’s built-in file object. Instead, it is a wrapper around the result of the Storage.open() method, which may be a File object, or it may be a custom storage’s implementation of the File API.

In addition to the API inherited from File such as read() and write(), FieldFile includes several methods that can be used to interact with the underlying file:

警告

Two methods of this class, save() and delete(), default to saving the model object of the associated FieldFile in the database.

FieldFile.name¶

文件的名称，Storage 的根路径， FileField 的相对路径。

FieldFile.size¶

下面 Storage.size() 方法的返回结果。

FieldFile.url¶

通过下面 Storage 类的 url() 方法只读地访问文件的URL。

FieldFile.open(mode='rb')¶

在指定模式下打开或重写与该实例相关联的文件，和Python的标准 open() 方法不同的是，它不返回文件描述符。

由于底层文件在访问它时隐式地打开，因此调用此方法可能没有必要，除非将指针重置到底层文件或更改模式。

FieldFile.close()¶

类似Python的 file.close() 方法，关闭相关文件。

FieldFile.save(name, content, save=True)¶

这个方法会将文件名以及文件内容传递到字段的storage类中,并将模型字段与保存好的文件关联。 I 如果想要手动关联文件数据到你的模型中的 FileField 实例, 则 save() 方法总是用来保存该数据。

方法接受两个必选参数: name 文件名, 和 content 文件内容。可选参数 save 控制模型实例在关联的文件被修改时是否保存，默认为 True 。

需要注意的是 content 参数必须是 django.core.files.File 的实例, 不是Python内建的文件对象。你可以用如下方法从一个已经存在的Python文件对象来构建 File:

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/path/to/hello.world')
myfile = File(f)

或者，你可以像下面的一样从一个python字符串中构建:

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

其他更多信息, 参见 Managing files.

FieldFile.delete(save=True)¶

删除与此实例关联的文件，并清除该字段的所有属性。注意:如果在调用 delete() 时有打开操作，该方法将关闭该文件。

save 控制模型实例在关联的文件被修改时是否保存，默认为 True 。

注意，model删除的时候，与之关联的文件并不会被删除。如果你要把文件也清理掉，你需要自己处理

`FilePathField`¶

class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)¶

一个 CharField 内容只限于文件系统内特定目录下的文件名，有几个特殊参数, 其中第一个是 必须的:

FilePathField.path¶: 必传。 FilePathField 应该得到的选择目录的绝对文件系统路径。例如: "/home/images".

FilePathField.match¶: 可选。一个字符串形式的正则表达式。FilePathField 使用其过滤文件名。 regex将应用于基本文件名，而不是全部路径。例如："foo.*\.txt$" 将会匹配到 foo23.txt 但不会匹配到 bar.txt 或 foo23.png 。

FilePathField.recursive¶: 可选。只能是 True 或者 False 。默认为 False 。声明是否包含所有子目录的 path 。

FilePathField.allow_files¶: 可选。只能是 True 或者 False 。默认为 True 。声明是否包含指定位置的文件该参数和 allow_folders 必须有一个为 True 。

FilePathField.allow_folders¶: 可选。只能是 True 或者 False 。默认为 False 。声明是否包含指定位置的文件夹。该参数和 allow_files 必须有一个为 True 。

当然，这些参数可以同时使用。

有一点需要提醒的是 match 只匹配基本文件名, 而不是整个文件路径,例如:

FilePathField(path="/home/images", match="foo.*", recursive=True)

…将会匹配 /home/images/foo.png 但不会匹配 /home/images/foo/bar.png 因为 match 只作用于基本文件名 (foo.png 和 bar.png)。

FilePathField 再数据库中以 varchar 类型存在默认最大长度为 100 个字节。和普通一段一样，可以使用 max_length 参数修改长度限制。

`FloatField`¶

class FloatField(**options)¶

用Python的一个 float 实例来表示一个浮点数。

如果属性 localize 为 False 则默认表单部件是一个 NumberInput ，否则是一个 TextInput 。

FloatField vs. DecimalField

有时候 FloatField 类可能会和 DecimalField 类产生混淆。虽然它们表示都表示实数，但是二者表示数字的方式不一样。 FloatField 使用Python内部的 float 类型，而 DecimalField 使用的是Python的 Decimal 类型。想要了解更多二者的差别, 可以查看Python文档中的 decimal 模块。

`ImageField`¶

class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)¶

继承了:class:FileField 类的所有方法和属性，而且还对上传的对象进行校验，确保它是个有效的image。

除了从 FileField 继承的属性外， ImageField 类还增加了 height 和 width 属性。

为了更便捷的去用这些属性值, ImageField 有两个额外的可选参数:

ImageField.height_field¶: 该属性的设定会在模型实例保存时,自动填充图片的高度。

ImageField.width_field¶: 该属性的设定会在模型实例保存时,自动填充图片的宽度。

ImageField需要 Pillow 库支持。

ImageField 实例在数据库中以 varchar 类型存在，默认最大长度为100个字节，和普通字段一样。也可以使用 max_length 参数限制。

该字段默认的表单部件是一个 ClearableFileInput 。

`IntegerField`¶

class IntegerField(**options)¶

一个整数。在Django所有支持的数据库中，-2147483648 到 2147483647 范围才是合法的。如果设置了 localize 为 False ,那么默认表单部件将是一个 NumberInput 否则是一个 TextInput 。

`GenericIPAddressField`¶

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)¶

一条IPv4或IPv6地址, 字符串格式是 (e.g. 192.0.2.30 或者 2a02:42fe::4)。默认的表单部件是 TextInput.

IPv6地址规范遵循 RFC 4291#section-2.2 2.2 章节, 包括使用该部分第3段中建议的IPv4格式, 如 ::ffff:192.0.2.0 。例如, 2001:0::0:01 将被转换成 2001::1, ::ffff:0a0a:0a0a 转换成 ::ffff:10.10.10.10 。所有字符都转换为小写。

GenericIPAddressField.protocol¶: 限制指定协议的有效输入。接受的值为 'both' (默认), 'IPv4' 或 'IPv6' 。匹配不区分大小写。

GenericIPAddressField.unpack_ipv4¶: 解析IPv4映射地址如 ::ffff:192.0.2.1. 如果启用该选项，则地址将被解析到 192.0.2.1 。默认是禁用。只有当 protocol 设置为 'both' 时才可以使用。

如果允许空值，则必须允许null值，因为空值存储为null。

`NullBooleanField`¶

class NullBooleanField(**options)¶

类似 BooleanField, 但是它允许 NULL 值。可以用它来代替 BooleanField 字段设置 null=True 的情况。它的默认表单是 NullBooleanSelect 。

`PositiveIntegerField`¶

class PositiveIntegerField(**options)¶

类似 IntegerField 类型, 但必须是整数或者零 (0)。取值范围是 0 到 2147483647 。允许 0 是为了向后兼容。

`PositiveSmallIntegerField`¶

class PositiveSmallIntegerField(**options)¶

类似 PositiveIntegerField 类型，但其允许的值必须小于某个特定值 (有数据库决定)。在Django所支持的数据库中 0 到 32767 内的值是绝对允许的。

`SlugField`¶

class SlugField(max_length=50, **options)¶

Slug 是一个新闻术语，通常叫做短标题。slug只能包含字母、数字、下划线或者是连字符。通常它们是用来放在URL里的。

类似 CharField 类型，可以指定 max_length (请参阅该部分中的有关数据库可移植性的说明和 max_length ) 如果没有指定 max_length 属性，将默认使用50。

同时 Field.db_index 设置为 True 。

比较可行的做法是根据其他值的内容自动预填 SlugField 的值。在admin中可以使用 prepopulated_fields 来实现。

SlugField.allow_unicode¶: New in Django 1.9:

如果设置为 True, 该字段除了ASCII之外，还接受Unicode字母。默认为 False.

`SmallIntegerField`¶

class SmallIntegerField(**options)¶

类似 IntegerField, 但只允许某些特定的值 (数据库决定)。在Django所支持的数据库中 -32768 到 32767 之前是绝对允许的。

`TextField`¶

class TextField(**options)¶

大文本字段。默认的表单部件是一个 Textarea 。

如果指定了 max_length 属性, 它将会在渲染页面时表单部件 Textarea 中体现出来，但是却不会在模型和数据库中有这个限制。如果需要这样清使用 CharField 类型。

MySQL 用户

如果在 MySQLdb 1.2.1p2 中使用该字段，并且是 utf8_bin 排序规则(默认*不是* 这个) 则需要注意几个问题。参考 MySQL database notes 。

`TimeField`¶

class TimeField(auto_now=False, auto_now_add=False, **options)¶

时间字段, 类似于Python datetime.time 实例. 和 DateField 具有相同的选项.

默认的表单部件是一个 TextInput. 在Admin中添加了一些JavaScript快捷方式。

`URLField`¶

class URLField(max_length=200, **options)¶

一个 CharField 类型的URL.

默认的表单部件是一个 TextInput.

与所有 CharField 子类一样, URLField 接受 max_length 可选参数. 如果没有特别指定 max_length 默认长度是200.

`UUIDField`¶

class UUIDField(**options)¶

一个用于存储唯一标识符的字段. 使用 Python 的 UUID 类. 如果使用 PostgreSQL, 将使用 uuid 数据类型储存, 其他情况是一个 char(32).

惟一的标识符是很好用来替代 AutoField 类型 primary_key 的方法. 数据库不会自动生成UUID值, 所以最好使用 default 参数:

import uuid
from django.db import models

class MyUUIDModel(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    # other fields

注意传入的是一个可调用的对象(即一个省略括号的方法) 而不是传入一个 UUID 实例给 default .

Field API参考¶

class Field¶

Field 是一个抽象的类, 用来表示数据库中的表的列.

Django使用字段创建数据库表(db_type()), 将Python类型映射到数据库(get_prep_value()), 反之亦然(from_db_value()).

在各个版本的Django API中field是最根本的部分, 尤其是 models 和 querysets.

在模型中, 字段被实例化为类的属性, 并表现为一个特定的表的列，详情参考模型. 它具有许多属性，如 null 和 unique 等, 以及用于将字段值映射到数据库特定值的方法.

Field 是 RegisterLookupMixin 的子类，因此可以在其上注册 Transform 和 Lookup，也就可以在 QuerySet 中使用(例如 field_name__="foo"). 所有内置查询都是默认注册好的.

Django的所有内建字段，如 CharField 都是 Field 的特殊实现. 如果需要自定义字段，则可以将任何内置字段重载，也可以重写一个新的 Field. 无论哪种情况，请参考自定义模型字段.

description¶

字段的详细描述，例如用于 django.contrib.admindocs 应用程序.

描述可以是以下形式:

description = _("String (up to %(max_length)s)")

其中参数从字段的 __dict__ 去获取.

为了将 Field 映射到数据库特定类型，Django开放了几种方法:

get_internal_type()¶

返回一个命名此字段的字符串用于后端特定用途. 默认情况下, 它返回类名.

有关自定义字段中的用法，请参见仿造内置字段类型.

db_type(connection)¶

返回 Field 的数据库列数据类型，同时考虑 connection.

有关自定义字段中使用自定义数据库列类型.

rel_db_type(connection)¶

New in Django 1.10:

返回指向 Field 的字段的数据库列数据类型，例如 ForeignKey 和 OneToOneField, 并考虑 connection.

有关自定义字段中使用自定义数据库列类型.

有三种主要情况，Django需要与数据库后端和字段交互:

当它查询数据库 (Python value -> database backend value)
当它从数据库加载数据 (database backend value -> Python value)
当它保存到数据库 (Python value -> database backend value)

查询时, get_db_prep_value() 和 get_prep_value() 将被用到:

get_prep_value(value)¶

value 是模型属性的当前值, 该方法应返回用作查询的参数的格式数据.

有关使用方法，请参阅转换Python对象至查询值.

get_db_prep_value(value, connection, prepared=False)¶

将 value 转换为特定后端值. 如果设置 prepared=True，则默认返回 value. 如果为 False 则返回 get_prep_value().

有关使用方法，请参阅转换查询值至数据库值.

加载数据时 from_db_value() 将被使用:

from_db_value(value, expression, connection, context)¶

将数据库返回的值转换为Python对象. 它与 get_prep_value() 相反.

此方法不使用于大多数内置字段, 因为这些字段在数据库后端已返回正确的Python类型，或后端本身执行转换.

有关使用方法，请参阅将值转换成Python对象.

注解

出于性能原因，from_db_value 没有在不需要它的字段上实现(所有Django字段). 因此，您不能在定义中调用 super.

保存数据时, pre_save() 和 get_db_prep_save() 将被使用:

get_db_prep_save(value, connection)¶: 类似于 get_db_prep_value(), 但仅仅在字段值一定会保存到数据库时调用. 默认返回 get_db_prep_value().

pre_save(model_instance, add)¶

在 get_db_prep_save() 之前调用, 以在保存之前准备好值. (e.g. for DateField.auto_now).

model_instance 是该字段所属的实例， add 是首次将实例保存到数据库.

它会返回此字段的 model_instance 适当属性的值. 属性名称位于 self.attname (这个由 Field 设置)

有关使用方法，请参阅保存前预处理数据.

字段通常以不同的类型接收它们的值，无论是序列化还是表单.

to_python(value)¶

将value值转换为正确的python对象. 它作为 value_to_string() 的反向操作，也是在 clean() 中调用.

有关使用方法，请参阅将值转换成Python对象.

除了保存到数据库，字段还需要知道如何序列化值:

value_to_string(obj)¶

将 obj 转换成字符串. 用于序列化字段的值.

有关使用方法，请参阅字段序列化转换.

使用 model forms 时, Field 需要知道应由哪个表单字段表示:

formfield(form_class=None, choices_form_class=None, **kwargs)¶

返回 ModelForm 该字段的默认 django.forms.Field.

默认情况下, 如果 form_class 和 choices_form_class 都是 None, 则使用 CharField. 如果字段没有指定 choices 和 choices_form_class, 则使用 TypedChoiceField.

有关用法, 参见为模型字段指定表单字段.

deconstruct()¶

返回足够多信息的4元元祖, 用来重新创建字段:

模型中的字段名称.
字段的导入路径 (e.g. "django.db.models.IntegerField").

这最好是能够兼容的版本，所以不要太具体更好.
位置参数列表.
关键词参数列表.

必须将此方法添加到1.7之前的字段, 才能使用迁移迁移其数据.

Django 1.10 文档

模型字段¶

字段选项¶

null¶

blank¶

choices¶

db_column¶

db_index¶

db_tablespace¶

default¶

editable¶

error_messages¶

help_text¶

primary_key¶

unique¶

unique_for_date¶

unique_for_month¶

unique_for_year¶

verbose_name¶

validators¶

注册和查询¶

字段类型¶

AutoField¶

BigAutoField¶

BigIntegerField¶

BinaryField¶

BooleanField¶

CharField¶

CommaSeparatedIntegerField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FileField 和 FieldFile¶

FilePathField¶

FloatField¶

ImageField¶

IntegerField¶

GenericIPAddressField¶

NullBooleanField¶

PositiveIntegerField¶

PositiveSmallIntegerField¶

SlugField¶

SmallIntegerField¶

TextField¶

TimeField¶

URLField¶

UUIDField¶

关系字段¶

ForeignKey¶

数据库中表示¶

参数¶

ManyToManyField¶

数据库表示¶

参数¶

OneToOneField¶