Django模型字段类型详解

AutoField

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.

DurationField

New in Django 1.8.
class DurationField([**options])
用作存储一段时间的字段类型 - 类似Python中的timedelta. 当数据库使用的是PostgreSQL, 该数据类型使用的是一个 interval 而在Oracle上，则使用的是 INTERVAL DAY(9) TO SECOND(6). Otherwise a bigint of microseconds is used.

Note：

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

EmailField

class EmailField([max_length=254, **options])
一个 CharField 用来检查输入的email地址是否合法。它使用 EmailValidator 来验证输入合法性。

Changed in Django 1.8:
默认最大长度 max_length 从75增加到254以符合RFC3696/5321标准。

FileField

class FileField([upload_to=None, max_length=100, **options])
一个上传文件的字段。

Note：

FileField字段不支持primary_key 和unique参数，如果使用会生成 TypeError错误

有两个可选参数：

FileField.upload_to
Changed in Django 1.7:
在旧版本Django中，upload_to 属性是必须要有的;
一个本地文件系统的路径，它将附加到MEDIA_ROOT 设置的后面来确定url 属性的值。

这个路径可能会包含一个 strftime() 格式串,并且会在文件上传时被替换为 实际的date/time作为文件路径 (这样上传的文件就不会塞满你指定的文件夹了).

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

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

大部分情况下，这个实例将还没有保存到数据库中，若它用到默认的AutoField 字段，它的主键字段还可能没有值。
FileField.storage
一个Storage 对象，用于你的文件的存取。参见管理文件 获取如何提供这个对象的细节。

这个字段的默认表单Widget 是ClearableFileInput。

在模型中调用FileField 或 ImageField (见下方) 需如下几步：

在你的settings文件中, 你必须要定义 MEDIA_ROOT 作为Django存储上传文件的路径(从性能上考虑，这些文件不能存在数据库中。) 定义一个 MEDIA_URL 作为基础的URL或者目录。确保这个目录可以被web server使用的账户写入。
在模型中添加FileField 或 ImageField 字段, 定义 upload_to参数，内容是 MEDIA_ROOT 的子目录，用来存放上传的文件。
数据库中存放的仅是这个文件的路径 （相对于MEDIA_ROOT). 你很可能会想用由Django提供的便利的url 属性。比如说, 如果你的ImageField 命名为 mug_shot, 你可以在template中用 {{ 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 主题指导.

Note：

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

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

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

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

FileField 实例将会在你的数据库中创建一个默认最大长度为100字符的varchar 列。就像其他的fields一样, 你可以用 max_length 参数改变最大长度的值.

FileField 和FieldFile

class FieldFile[source]
当你添加 FileField 到你的模型中时, 你实际上会获得一个 FieldFile的实例来替代将要访问的文件。 除了继承至 django.core.files.File的功能外, 这个类还有其他属性和方法可以用于访问文件:

FieldFile.url
通过潜在Storage 类的url()方法可以只读地访问文件的URL。

FieldFile.open(mode='rb')[source]
该方法像标准的Python open() 方法,并可通过 mode参数设置打开模式.

FieldFile.close()[source]
该方法像标准的Pythonfile.close() 方法,并关闭相关文件.

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

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

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

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

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

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

FieldFile.delete(save=True)[source]
删除与此实例关联的文件，并清除该字段的所有属性。注意︰ 如果它碰巧是开放的调用 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
可选的.A regular expression, as a string, that FilePathField will use to filter filenames. Note that the regex will be applied to the base filename, not the full path. Example: "foo.*.txt$", which will match a file called foo23.txt but not bar.txt or foo23.png.

FilePathField.recursive
可选的.Either True or False. Default is False. Specifies whether all subdirectories of path should be included

FilePathField.allow_files
可选的.Either True or False. Default is True. Specifies whether files in the specified location should be included. Either this or allow_folders must be True.

FilePathField.allow_folders
是可选的.输入 True 或者 False.默认值为 False.Specifies whether folders in the specified location should be included. Either this or allow_files must be True.

Of course, these arguments can be used together.

有一点需要提醒的是 match只匹配基本文件名（base filename）, 而不是整个文件路径（full path）:

FilePathField(path="/home/images", match="foo.*", recursive=True)
...will match /home/images/foo.png but not /home/images/foo/bar.png because the match applies to the base filename (foo.png and bar.png).

FilePathField实例被创建在您的数据库为varchar列默认最大长度为 100 个字符。作为与其他字段，您可以更改使用的max_length最大长度。

FloatField

class FloatField([**options])
用Python的一个float 实例来表示一个浮点数.

该字段的默认组件是一个 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])
继承了 FileField的所有属性和方法, 但还对上传的对象进行校验，确保它是个有效的image.

