Model field reference - Field ty

2018-01-10 本文已影响0人寂寞杰罗

Field types（字段类型）

AutoField

class AutoField(**options)

一个IntegerField根据可用的ID自动递增。你通常不需要直接使用它; 如果不另外指定，则主键字段将自动添加到您的模型中。请参阅自动主键字段。

BigAutoField

class BigAutoField(**options)

一个64位整数，很像一个AutoField不同之处在于它是保证从适合数字1到9223372036854775807。

BigIntegerField

class BigIntegerField(**options)

一个64位整数，很像一个IntegerField不同之处在于它是保证从适合数字-9223372036854775808到 9223372036854775807。这个字段的默认表单部件是一个TextInput。

BinaryField

class BinaryField(**options)

用于存储原始二进制数据的字段。它只支持bytes分配。请注意，此字段的功能有限。例如，无法过滤BinaryField值上的查询集。也不能在一个ModelForm中包含一个BinaryField。

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是在数据库级别和Django验证中强制执行的。

注意：如果您正在编写一个必须可移植到多个数据库后端的应用程序，则应该知道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- 从 datetime.date.today()
*DateTimeField：default=timezone.now- 从 django.utils.timezone.now()

这个字段的默认表单部件是一个TextInput。管理员添加了JavaScript日历和“今天”的快捷方式。包含一个附加的invalid_date错误消息key。

选项auto_now_add，auto_now和default互斥。这些选项的任何组合都会导致错误。

注意：在当前的应用中，设置auto_now或auto_now_add为 True，会导致该字段editable=False和blank=True 设置。

注意：在auto_now和auto_now_add选项将始终使用的日期默认时区在创建或更新的时刻。如果你需要不同的东西，你可能要考虑简单地使用自己的可调用默认值或覆盖save() 而不是使用auto_now或auto_now_add；或者使用一个DateTime字段而不是一个DateField决定如何处理从datetime到date的转换。

DateTimeField

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

日期和时间，在Python中表示为datetime.datetime实例。带有与DateField相同的额外参数。
这个字段的默认表单部件是一个单一的TextInput。管理员使用两个单独的TextInput小部件与JavaScript快捷方式。

DecimalField

class DecimalField(max_digits=None, decimal_places=None, **options)

一个固定精度的十进制数，在Python中表示为Decimal实例。有两个必要的参数：

DecimalField.max_digits
号码中允许的最大位数。请注意，这个数字必须大于或等于decimal_places。

DecimalField.decimal_places
与数字一起存储的小数位数。

例如，要存储最大为999且带有2位小数的数字，您可以使用：

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

而要存储最大10亿且带有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参数，如果使用将报错。

有两个参数选项：

FileField.upload_to
这个属性规定了上传文件的路径和名称，并可以通过两种方式设置。在这两种情况下，该值都传递给Storage.save()方法。
如果指定一个字符串值，它可能包含的strftime()格式，这将是由文件上传（以便上传的文件不填写指定的目录）的日期/时间进行更换。例如：

class MyModel(models.Model):
    # 文件将被上传到`MEDIA_ROOT/uploads`目录
    upload = models.FileField(upload_to='uploads/')
    # 或者...
    # 文件将被存储于`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	An instance of the model where the FileField is defined. More specifically, this is the particular instance where the current file is being attached. In most cases, this object will not have been saved to the database yet, so if it uses the default AutoField, it might not yet have a value for its primary key field.
filename	The filename that was originally given to the file. This may or may not be taken into account when determining the final destination path.

例如：

def user_directory_path(instance, filename):
    # 文件将被上传到：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
存储对象，用于处理文件的存储和检索。有关如何提供此对象的详细信息，请参阅管理文件。
该字段的默认表单部件是ClearableFileInput。
在模型中使用FileField或ImageField（见下文）需要几个步骤：

在您的设置文件中，您需要将MEDIA_ROOT定义为您希望Django存储上传文件的目录的完整路径。（对于性能，这些文件不存储在数据库中。）将MEDIA_URL定义为该目录的基本公用URL。确保该目录可由Web服务器的用户帐户写入。
将FileField或ImageField添加到模型中，定义upload_to选项以指定MEDIA_ROOT的子目录以用于上传的文件。
所有将存储在数据库中的文件都是一个路径（相对于MEDIA_ROOT）。你很可能会想使用Django提供的便捷url属性。例如，如果您的ImageField被称为mug_shot，则可以使用{{object.mug_shot.url}}在模板中获取图像的绝对路径。

