Django Model field reference - Field types

翻译自官方文档,django 中可用的模型字段及其含义。

AutoField

一个 id 自动递增的 IntegerField 字段,您通常不需要直接使用它,如果不指定主键字段,那么一个 AutoField 字段将被自动添加到模型中。


BigAutoField

和 AutoField 类似,不同之处在于,它的数字范围是 1 到 9223372036854775807 。


BigIntegerField

一个 64 位整数,类似 IntegerField ,不同之处在于他的合法数字范围是 -9223372036854775808 到 9223372036854775807 。该字段的默认表单部件是 TextInput 。


BinaryField

用于存储原始二进制数据的字段,它只支持 bytes 。请注意,该字段的功能有限,比如不支持过滤查询集,也不可能包含在一个 ModelForm 中。

尽管您可能会考虑将数据存储在数据库中,但 99% 的情况下这是糟糕的设计,请考虑使用静态文件来代替。


BooleanField

True / False

该字段的默认表单部件是 CheckboxInput

如果您需要接受 null 值,则应该使用 NullBooleanField 。


CharField

用于存储字符串,对于大量的文字,请使用 TextField 。

该字段的默认部件是 TextInput 。

CharField 有一个额外的必要参数:

CharField.max_length

字段的最大长度(以字符为单位)。在数据库级别和 django 验证中执行。


DateField

日期,由 Python 中的 datetime.date 实例表示,有一些额外的可选参数:

DateField.auto_now

每次保存对象是自动将字段设置为现在,仅在 model.save() 时更新,使用其他方式更新字段时不会自动更新,比如 QuerySet.update() 。

DateField.auto_now_add

首次创建对象时,自动将字段设置为现在。如果设置了此选项,则字段的 default 设置将失效。如果您希望自动保存其他形式的日期:

  • For DateField: default=date.today - from datetime.date.today()
  • For DateTimeField: default=timezone.now - fromdjango.utils.timezone.now()

该字段的默认部件为 TextInput。


DateTimeField

日期和时间,由 Python 的 datetime.datetime 实例表示。默认部件为 TextInput 。

与 DateField 有相同的额外参数(auto_now 和 auto_now_add)。


DecimalField

一个固定精度的十进制数,由 Python 中的 Decimal 实例表示,有两个必需的参数:

DecimalField.max_digits

允许的最大位数,此数字必须大于等于 decimal_places 。

DecimalField.decimal_places

用数字存储的小数位数。

例如,存储数字 999 ,精确到小数点后两位:

1
models.DecimalField(..., max_digits=5, decimal_places=2)

存可能到十亿的数字,精确到小数点后十位:

1
models.DecimalField(..., max_digits=19, decimal_places=10)

该字段的默认表单控件为 NumberInput 。


DurationField

用于存储时间段的字段,由 Python 中的 timedelta 表示。

在不同的数据库中表现可能不同,请谨慎使用。


EmailField

顾名思义……将会由 EmailValidator 验证。


FileField

文件上传字段,不支持 primary_key 参数,如果使用将出错。

有两个可选的参数:

FileField.upload_to

该属性提供了设置上传目录和文件名的方法,有两种设置方式:
您可以指定一个字符串值,它可以包含 strftime() 格式,将会被上传的时间所取代。例如:

1
2
3
4
5
6
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/2017/02/21
upload = models.FileField(upload_to='uploads/%Y/%m/%d/')

您也可以使用默认值 FileSystemStorage ,然而我没看懂使用默认值会如何处理。

upload_to 可以被调用,返回上传路径。关于此项更详细的介绍,可以查看官方文档。

FileField.storage

用于处理文件的存储和检索。请参阅Managing files

该字段默认的部件是 ClearableFileInout 。