除了从FileField继承来的属性外，ImageField 还有宽和 高属性。

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

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

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

ImageField字段需要调用Pillow 库.

ImageField会创建在你的数据库中 和 varchar 一样,默认最大长度为100和其他字段一样, 你可以使用max_length 参数来设置默认文件最大值.

The default form widget for this field is a ClearableFileInput.

IntegerField

class IntegerField([**options])
一个整数。在Django所支持的所有数据库中，从 -2147483648 到 2147483647 范围内的值是合法的。默认的表单输入工具是TextInput.

IPAddressField

class IPAddressField([**options])
Deprecated since version 1.7:
该字段已废弃，从1.7开始支持GenericIPAddressField.
IP地址，会自动格式化（例如：“192.0.2.30”）。默认表单控件为 TextInput.

GenericIPAddressField

class GenericIPAddressField([protocol=both, unpack_ipv4=False, **options])
一个 IPv4 或 IPv6 地址, 字符串格式 (例如 192.0.2.30 或 2a02:42fe::4). 这个字段的默认表单小部件是一个TextInput.

IPv6 地址会根据 RFC 4291 章节 2.2所规范, 包括该章节中第三段的的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
Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.

If you allow for blank values, you have to allow for null values since blank values are stored as null.

NullBooleanField

class NullBooleanField([**options])
Like a BooleanField, but allows NULL as one of the options. Use this instead of a BooleanField with null=True. The default form widget for this field is a NullBooleanSelect.

PositiveIntegerField（正整数字段）

class PositiveIntegerField([**options])
类似 IntegerField, 但值必须是正数或者零(0). Values from 0 to 2147483647 are safe in all databases supported by Django. The value 0 is accepted for backward compatibility reasons.

PositiveSmallIntegerField

class PositiveSmallIntegerField([**options])
该模型字段类似 PositiveIntegerField, 但是只允许小于某一特定值（依据数据库类型而定）。从0 到 32767 这个区间，对于Django所支持的所有数据库而言都是安全的。

SlugField

class SlugField([max_length=50, **options])
Slug 是一个新闻术语（通常叫做短标题）。一个slug只能包含字母、数字、下划线或者是连字符，通常用来作为短标签。通常它们是用来放在URL里的。

与CharField类似, 你可以指定 max_length 的值(read the note about database portability and max_length in that section, too). 如果没有指定 max_length, Django将会默认长度为50。

Implies setting Field.db_index to True.

It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using prepopulated_fields.

SmallIntegerField

class SmallIntegerField([**options])
与 IntegerField这个字段类型很类似,不同的是SmallInteger类型只能在一个确定的范围内(数据库依赖)。对于django来讲，该字段值在 -32768 至 32767这个范围内对所有可支持的数据库都是安全的。

TextField

class TextField([**options])
大文本字段。该模型默认的表单组件是Textarea。

Changed in Django 1.7:
如果你在这个字段类型中使用了max_length属性，它将会在渲染页面表单元素Textarea 时候体现出来。但是并不会在model或者数据库级别强制性的限定字段长度。Use a CharField for that。

TimeField

class TimeField([auto_now=False, auto_now_add=False, **options])
时间字段，和Python中 datetime.time 一样。Accepts the same auto-population options as DateField.

表单默认为 TextInput.输入框。The admin adds some JavaScript shortcuts.

URLField

class URLField([max_length=200, **options])
一个CharField 类型的URL

The default form widget for this field is a TextInput.

Like all CharField subclasses, URLField takes the optional max_length argument. If you don’t specify max_length, a default of 200 is used.

UUIDField

New in Django 1.8.
class UUIDField([**options])
一个用来存储UUID的字段。使用Python的UUID类。 当使用PostgreSQL数据库时，该字段类型对应的数据库中的数据类型是uuid，使用其他数据库时，数据库对应的是char(32)类型。

使用UUID类型相对于使用具有primary_key参数的AutoField类型是一个更好的解决方案。 数据库不会自动生成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

注意：这里传递给default是一个可调用的对象（即一个省略了括号的方法），而不是传递一个UUID实例给default