例如，假设你的MEDIA_ROOT设置为/home/media，upload_to设置为photos/%y/%m/%d。upload_to的%y/%m/%d部分是strftime()格式；%y是四位数年份，%m是两位数月份，％d是两位数字日期。如果您在2007年1月15日上传文件，它将被保存在/home/media/photos/2007/01/15目录中。

如果你想检索上传文件的磁盘文件名或文件大小，则可以分别使用名称和大小属性; 有关可用属性和方法的更多信息，请参阅文件类参考和管理文件主题指南。

注意：该文件作为模型保存在数据库中的一部分进行保存，因此在保存模型之后，不能依赖磁盘上使用的实际文件名。

上传的文件的相对URL可以使用url属性获取。在内部，它调用底层存储类的url()方法。

请注意，无论何时处理上传的文件，都应密切注意您上传的文件的位置以及它们的类型，以避免安全漏洞。验证所有上传的文件，以确保这些文件是您认为的文件。例如，如果您盲目地让某人上传文件（无需验证）到Web服务器文档根目录中的某个目录，则有人可以上传CGI或PHP脚本，并通过访问您网站上的URL来执行该脚本。不要这样做。

还要注意的是，即使是上传的HTML文件，由于它可以被浏览器执行（尽管不是由服务器执行），也可能造成等同于XSS或CSRF攻击的安全威胁。

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

FileField and FieldFile

class FieldFile

当您访问模型上的FileField时，将为您提供FieldFile的实例作为访问基础文件的代理。

FieldFile的API反映了File的特性，主要区别在于：由类包装的对象不一定是Python内置文件对象的包装。相反，它是Storage.open()方法（可能是File对象）的结果的一个包装，也可能是File API的自定义存储实现。

除了从File继承的API（例如read()和write()之外，FieldFile还包括几个可用于与基础文件进行交互的方法：

警告：这个类的两个方法save()和delete()默认保存关联的FieldFile的模型对象到数据库中。

FieldFile.name

文件的名称，包括从相关FileField的Storage的根目录的相对路径。

FieldFile.size

底层Storage.size()方法的结果。

FieldFile.url

通过调用基础Storage类的url()方法来访问文件的相对URL的只读属性。

FieldFile.open（模式= 'RB'）

以指定模式打开或重新打开与此实例关联的文件。与标准的Python open()方法不同，它不返回文件描述符。

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

FieldFile.close()

行为与标准的Python file.close()方法相似，并关闭与此实例关联的文件。

FieldFile.save（name，content，save = True）

此方法将文件名和文件内容传递给字段的存储类，然后将存储的文件与模型字段相关联。如果要手动将文件数据与模型上的FileField实例相关联，则使用save()方法来保留该文件数据。

需要两个必需的参数：名称是文件的名称，内容是包含文件内容的对象。可选的save参数控制在与该字段关联的文件被更改后是否保存模型实例。默认为True。

请注意，content参数应该是django.core.files.File的一个实例，而不是Python的内置文件对象。你可以像这样从现有的Python文件对象构造一个文件：

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）

删除与此实例关联的文件，并清除该字段上的所有属性。注意：这个方法会在调用delete()的时候关闭文件。

可选的save参数控制在与该字段关联的文件被删除后是否保存模型实例。默认为True。

请注意，删除模型时，相关文件不会被删除。如果您需要清理孤立的文件，则需要自己处理（例如，使用自定义管理命令，可以手动运行或计划通过例如cron定期运行）。

FilePathField

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

一个CharField，其选择仅限于文件系统上某个目录中的文件名。有三个特殊的论点，其中第一个是必需的：

FilePathField.path

必须。FilePathField应该从中选择的目录的绝对文件系统路径。例如：/ home / images。

FilePathField.match

可选的。FilePathField将用来过滤文件名的正则表达式，作为字符串。请注意，正则表达式将应用于基本文件名，而不是完整路径。例如：foo.*\.txt$，它将匹配一个名为foo23.txt但不是bar.txt或foo23.png的文件。

FilePathField.recursive

可选的。True或False。默认是False。指定是否应该包含路径的所有子目录。

