本文档包含 Field
包括 field options 和 field types Django提供。
参见
如果内置字段不起作用,您可以尝试 django-localflavor (documentation 其中包含对特定国家和文化有用的各种代码片段。
而且,你可以很容易地 write your own custom model fields .
备注
从技术上讲,这些模型在 django.db.models.fields
但为了方便起见,它们被进口到 django.db.models
标准惯例是使用 from django.db import models
并将字段引用为 models.<Foo>Field
.
以下参数可用于所有字段类型。所有都是可选的。
null
¶如果 True
,django将空值存储为 NULL
在数据库中。默认是 False
.
避免使用 null
基于字符串的字段,如 CharField
和 TextField
. 如果基于字符串的字段 null=True
,这意味着它有两个可能的“无数据”值: NULL
和空字符串。在大多数情况下,“无数据”有两个可能的值是多余的;django约定使用空字符串,而不是 NULL
. 一个例外是 CharField
都有 unique=True
和 blank=True
集合。在这种情况下, null=True
在保存多个值为空的对象时,需要避免唯一的约束冲突。
对于基于字符串和非基于字符串的字段,还需要设置 blank=True
如果您希望允许表单中的空值, null
参数只影响数据库存储(请参见 blank
)
备注
使用Oracle数据库后端时,该值 NULL
将存储以表示空字符串,而不考虑此属性。
blank
¶如果 True
,该字段允许为空。默认是 False
.
注意这与 null
. null
纯粹与数据库相关,而 blank
是否与验证相关。如果字段有 blank=True
,表单验证将允许输入空值。如果字段有 blank=False
,字段将是必需的。
choices
¶下面描述的格式的映射或可迭代,用作此字段的选项。如果给出了选择,这些选择是由 model validation 默认的表单小部件将是包含这些选项的选择框,而不是标准文本字段。
如果给出了映射,则关键元素是要在模型上设置的实际值,第二个元素是人类可读的名称。例如::
YEAR_IN_SCHOOL_CHOICES = {
"FR": "Freshman",
"SO": "Sophomore",
"JR": "Junior",
"SR": "Senior",
"GR": "Graduate",
}
您还可以传递一个 sequence 由恰好包含两个项的可迭代项组成(例如 [(A1, B1), (A2, B2), …]
)。每个元组中的第一个元素是要在模型上设置的实际值,第二个元素是人类可读的名称。例如::
YEAR_IN_SCHOOL_CHOICES = [
("FR", "Freshman"),
("SO", "Sophomore"),
("JR", "Junior"),
("SR", "Senior"),
("GR", "Graduate"),
]
choices
也可以定义为不需要任何参数并返回上述任何格式的Callable。例如::
def get_currencies():
return {i: i for i in settings.CURRENCIES}
class Expense(models.Model):
amount = models.DecimalField(max_digits=10, decimal_places=2)
currency = models.CharField(max_length=3, choices=get_currencies)
传递一个可调用的 choices
例如,在以下情况下可以特别方便:
受I/O限制的操作(可能会被缓存)的结果,例如查询同一或外部数据库中的表,或访问静态文件中的选项。
列表基本稳定,但可能会随时间或项目的不同而变化。这一类别的例子是使用第三方应用程序,这些应用程序提供众所周知的价值清单,如货币、国家、语言、时区等。
添加了对映射和可计算的支持。
通常,最好在模型类内定义选项,并为每个值定义一个适当命名的常量:
from django.db import models
class Student(models.Model):
FRESHMAN = "FR"
SOPHOMORE = "SO"
JUNIOR = "JR"
SENIOR = "SR"
GRADUATE = "GR"
YEAR_IN_SCHOOL_CHOICES = {
FRESHMAN: "Freshman",
SOPHOMORE: "Sophomore",
JUNIOR: "Junior",
SENIOR: "Senior",
GRADUATE: "Graduate",
}
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}
虽然您可以在模型类之外定义一个选项列表并引用它,但是在模型类中定义每个选项的选项和名称会将所有这些信息保存在使用它的类中,并有助于引用这些选项(例如, Student.SOPHOMORE
会在任何地方工作 Student
模型已导入)。
您还可以将可用的选项收集到可用于组织目的的命名组中:
MEDIA_CHOICES = {
"Audio": {
"vinyl": "Vinyl",
"cd": "CD",
},
"Video": {
"vhs": "VHS Tape",
"dvd": "DVD",
},
"unknown": "Unknown",
}
映射的关键是要应用到组的名称,值是该组中的选项,由字段值和选项的人类可读名称组成。分组选项可以与单个映射中的未分组选项组合(例如 "unknown"
选项)。
您还可以使用序列,例如二元组列表:
MEDIA_CHOICES = [
(
"Audio",
(
("vinyl", "Vinyl"),
("cd", "CD"),
),
),
(
"Video",
(
("vhs", "VHS Tape"),
("dvd", "DVD"),
),
),
("unknown", "Unknown"),
]
注意,选择可以是任何序列对象——不一定是列表或元组。这允许您动态地构造选项。但如果你发现自己被黑客攻击 choices
为了保持动态,最好使用适当的数据库表 ForeignKey
. choices
用于静态数据,如果有变化的话,不会太大。
备注
每次按 choices
变化。
对于具有以下属性的每个模型字段 choices
设置后,Django将把选择标准化为一个二元组列表,并添加一个方法来检索字段当前值的人类可读名称。看见 get_FOO_display()
在数据库API文档中。
除非 blank=False
与一个 default
然后是一个包含 "---------"
将使用“选择”框呈现。若要重写此行为,请将元组添加到 choices
包含 None
例如 (None, 'Your String For Display')
. 或者,可以使用空字符串而不是 None
这是有意义的-例如 CharField
.
此外,Django还提供了枚举类型,您可以将其子类化以简洁的方式定义选项:
from django.utils.translation import gettext_lazy as _
class Student(models.Model):
class YearInSchool(models.TextChoices):
FRESHMAN = "FR", _("Freshman")
SOPHOMORE = "SO", _("Sophomore")
JUNIOR = "JR", _("Junior")
SENIOR = "SR", _("Senior")
GRADUATE = "GR", _("Graduate")
year_in_school = models.CharField(
max_length=2,
choices=YearInSchool,
default=YearInSchool.FRESHMAN,
)
def is_upperclass(self):
return self.year_in_school in {
self.YearInSchool.JUNIOR,
self.YearInSchool.SENIOR,
}
这些工作类似于 enum
来自Python的标准库,但经过一些修改:
枚举成员值是构造具体数据类型时使用的参数元组。Django支持在此元组的末尾添加额外的字符串值以用作人类可读的名称,或者 label
。这个 label
可以是懒惰的可翻译字符串。因此,在大多数情况下,成员值将是 (value, label)
2-元组。有关详情,请参阅以下内容 an example of subclassing choices 使用更复杂的数据类型。如果未提供元组,或者最后一项不是(惰性)字符串,则 label
是 automatically generated 从成员名称。
A .label
属性添加到值上,以返回人类可读的名称。
许多定制属性被添加到枚举类中-- .choices
, .labels
, .values
,以及 .names
--使访问枚举的这些单独部分的列表变得更容易。
警告
这些属性名称不能用作成员名称,因为它们会发生冲突。
使用 enum.unique()
强制执行,以确保不能多次定义值。在选择一个领域时,这不太可能是预期的。
注意使用 YearInSchool.SENIOR
, YearInSchool['SENIOR']
或 YearInSchool('SR')
访问或查找枚举成员按预期工作,就像 .name
和 .value
成员的属性。
如果您不需要翻译人类可读的名称,您可以从成员名称推断它们(用空格替换下划线并使用标题大小写):
>>> class Vehicle(models.TextChoices):
... CAR = "C"
... TRUCK = "T"
... JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'
由于枚举值需要是整数的情况非常常见,Django提供了一个 IntegerChoices
班级。例如::
class Card(models.Model):
class Suit(models.IntegerChoices):
DIAMOND = 1
SPADE = 2
HEART = 3
CLUB = 4
suit = models.IntegerField(choices=Suit)
还可以利用 Enum Functional API 需要注意的是,标签是按照上面突出显示的方式自动生成的:
>>> MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
>>> MedalType.choices
[('GOLD', 'Gold'), ('SILVER', 'Silver'), ('BRONZE', 'Bronze')]
>>> Place = models.IntegerChoices("Place", "FIRST SECOND THIRD")
>>> Place.choices
[(1, 'First'), (2, 'Second'), (3, 'Third')]
如果您需要对具体数据类型的支持,而不是 int
或 str
,您可以子类 Choices
混凝土和所需数据。 date
供使用 DateField
::
class MoonLandings(datetime.date, models.Choices):
APOLLO_11 = 1969, 7, 20, "Apollo 11 (Eagle)"
APOLLO_12 = 1969, 11, 19, "Apollo 12 (Intrepid)"
APOLLO_14 = 1971, 2, 5, "Apollo 14 (Antares)"
APOLLO_15 = 1971, 7, 30, "Apollo 15 (Falcon)"
APOLLO_16 = 1972, 4, 21, "Apollo 16 (Orion)"
APOLLO_17 = 1972, 12, 11, "Apollo 17 (Challenger)"
还有一些额外的注意事项:
枚举类型不支持 named groups .
因为具有具体数据类型的枚举要求所有值都与该类型匹配,因此重写 blank label 无法通过创建值为的成员来实现 None
. 相反,设置 __empty__
类的属性:
class Answer(models.IntegerChoices):
NO = 0, _("No")
YES = 1, _("Yes")
__empty__ = _("(Unknown)")
中直接使用枚举类型的支持 choices
已添加。
db_column
¶用于此字段的数据库列的名称。如果没有给出,Django将使用字段的名称。
如果您的数据库列名是SQL保留字,或者包含在python变量名中不允许使用的字符(尤其是连字符),那么就可以了。Django在后台引用列和表名。
db_comment
¶此字段要使用的数据库列的注释。对于那些可能没有查看Django代码的具有直接数据库访问权限的个人来说,它对于记录字段很有用。例如::
pub_date = models.DateTimeField(
db_comment="Date and time when the article was published",
)
db_default
¶此字段的数据库计算的默认值。它可以是文字值或数据库函数,例如 Now
**
created = models.DateTimeField(db_default=Now())
可以使用更复杂的表达式,只要它们由文字和数据库函数组成:
month_due = models.DateField(
db_default=TruncMonth(
Now() + timedelta(days=90),
output_field=models.DateField(),
)
)
数据库默认设置不能引用其他字段或模型。例如,这是无效的::
end = models.IntegerField(db_default=F("start") + 50)
如果两者都有 db_default
和 Field.default
都设置好了, default
在使用Python代码创建实例时将优先使用。 db_default
仍将在数据库级别设置,并将在ORM之外插入行或在迁移中添加新字段时使用。
db_index
¶如果 True
,将为此字段创建数据库索引。
db_tablespace
¶的名字 database tablespace 用于该字段的索引(如果该字段已编入索引)。默认值是项目的 DEFAULT_INDEX_TABLESPACE
设置,如果设置,或 db_tablespace
如果有的话。如果后端不支持索引的表空间,则忽略此选项。
default
¶字段的默认值。这可以是一个值或可调用对象。如果可调用,则每次创建新对象时都会调用它。
默认值不能是可变对象(模型实例, list
, set
等),作为对该对象同一实例的引用,将在所有新模型实例中用作默认值。相反,将所需的默认值包装在可调用文件中。例如,如果要指定默认值 dict
对于 JSONField
,使用函数:
def contact_default():
return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)
lambda
不能用于字段选项,如 default
因为他们不能 serialized by migrations . 有关其他注意事项,请参阅该文档。
对于像 ForeignKey
映射到模型实例的默认值应该是它们引用的字段的值。 (pk
除非 to_field
而不是模型实例。
创建新模型实例时使用默认值,但没有为字段提供值。当字段是主键时,当字段设置为 None
.
也可以使用在数据库级别设置缺省值 Field.db_default
。
editable
¶如果 False
,该字段将不会显示在管理员或任何其他 ModelForm
. 在 model validation . 默认是 True
.
error_messages
¶这个 error_messages
参数允许您重写字段将引发的默认消息。传入一个字典,其中的键与要重写的错误消息匹配。
错误消息键包括 null
, blank
, invalid
, invalid_choice
, unique
和 unique_for_date
. 为中的每个字段指定了其他错误消息键。 Field types 下面部分。
这些错误消息通常不会传播到表单。见 关于模型的考虑 error_messages .
help_text
¶要与表单小部件一起显示的额外“帮助”文本。它对文档很有用,即使表单上没有使用您的字段。
注意这个值是 not HTML以自动生成的表单转义。这允许您在 help_text
如果你愿意的话。例如::
help_text = "Please use the following format: <em>YYYY-MM-DD</em>."
或者,您可以使用纯文本和 django.utils.html.escape()
以转义任何HTML特殊字符。确保您转义任何可能来自不受信任用户的帮助文本,以避免跨站点脚本攻击。
primary_key
¶如果 True
,此字段是模型的主键。
如果您不指定 primary_key=True
对于模型中的任何字段,Django会自动添加一个字段来保存主键,因此您不需要设置 primary_key=True
除非您想要重写默认的主键行为。可在中为每个应用程序指定自动创建的主键字段类型 AppConfig.default_auto_field
或全局地在 DEFAULT_AUTO_FIELD
设置。有关详细信息,请参阅 自动主键字段 。
primary_key=True
暗示 null=False
和 unique=True
. 一个对象上只允许有一个主键。
主键字段是只读的。如果更改现有对象的主键值,然后保存它,则将在旧对象旁边创建一个新对象。
主键字段设置为 None
什么时候 deleting
一件物品。
unique
¶如果 True
,此字段在整个表中必须是唯一的。
这是在数据库级别和通过模型验证强制执行的。如果试图将具有重复值的模型保存到 unique
A域 django.db.IntegrityError
将由模型的 save()
方法。
此选项对除 ManyToManyField
和 OneToOneField
.
注意什么时候 unique
是 True
,您不需要指定 db_index
,因为 unique
意味着创建索引。
unique_for_date
¶将此设置为 DateField
或 DateTimeField
要求此字段对于日期字段的值是唯一的。
例如,如果您有字段 title
那有 unique_for_date="pub_date"
,那么django就不允许输入两个相同的记录 title
和 pub_date
.
请注意,如果将此设置为指向 DateTimeField
只考虑字段的日期部分。此外,什么时候 USE_TZ
是 True
,将在 current time zone 在保存对象时。
这是强制执行 Model.validate_unique()
在模型验证期间,但不是在数据库级别。如果有的话 unique_for_date
约束涉及不属于 ModelForm
(例如,如果其中一个字段列在 exclude
或有 editable=False
) Model.validate_unique()
将跳过该特定约束的验证。
unique_for_month
¶喜欢 unique_for_date
,但要求字段相对于月份是唯一的。
unique_for_year
¶喜欢 unique_for_date
和 unique_for_month
.
verbose_name
¶字段的可读名称。如果没有给出详细名称,Django将使用字段的属性名自动创建该名称,并将下划线转换为空格。见 Verbose field names .
validators
¶要为此字段运行的验证程序列表。见 validators documentation 更多信息。
AutoField
¶安 IntegerField
根据可用的ID自动递增。您通常不需要直接使用它;如果您不另外指定,主键字段将自动添加到您的模型中。见 自动主键字段 .
BigAutoField
¶64位整数,很像 AutoField
但它保证符合 1
到 9223372036854775807
.
BigIntegerField
¶64位整数,很像 IntegerField
但它保证符合 -9223372036854775808
到 9223372036854775807
. 此字段的默认表单小部件是 NumberInput
.
BinaryField
¶存储原始二进制数据的字段。它可以被分配 bytes
, bytearray
或 memoryview
.
默认情况下, BinaryField
集合 editable
到 False
,在这种情况下,它不能包含在 ModelForm
.
可选的。字段的最大长度(以字节为单位)。最大长度在Django的验证中使用 MaxLengthValidator
。
滥用 BinaryField
尽管您可能会考虑在数据库中存储文件,但在99%的情况下,考虑到这是一个糟糕的设计。这个字段是 not 适当的替代品 static files 处理。
BooleanField
¶真/假字段。
此字段的默认表单小部件是 CheckboxInput
或 NullBooleanSelect
如果 null=True
.
默认值为 BooleanField
是 None
什么时候? Field.default
未定义。
CharField
¶字符串字段,用于小到大的字符串。
对于大量文本,请使用 TextField
.
此字段的默认表单小部件是 TextInput
.
CharField
有以下额外的参数:
字段的最大长度(以字符为单位)。这个 max_length
在数据库级别和Django的验证中使用 MaxLengthValidator
。Django附带的所有数据库后端都需要它,但PostgreSQL除外,它支持无限制 VARCHAR
柱子。
备注
如果编写的应用程序必须可移植到多个数据库后端,则应注意对 max_length
对于一些后端。参考 database backend notes 有关详细信息。
可选。字段的数据库排序规则名称。
备注
排序规则名称没有标准化。因此,它不能跨多个数据库后端移植。
甲骨文公司
Oracle仅在 MAX_STRING_SIZE
数据库初始化参数设置为 EXTENDED
.
DateField
¶用python表示的日期 datetime.date
实例。有一些额外的可选参数:
每次保存对象时自动将字段设置为“现在”。用于“上次修改”时间戳。请注意,当前日期是 总是 已使用;您不仅可以覆盖默认值。
该字段仅在调用时自动更新 Model.save()
. 当以其他方式更新其他字段(如 QuerySet.update()
尽管您可以在这样的更新中为字段指定自定义值。
首次创建对象时自动将字段设置为“现在”。用于创建时间戳。请注意,当前日期是 总是 已使用;您不仅可以覆盖默认值。因此,即使在创建对象时为此字段设置了一个值,它也将被忽略。如果要修改此字段,请设置以下内容,而不是 auto_now_add=True
:
为了 DateField
: default=date.today
-来自 datetime.date.today()
为了 DateTimeField
: default=timezone.now
-来自 django.utils.timezone.now()
此字段的默认表单小部件是 DateInput
. 管理员添加了一个javascript日历和“今日”的快捷方式。包括一个附加的 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
以及决定如何在显示时处理从日期时间到日期的转换。
DateTimeField
¶日期和时间,用python表示 datetime.datetime
实例。采用与 DateField
.
此字段的默认表单小部件是 DateTimeInput
. 管理员使用两个单独的 TextInput
带有javascript快捷方式的小部件。
DecimalField
¶一个固定精度的十进制数,在python中用 Decimal
实例。它使用验证输入 DecimalValidator
.
具有以下特性 required 论据:
数字中允许的最大位数。请注意,此数字必须大于或等于 decimal_places
.
要与数字一起存储的小数位数。
例如,要将数字存储到 999.99
如果分辨率为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 . 你也应该意识到 SQLite limitations 十进制字段。
DurationField
¶用于存储时间段的字段-用python建模 timedelta
. 在PostgreSQL上使用时,使用的数据类型是 interval
在Oracle上,数据类型是 INTERVAL DAY(9) TO SECOND(6)
. 否则,A bigint
使用微秒。
备注
算术与 DurationField
在大多数情况下都有效。但是,在PostgreSQL以外的所有数据库上,比较 DurationField
运算 DateTimeField
实例将无法按预期工作。
EmailField
¶A CharField
检查该值是否为有效的电子邮件地址,使用 EmailValidator
.
FileField
¶文件上载字段。
备注
这个 primary_key
参数不受支持,如果使用,将引发错误。
具有以下可选参数:
此属性提供了一种设置上载目录和文件名的方法,可以通过两种方式进行设置。在这两种情况下,值都传递给 Storage.save()
方法。
如果指定字符串值或 Path
,可能包含 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风格的路径(带正斜杠)以传递给存储系统。这两个参数是:
论证 |
描述 |
---|---|
|
模型的实例,其中 在大多数情况下,此对象还没有保存到数据库中,因此如果它使用默认值 |
|
最初提供给文件的文件名。在确定最终目的地路径时,可以考虑,也可以不考虑。 |
例如::
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)
此字段的默认表单小部件是 ClearableFileInput
.
使用A FileField
或 ImageField
(见下文)在一个模型中,采取了几个步骤:
在您的设置文件中,您需要定义 MEDIA_ROOT
作为您希望Django存储上传文件的目录的完整路径。(出于性能考虑,这些文件不存储在数据库中。)定义 MEDIA_URL
作为该目录的基本公共URL。确保Web服务器的用户帐户可以写入此目录。
添加 FileField
或 ImageField
对于您的模型,定义 upload_to
指定子目录的选项 MEDIA_ROOT
用于上载的文件。
数据库中存储的所有内容都是指向文件的路径(相对于 MEDIA_ROOT
)你很可能想利用方便 url
Django提供的属性。例如,如果 ImageField
被称为 mug_shot
,可以获取模板中图像的绝对路径 {{{{ object.mug_shot.url }}}}
.
例如,说 MEDIA_ROOT
设置为 '/home/media'
和 upload_to
设置为 'photos/%Y/%m/%d'
. 这个 '%Y/%m/%d'
部分 upload_to
是 strftime()
格式化; '%Y'
是四位数的年份, '%m'
是两位数的月份和 '%d'
是两位数的一天。如果您在2007年1月15日上传一个文件,它将保存在目录中。 /home/media/photos/2007/01/15
.
如果要检索上载文件的磁盘文件名或文件大小,可以使用 name
和 size
属性;有关可用属性和方法的详细信息,请参见 File
类引用和 文档管理 主题指南。
备注
该文件作为在数据库中保存模型的一部分保存,因此在保存模型之前,不能依赖磁盘上使用的实际文件名。
上载文件的相对URL可以使用 url
属性。在内部,这调用 url()
底层的方法 Storage
类。
请注意,无论何时处理上传的文件,都应该密切关注上传位置以及上传的文件类型,以避免安全漏洞。 Validate all uploaded files 这样你就能确定这些文件就是你想的那样。例如,如果您盲目地允许某人在未经验证的情况下将文件上传到您的Web服务器的文档根目录中,则某人可以上传CGI或PHP脚本,并通过访问其在您网站上的URL来执行该脚本。不允许这样做。
另外请注意,即使是上载的HTML文件,由于它可以由浏览器执行(而不是由服务器执行),也可能造成等同于XSS或CSRF攻击的安全威胁。
FileField
实例在数据库中创建为 varchar
默认最大长度为100个字符的列。与其他字段一样,可以使用 max_length
参数。
FileField
and FieldFile
¶当您访问 FileField
在模型上,您将获得 FieldFile
作为访问基础文件的代理。
API FieldFile
镜子的 File
,有一个关键区别: The object wrapped by the class is not necessarily a wrapper around Python's built-in file object. 相反,它是围绕 Storage.open()
方法,可以是 File
对象,或者它可以是自定义存储的 File
应用程序编程接口。
除了继承自 File
如 read()
和 write()
, FieldFile
包括可用于与基础文件交互的几种方法:
文件名,包括根目录下的相对路径 Storage
相关联的 FileField
.
属性访问文件的本地文件系统路径的只读属性。 path()
方法的基础 Storage
班级。
基础的结果 Storage.size()
方法。
只读属性,通过调用 url()
底层的方法 Storage
类。
在指定的 mode
. 与标准的python不同 open()
方法,它不返回文件描述符。
由于在访问基础文件时会隐式打开它,因此可能不需要调用此方法,除非重置指向基础文件的指针或更改 mode
.
行为类似于标准的python file.close()
方法并关闭与此实例关联的文件。
此方法获取文件名和文件内容,并将它们传递给字段的存储类,然后将存储的文件与模型字段相关联。如果要手动将文件数据与 FileField
模型上的实例, save()
方法用于保持该文件数据。
采用两个必需的参数: name
文件的名称,以及 content
它是包含文件内容的对象。可选的 save
参数控制与此字段关联的文件更改后是否保存模型实例。默认为 True
.
请注意 content
参数应为的实例 django.core.files.File
,而不是python的内置文件对象。你可以构造一个 File
来自现有的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")
有关详细信息,请参阅 文档管理 .
删除与此实例关联的文件并清除字段上的所有属性。注意:此方法将在以下情况下关闭文件: delete()
被称为。
可选的 save
参数控制删除与此字段关联的文件后是否保存模型实例。默认为 True
.
请注意,删除模型时,不会删除相关文件。如果您需要清理孤立的文件,您需要自己处理它(例如,使用一个可以手动运行或计划通过cron定期运行的自定义管理命令)。
FilePathField
¶A CharField
其选择仅限于文件系统上某个目录中的文件名。有一些特别的论点,其中第一个是 必修的 :
必修的。指向目录的绝对文件系统路径 FilePathField
应该有自己的选择。例子: "/home/images"
.
path
也可以是可调用的,例如在运行时动态设置路径的函数。例子::
import os
from django.conf import settings
from django.db import models
def images_path():
return os.path.join(settings.LOCAL_FILE_DIR, "images")
class MyModel(models.Model):
file = models.FilePathField(path=images_path)
可选的。作为字符串的正则表达式, FilePathField
将用于筛选文件名。请注意,regex将应用于基文件名,而不是完整路径。例子: "foo.*\.txt$"
,它将与名为 foo23.txt
但不是 bar.txt
或 foo23.png
.
可选的。要么 True
或 False
True
. 指定是否应包括指定位置的文件。要么是这个,要么是 allow_folders
必须是 True
.
可选的。要么 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
¶在python中由 float
实例。
此字段的默认表单小部件是 NumberInput
什么时候? localize
是 False
或 TextInput
否则。
FloatField
vs. DecimalField
这个 FloatField
有时课程和 DecimalField
类。虽然它们都代表实数,但它们代表的数字不同。 FloatField
使用Python的 float
在内部键入,而 DecimalField
使用Python的 Decimal
类型。有关这两者之间的区别的信息,请参见 decimal
模块。
GeneratedField
¶始终根据模型中的其他字段计算的字段。此字段由数据库本身管理和更新。使用 GENERATED ALWAYS
SQL语法。
生成的列有两种:存储列和虚拟列。存储生成的列是在写入(插入或更新)时计算的,并占用存储空间,就像它是常规列一样。虚拟生成的列不占用存储空间,在读取时进行计算。因此,虚拟生成的列类似于视图,而存储的生成的列类似于实例化视图。
一个 Expression
由数据库用来在每次更改模型时自动设置字段值。
表达式应该是确定性的,并且仅引用模型内的字段(在同一数据库表中)。生成的字段不能引用其他生成的字段。数据库后端可以施加进一步的限制。
用于定义字段数据类型的模型字段实例。
确定数据库列是否应像实际列一样占用存储空间。如果 False
,该列充当虚拟列,不占用数据库存储空间。
PostgreSQL仅支持持久列。Oracle仅支持虚拟列。
刷新数据
由于数据库始终计算值,因此必须重新加载对象才能在 save()
,例如,通过使用 refresh_from_db()
。
数据库限制
对于生成的字段,有许多特定于数据库的限制,Django不会对其进行验证,并且数据库可能会引发错误,例如,PostgreSQL要求将生成的列中引用的函数和运算符标记为 IMMUTABLE
。
你应该经常检查一下 expression
在您的数据库上支持。检查 MariaDB , MySQL , Oracle , PostgreSQL ,或 SQLite 医生。
GenericIPAddressField
¶字符串格式的IPv4或IPv6地址(例如 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
. 所有字符都转换为小写。
将有效输入限制为指定的协议。接受值为 'both'
(默认) 'IPv4'
或 'IPv6'
. 匹配不区分大小写。
解包IPv4映射地址,如 ::ffff:192.0.2.1
. 如果启用此选项,地址将解包到 192.0.2.1
. 默认设置为禁用。只能在以下情况下使用 protocol
设置为 'both'
.
如果允许空值,则必须允许空值,因为空值存储为空。
ImageField
¶从继承所有属性和方法 FileField
,但也验证上载的对象是有效的图像。
除了可用于 FileField
,一个 ImageField
也有 height
和 width
属性。
为了便于对这些属性的查询, ImageField
具有以下可选参数:
模型字段的名称,该字段将在每次保存模型实例时自动填充图像的高度。
模型字段的名称,该字段将在每次保存模型实例时自动填充图像的宽度。
需要 Pillow 类库。
ImageField
实例在数据库中创建为 varchar
默认最大长度为100个字符的列。与其他字段一样,可以使用 max_length
参数。
此字段的默认表单小部件是 ClearableFileInput
.
IntegerField
¶整数。值从 -2147483648
到 2147483647
在Django支持的所有数据库中都是安全的。
它使用 MinValueValidator
和 MaxValueValidator
根据默认数据库支持的值验证输入。
此字段的默认表单小部件是 NumberInput
什么时候? localize
是 False
或 TextInput
否则。
JSONField
¶用于存储JSON编码数据的字段。在python中,数据以其python本机格式表示:字典、列表、字符串、数字、布尔值和 None
.
JSONField
在MariaDB、MySQL、Oracle、PostgreSQL和SQLite(具有 JSON1 extension enabled )。
可选的 json.JSONEncoder
子类来序列化标准JSON序列化程序不支持的数据类型(例如。 datetime.datetime
或 UUID
). 例如,可以使用 DjangoJSONEncoder
班级。
默认为 json.JSONEncoder
.
可选的 json.JSONDecoder
子类以反序列化从数据库检索的值。值将采用自定义编码器选择的格式(通常是字符串)。反序列化可能需要考虑这样一个事实:您不能确定输入类型。例如,您有可能返回 datetime
这实际上是一个字符串,恰好是为 datetime
S
默认为 json.JSONDecoder
.
查询 JSONField
在数据库中,请参见 查询 JSONField .
缺省值
如果您为该字段指定一个 default
,确保它是可调用的,如 dict
类或每次都返回一个新对象的函数。错误地使用像这样的可变对象 default={}
或 default=[]
创建在所有实例之间共享的可变默认设置。
索引
Index
和 Field.db_index
两者都创建了一个B-tree索引,这在查询时不是特别有用 JSONField
. 仅在PostgreSQL上,您可以使用 GinIndex
那更合适。
PostgreSQL用户
PostgreSQL有两种基于本地JSON的数据类型: json
和 jsonb
. 它们之间的主要区别在于如何存储它们以及如何查询它们。波斯特雷克尔 json
字段存储为JSON的原始字符串表示形式,并且在根据键进行查询时必须动态解码。这个 jsonb
字段是基于允许索引的JSON的实际结构存储的。权衡是一个很小的额外成本,写给 jsonb
字段。 JSONField
使用 jsonb
.
PositiveBigIntegerField
¶像一个 PositiveIntegerField
,但只允许在特定(依赖于数据库)点下的值。值从 0
到 9223372036854775807
在Django支持的所有数据库中都是安全的。
PositiveIntegerField
¶像一个 IntegerField
,但必须为正或零 (0
)值从 0
到 2147483647
在Django支持的所有数据库中都是安全的。价值 0
因为向后兼容的原因而被接受。
PositiveSmallIntegerField
¶像一个 PositiveIntegerField
,但只允许在特定(依赖于数据库)点下的值。值从 0
到 32767
在Django支持的所有数据库中都是安全的。
SlugField
¶Slug 是报纸术语。slug是一个短标签,只包含字母、数字、下划线或连字符。它们通常用于URL。
像charfield一样,您可以指定 max_length
(阅读有关数据库可移植性和 max_length
在那一部分也是如此)。如果 max_length
未指定,Django将使用默认长度50。
暗示设置 Field.db_index
到 True
.
根据其他值的值自动预填充SlugField通常很有用。您可以在管理员中使用 prepopulated_fields
.
它使用 validate_slug
或 validate_unicode_slug
用于验证。
如果 True
字段除接受ASCII字母外还接受Unicode字母。默认为 False
.
SmallAutoField
¶像一个 AutoField
(依赖)数据库只允许某些值。值来自 1
到 32767
在Django支持的所有数据库中都是安全的。
SmallIntegerField
¶像一个 IntegerField
,但只允许在特定(依赖于数据库)点下的值。值从 -32768
到 32767
在Django支持的所有数据库中都是安全的。
TextField
¶大文本字段。此字段的默认表单小部件是 Textarea
.
max_length
属性,它将反映在 Textarea
自动生成表单字段的小部件。但是,它不是在模型或数据库级别强制执行的。使用A CharField
为此。
可选。字段的数据库排序规则名称。
备注
排序规则名称没有标准化。因此,它不能跨多个数据库后端移植。
甲骨文公司
Oracle不支持 TextField
.
TimeField
¶用python表示的时间 datetime.time
实例。接受与相同的自动填充选项 DateField
.
此字段的默认表单小部件是 TimeInput
. 管理员添加了一些javascript快捷方式。
URLField
¶A CharField
对于URL,由验证 URLValidator
.
此字段的默认表单小部件是 URLInput
.
像所有 CharField
子类, URLField
选择 max_length
参数。如果您不指定 max_length
,默认值为200。
UUIDField
¶用于存储通用唯一标识符的字段。使用Python的 UUID
班级。在PostgreSQL和MariaDB 10.7+上使用时,它存储在 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
注意,可调用(省略括号)传递给 default
,不是的实例 UUID
.
在PostgreSQL和MariaDB 10.7+上进行查找
vbl.使用 iexact
, contains
, icontains
, startswith
, istartswith
, endswith
,或 iendswith
对于没有连字符的值,在PostgreSQL上的查找不起作用,因为PostgreSQL和MariaDB 10.7+将它们存储在用连字符连接的UUID数据类型中。
Field
是表示数据库表列的抽象类。Django使用字段创建数据库表 (db_type()
)将python类型映射到数据库 (get_prep_value()
)反之亦然 (from_db_value()
)
因此,字段是不同django API中的基本部分,特别是, models
和 querysets
.
在模型中,字段被实例化为类属性并表示特定的表列,请参见 模型 . 它具有如下属性: null
和 unique
以及Django用于将字段值映射到数据库特定值的方法。
A Field
是的子类 RegisterLookupMixin
因此两者 Transform
和 Lookup
可以在上面注册以用于 QuerySet
s(例如) field_name__exact="foo"
)所有 built-in lookups 默认情况下注册。
所有Django的内置字段,例如 CharField
,是 Field
. 如果需要自定义字段,可以将任何内置字段子类化,也可以编写 Field
白手起家。无论哪种情况,请参见 如何创建自定义模型字段 .
字段的详细描述,例如 django.contrib.admindocs
应用。
描述的形式可以是:
description = _("String (up to %(max_length)s)")
从字段的 __dict__
.
实现 descriptor protocol 实例化并分配给模型实例属性。构造函数必须接受单个参数 Field
实例。重写get属性允许自定义此get类的行为。
地图A Field
对于特定于数据库的类型,Django公开了几种方法:
返回字段的数据库列数据类型,如 ForeignKey
和 OneToOneField
指的是 Field
,考虑到 connection
.
见 自定义数据库类型 用于自定义字段。
Django需要与数据库后端和字段进行交互的主要情况有三种:
查询数据库时(python value->database backend value)
从数据库加载数据时(数据库后端值->python值)
当它保存到数据库时(python value->database backend value)
查询时, get_db_prep_value()
和 get_prep_value()
使用:
value
是模型属性的当前值,该方法应返回已准备好用作查询参数的格式的数据。
见 将python对象转换为查询值 供使用。
皈依者 value
到后端特定的值。默认情况下,它返回 value
如果 prepared=True
和 get_prep_value()
如果是 False
.
见 将查询值转换为数据库值 供使用。
加载数据时, from_db_value()
使用:
将数据库返回的值转换为python对象。它与 get_prep_value()
.
此方法不用于大多数内置字段,因为数据库后端已经返回正确的python类型,或者后端本身进行转换。
expression
是一样的 self
.
见 将值转换为python对象 供使用。
备注
出于性能原因, from_db_value
不作为不需要它的字段(所有Django字段)的no-op实现。因此你不能调用 super
在你的定义中。
储蓄时, pre_save()
和 get_db_prep_save()
使用:
一样 get_db_prep_value()
,但当字段值必须为 保存的 到数据库。默认情况下返回 get_db_prep_value()
.
在之前调用的方法 get_db_prep_save()
在保存之前准备值(例如 DateField.auto_now
)
model_instance
此字段所属的实例和 add
是否首次将实例保存到数据库中。
它应该从返回适当属性的值 model_instance
对于这个领域。属性名在中 self.attname
(这是由 Field
)
见 保存前预处理值 供使用。
字段通常以不同的类型接收它们的值,可以是序列化的,也可以是表单的。
将该值转换为正确的python对象。它的作用与 value_to_string()
,也被称为 clean()
.
见 将值转换为python对象 供使用。
除了保存到数据库之外,字段还需要知道如何序列化其值:
返回给定模型实例的字段值。
这种方法经常被 value_to_string()
.
皈依者 obj
一个字符串。用于序列化字段的值。
见 正在转换字段数据以进行序列化 供使用。
使用时 model forms
, the Field
需要知道它应该用哪个表单域表示:
返回默认值 django.forms.Field
这个领域的 ModelForm
.
默认情况下,如果两者都是 form_class
和 choices_form_class
是 None
,它使用 CharField
. 如果现场有 choices
和 choices_form_class
未指定,它使用 TypedChoiceField
.
见 为模型字段指定窗体字段 供使用。
Field
实现 lookup registration API 。该API可用于定制可用于字段类及其实例的查找,以及如何从字段获取查找。
每个 Field
实例包含几个允许自省其行为的属性。使用这些属性而不是 isinstance
检查何时需要编写依赖于字段功能的代码。这些属性可以与 Model._meta API 缩小对特定字段类型的搜索范围。自定义模型字段应实现这些标志。
指示是否自动创建字段的布尔标志,例如 OneToOneField
由模型继承使用。
指示字段是否有关联的数据库列的布尔标志。
指示字段是否用于支持另一个非隐藏字段的功能(例如 content_type
和 object_id
组成一个 GenericForeignKey
)这个 hidden
标志用于区分构成模型上字段的公共子集的内容与模型上的所有字段。
备注
Options.get_fields()
默认情况下排除隐藏字段。传球 include_hidden=True
返回结果中的隐藏字段。
布尔标志,指示字段是否包含对一个或多个其他模型的功能引用(例如 ForeignKey
, ManyToManyField
, OneToOneField
等)。
返回定义字段的模型。如果在模型的超类上定义了字段, model
将引用超类,而不是实例的类。
这些属性用于查询关系的基数和其他详细信息。这些属性存在于所有字段中;但是,它们只具有布尔值(而不是 None
)如果字段是关系类型 (Field.is_relation=True
)
布尔标志,即 True
如果字段有多对多关系; False
否则。Django中唯一包含的字段 True
是 ManyToManyField
.
布尔标志,即 True
如果字段有多对一关系,例如 ForeignKey
; False
否则。
布尔标志,即 True
如果字段有一对多关系,例如 GenericRelation
或者A的反面 ForeignKey
; False
否则。
布尔标志,即 True
如果字段有一对一关系,例如 OneToOneField
; False
否则。
指向与字段相关的模型。例如, Author
在里面 ForeignKey(Author, on_delete=models.CASCADE)
. 这个 related_model
对于一个 GenericForeignKey
总是 None
.
12月 18, 2023