在模型中使用 FileField 或者 ImageField 需要几个步骤:

  1. 在 settings.py 中,需要定义 MEDIA_ROOT ,是您想要 django 存储上传文件的目录的完整路径,(出于性能考虑,这些文件不应当存在数据库中)。定义 MEDIA_URL (例如:”/media/“),确保该目录可以由 Web 服务器的用户账户写入。
  1. 将 FileField 或 ImageField 添加到您的模型中,定义 upload_to 选项以指定 MEDIA_ROOT 下用于上传文件的子目录。
  1. 所有存在数据库中的数据都是路径, django 提供了一个名为 url 的便利属性,如果你的 ImageField 的字段名为 mug_shot ,那么你可以在模板中获得图像的绝对路径: 。

例如您 MEDIA_ROOT 的设置为 ‘/home/media’,并且 upload_to 设置为 ‘photos/%Y/%m/%d’,其中的’%Y/%m/%d’将会被 strftime() 格式化,假设在2007年1月15日上传文件,那么文件将被保存至目录 /home/media/photos/2007/01/15 。

如果您想要检索上传文件的文件名或者文件大小,可以使用 name 和 size 属性,有关更多的可用属性和方法,请参阅 File类的定义和Managing files

请注意,无论何时,都应该密切的关注上传的文件以及它们的类型,以避免安全漏洞。

FileField 在数据库中创建为 varchar 的默认最大长度为 100 个字符的列,可以使用 max_length 参数来修改其最大长度。

FileField 和 FieldFile

当访问 FileField 模型时,会提供一个 FieldFile 实例作为访问基础文件的代理。

实例从 File 类继承了诸如 read 和 write 等方法,save 与 delete 方法将会影响到 FieldFile 数据库中关联的模型对象。

FieldFile.name

文件的名称

FieldFile.size

文件大小

FieldFile.url

访问文件的相对 URL

FieldFile.open(mode=’rb’)

pass

FieldFile.close()

pass

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

此方法获取文件名和文件内容,并将它们传递给字段的存储类。

coutent 参数 应该是 django.core.files 对象的一个实例:

1
2
3
4
5
6
7
8
9
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")

FieldFile.delete(save=True)

删除与此实例相关联的文件并清除字段上的所有属性,可选参数 save 空值在删除文件后是否保存模型实例,默认为 True 。

请注意:删除模型时,相关的文件不会被删除,您需要自己处理它。


FilePathField

请参照官方文档(我确实不知道是干啥的)。


FloatField

由 Python 中的 float 表示的浮点数。

默认控件为 NumberInput 。


ImageField

继承 FileField 的所有属性和方法,同时会验证上传的是有效的图像。

有两个额外的可选参数:

  • ImageField.height_field
  • ImageField.width_field

需要 pillow 库。

该字段的默认表单部件是 ClearableInput 。


IntegerField

一个整数 -2147483648 到 2147483647 ,默认表单控件为 NumberInput 。


GenericIpAddressField

字符串格式的 IPv4 或者 IPv6 地址,默认表单控件为 TextInput 。

具体的请参照官方文档。


NullBooleanField

类似 BooleanField ,但允许 NULL 作为其中一个选项,默认表单部件为 NullBooleanSelect 。


PositiveIntegerField

类似 IntegerField ,但是必须是正数或 0 ,范围是 0 到 2147483647 。


PositiveSmallIntegerField

类似 PositiveIntegerField ,范围是 0 到 32767 。


SlugField

一个短的标签,只包含字母、数字、下划线和连字符,通常被用于 URL ,长度限制为 50 。


SmallIntegerField

类似 IntegerField ,范围 -32768 到 32767 。


TextField

一个大文本字段,默认表单小部件为 Textarea 。


TimeField

一个时间,由 Python 中的 datetime.time 实例表示,与 DateField 可以使用相同的自动填充选项。

该字段的默认表单部件为 TextInput 。


URLField

一个 CharField ,代表一个 URL ,默认长度限制为 200 。

默认部件为 TextInput 。


UUIDField

用于存储通用唯一标识符的字段,使用 Python 的 uuid 类。

可用于 AutoField 的 primary_key

1
2
3
4
5
6
import uuid
from django.db import models

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