FilePathField.allow_files

可选的。True或False。默认是True。指定是否应该包含指定位置的文件。这个选项或者allow_folders必须有一个为True。

FilePathField.allow_folders

可选的。True或False。默认是False。指定是否应该包含指定位置的文件夹。这个或者allow_files必须是True。

当然，这些参数可以一起使用。

一个潜在的问题是匹配适用于基本文件名，而不是完整路径。所以，这个例子：

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

...匹配/home/images/foo.png，但不匹配/home/images/foo/bar.png，因为匹配适用于基本文件名（foo.png和bar.png）。

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

FloatField

class FloatField(**options)

由浮点实例在Python中表示的浮点数。

当localize为False或TextInput时，此字段的默认表单窗口小部件为NumberInput。

FloatField vs DecimalField
FloatField类有时与DecimalField类混合在一起。尽管它们都代表实数，但它们代表的数字不同。 FloatField在内部使用Python的float类型，而DecimalField使用Python的Decimal类型。有关这两者之间的区别的信息，请参阅Python的十进制模块的文档。

ImageField

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

从FileField继承所有的属性和方法，但也验证上传的对象是一个有效的图像。
除了可用于FileField的特殊属性外，ImageField还具有高度和宽度属性。
为了便于查询这些属性，ImageField有两个额外的可选参数：

ImageField.height_field
每次保存模型实例时将使用图像的高度自动填充模型字段的名称。
ImageField.width_field
每次保存模型实例时将使用图像宽度自动填充模型字段的名称。

需要Pillow库。
ImageField实例在数据库中被创建为默认最大长度为100个字符的varchar列。与其他字段一样，您可以使用max_length参数更改最大长度。
该字段的默认表单部件是ClearableFileInput。

IntegerField

class IntegerField(**options)

一个整数字段。在Django支持的所有数据库中，值从-2147483648到2147483647都是安全的。当localize为False或TextInput时，此字段的默认表单窗口小部件为NumberInput。

GenericIPAddressField

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

以字符串格式（例如192.0.2.30或2a02:42fe::4）的IPv4或IPv6地址。该字段的默认表单窗口小部件是一个TextInput。

IPv6地址规范化遵循RFC 4291#section-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。默认是禁用的。只能在协议设置为both时使用。
如果允许空白值，则必须允许空值，因为空白值存储为空。

NullBooleanField

class NullBooleanField(**options)

类似一个BooleanField，但允许NULL作为其中一个选项。使用这个而不是一个null = True的BooleanField。此字段的默认表单窗口小部件是NullBooleanSelect。

PositiveIntegerField

class PositiveIntegerField(**options)

类似IntegerField，但必须是正数或零(0)。在Django支持的所有数据库中，从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，则Django将使用默认长度50。

暗示将Field.db_index设置为True。

根据其他值的值自动预填充SlugField通常是有用的。您可以使用prepopulated_fields在管理员中自动执行此操作。

SlugField.allow_unicode

如果为True，则该字段除ASCII字母外还接受Unicode字母。默认为False。

SmallIntegerField

class SmallIntegerField(**options)

像IntegerField一样，但只允许在某个（数据库相关）点下的值。在Django支持的所有数据库中，-32768到32767的值是安全的。

TextField

class TextField(**options)

一个大的文本字段。该字段的默认表单窗口小部件是一个Textarea。
如果你指定了max_length属性，它将会反映在自动生成的表单字段的Textarea小部件中。但是，它不是在模型或数据库级别执行的。为此使用CharField。

TimeField

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

一个时间，用Python表示一个datetime.time实例。接受与DateField相同的自动填充选项。

该字段的默认表单窗口小部件是一个TextInput。管理员添加了一些JavaScript快捷方式。

URLField

class URLField(max_length=200, **options)

一个符合URL标准的CharField。
该字段的默认表单窗口小部件是一个TextInput。
像所有CharField子类一样，URLField接受可选的max_length参数。如果您不指定max_length，则使用默认值200。

UUIDField

class UUIDField(**options)

用于存储通用唯一标识符的字段。使用Python的UUID类。在PostgreSQL上使用时，它将以uuid数据类型存储，否则以char(32)存储。
对于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

请注意，可调用（使用括号省略）传递给默认值，而不是UUID的实例。