模型字段参考¶
本文档包含 Field
类的所有 API 参考,包括 字段选项 和 字段类型。
See also
If the built-in fields don't do the trick, you can try django-localflavor (documentation), which contains assorted pieces of code that are useful for particular countries and cultures.
当然,你也可以简单的 编写自定义模型字段。
Note
Fields are defined in django.db.models.fields
, but for convenience
they're imported into django.db.models
. The standard convention is
to use from django.db import models
and refer to fields as
models.<Foo>Field
.
字段选项¶
以下参数对所以字段类型均有效,且是可选的。
null
¶
- 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
)。
Note
当使用 Oracle 数据库后端时,不管这个属性是什么,都会存储 NULL
值来表示空字符串。
blank
¶
- Field.blank¶
如果是 True
,该字段允许为空。默认为 False
。
注意,这与 null
不同。 null
纯属数据库相关,而 blank
则与验证相关。如果一个字段有 blank=True
,表单验证将允许输入一个空值。如果一个字段有 blank=False
,则该字段为必填字段。
choices
¶
一个以下述格式的映射或可迭代对象,用作该字段的选项。如果提供了选项,它们将被 模型验证 强制执行,并且默认的表单小部件将是一个选择框,其中包含这些选项,而不是标准的文本字段。
如果提供了映射,键元素是要设置在模型上的实际值,第二个元素是可读的人类名称。例如:
YEAR_IN_SCHOOL_CHOICES = {
"FR": "Freshman",
"SO": "Sophomore",
"JR": "Junior",
"SR": "Senior",
"GR": "Graduate",
}
你还可以传递一个包含自身由两个项目的可迭代对象的 序列 (例如,[(A1, B1), (A2, B2), …]
)。每个元组中的第一个元素是要设置在模型上的实际值,第二个元素是可读的人类名称。例如:
YEAR_IN_SCHOOL_CHOICES = [
("FR", "Freshman"),
("SO", "Sophomore"),
("JR", "Junior"),
("SR", "Senior"),
("GR", "Graduate"),
]
choices
也可以定义为一个可调用对象,它不需要参数并返回上述任何格式之一。例如:
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
可以特别方便:
将可调用对象传递给
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"
选项)。
你还可以使用一个序列,例如,一个包含 2 元组的列表:
MEDIA_CHOICES = [
(
"Audio",
(
("vinyl", "Vinyl"),
("cd", "CD"),
),
),
(
"Video",
(
("vhs", "VHS Tape"),
("dvd", "DVD"),
),
),
("unknown", "Unknown"),
]
请注意,选择可以是任何序列对象——不一定是列表或元组。这让你可以动态地构造选择。但是如果你发现自己把 chips
魔改成动态的,你可能最好使用一个合适的的带有 ForeignKey
的数据库表。 chips
是用于静态数据的,如果有的话,不应该有太大的变化。
Note
每当 choices
的顺序变动时将会创建新的迁移。
对于每个具有 choices
设置的模型字段,Django 将规范化选择项为一个 2-元组的列表,并添加一个方法来获取字段当前值的可读名称。请参阅数据库 API 文档中的 get_FOO_display()
。
除非 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,
}
这些工作类似于 Python 标准库中的 enum
,但是做了一些修改。
枚举成员的值是用于构造具体数据类型的参数元组。Django 支持在此元组的末尾添加额外的字符串值,用作可读名称或
label
。这个label
可以是懒惰可翻译的字符串。因此,在大多数情况下,成员值将是一个(value, label)
的 2-元组。请参阅下面的示例,了解使用更复杂的数据类型来进行选择的 子类化选择项的示例。如果未提供元组,或者最后一项不是(懒惰)字符串,则从成员名称中 自动生成label
。在值上添加
.label
属性,以返回人类可读的名称。一些自定义属性被添加到枚举类中——
.choices
、.labels
、.values
和.names
——以便更容易访问这些枚举的各个部分的列表。Warning
这些属性名称不能作为成员名称使用,因为它们会发生冲突。
强制使用
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)"
还有一些注意事项需要注意:
db_column
¶
- Field.db_column¶
这个字段要使用的数据库列名。如果没有给出列名,Django 将使用字段名。
如果你的数据库列名是 SQL 的保留字,或者包含了 Python 变量名中不允许的字符——特别是连字符——那也没关系。Django 会在幕后引用列名和表名。
db_comment
¶
- Field.db_comment¶
用于此字段的数据库列的注释。对于具有直接数据库访问权限但可能不查看您的 Django 代码的人来说,这非常有用。例如:
pub_date = models.DateTimeField(
db_comment="Date and time when the article was published",
)
db_default
¶
- Field.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
,在 Python 代码中创建实例时 default
会优先生效。db_default
仍然会在数据库级别设置,并且在使用 ORM 之外插入行或在迁移中添加新字段时仍然会使用它。
If a field has a db_default
without a default
set and no value is
assigned to the field, a DatabaseDefault
object is returned as the field
value on unsaved model instances. The actual value for the field is determined
by the database when the model instance is saved.
db_index
¶
- Field.db_index¶
如果是 True
,将为该字段创建数据库索引。
db_tablespace
¶
如果这个字段有索引,那么要为这个字段的索引使用的 数据库表空间 的名称。默认是项目的 DEFAULT_INDEX_TABLESPACE
设置(如果有设置),或者是模型的 db_tablespace
(如果有)。如果后端不支持索引的表空间,则忽略此选项。
default
¶
- Field.default¶
该字段的默认值。可以是一个值或者是个可调用的对象,如果是个可调用对象,每次实例化模型时都会调用该对象。
默认值不能是一个可更改的对象(模型实例、list
、set
等),因为对该对象同一实例的引用将被用作所有新模型实例的缺省值。相反,将所需的默认值包裹在一个可调用对象中。例如,如果你想为 JSONField
指定一个默认的 dict
,使用一个函数:
def contact_default():
return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)
lambda
不能用于 default
等字段选项,因为它们不能被 迁移序列化。其他注意事项见该文档。
对于像 ForeignKey
这样映射到模型实例的字段,默认应该是它们引用的字段的值(默认是 pk
除非 to_field
被设置了),而不是模型实例。
当创建新的模型实例且没有为该字段提供值时,使用默认值。当字段是主键时,当字段设置为``None`` 时,也使用默认值。
默认值也可以在数据库级别使用 Field.db_default
来设置。
editable
¶
- Field.editable¶
如果是 False
,该字段将不会在管理或任何其他 ModelForm
中显示。在 模型验证 中也会跳过。默认为 True
。
error_messages
¶
error_messages
参数可以让你覆盖该字段引发的默认消息。传入一个与你想覆盖的错误信息相匹配的键值的字典。
错误信息键包括 null
、blank
、invalid
、invalid_choice
、unique
和 unique_for_date
。在下面的 字段类型 一节中为每个字段指定了额外的错误信息键。
这些错误信息通常不会传播到表单中。参见 有关模型的 error_messages 的注意事项。
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 特殊字符。确保你转义任何可能来自不受信任的用户的帮助文本,以避免跨站脚本攻击。
primary_key
¶
- Field.primary_key¶
如果设置为 True
,将该字段设置为该模型的主键。
如果你没有为模型中的任何字段指定 primary_key=True
,Django 会自动添加一个字段来保存主键,所以你不需要在任何字段上设置 primary_key=True,除非你想覆盖默认主键行为。自动创建的主键字段的类型可以在 AppConfig.default_auto_field
中为每个应用程序指定,或者在 DEFAULT_AUTO_FIELD
配置中全局指定。更多信息,请参阅 自动设置主键。
primary_key=True
意味着 null=False
和 unique=True
。一个对象只允许有一个主键。
主键字段是只读的。如果您改变了现有对象的主键值,然后将其保存,则会在旧对象旁边创建一个新对象。
主键字段在 deleting
对象时设置为 None
。
unique
¶
如果设置为 True
,这个字段必须在整个表中保持值唯一。
这是在数据库级别和模型验证中强制执行的。如果你试图保存一个在 unique
字段中存在重复值的模型,模型的 save()
方法将引发 django.db.IntegrityError
。
除了 ManyToManyField
和 OneToOneField
之外,该选项对所有字段类型有效。
请注意,当 unique
为 True
时,你不需要指定 db_index
,因为 unique
意味着创建一个索引。
unique_for_date
¶
- Field.unique_for_date¶
将其设置为 DateField
或 DateTimeField
的名称,要求该字段的日期字段值是唯一的。
例如,如果你的字段 title
有 unique_for_date="pub_date"
,那么 Django 就不允许输入两条相同 title
和 pub_date
的记录。
请注意,如果将其设置为指向 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_fordate
和 unique_formonth
。
verbose_name
¶
- Field.verbose_name¶
字段的一个人类可读名称,如果没有给定详细名称,Django 会使用字段的属性名自动创建,并将下划线转换为空格。参见 详细字段名。
validators
¶
要为该字段运行的验证器列表。更多信息请参见 验证器文档。
字段类型¶
AutoField
¶
一个 IntegerField
,根据可用的 ID 自动递增。你通常不需要直接使用它;如果你没有指定,主键字段会自动添加到你的模型中。参见 自动设置主键。
BigAutoField
¶
一个 64 位整数,与 AutoField
很相似,但保证适合 1
到 9223372036854775807
的数字。
BigIntegerField
¶
一个 64 位的整数,和 IntegerField
很像,只是它保证适合从 -9223372036854775808
到 9223372036854775807
的数字。该字段的默认表单部件是一个 NumberInput
。
BinaryField
¶
一个用于存储原始二进制数据的字段。可以指定为 bytes
、bytearray
或 memoryview
。
默认情况下,BinaryField
将 ediditable`
设置为 False
,在这种情况下,它不能被包含在 ModelForm
中。
- BinaryField.max_length¶
可选项。字段的最大长度(以字节为单位)。Django 在验证时使用
MaxLengthValidator
来强制执行最大长度。
滥用 BinaryField
虽然你可能会想到在数据库中存储文件,但考虑到这在99%的情况下是糟糕的设计。这个字段 不能 代替正确的 静态文件 处理。
BooleanField
¶
一个 true/false 字段。
该字段的默认表单部件是 CheckboxInput
,或者如果 null=True
则是 NullBooleanSelect
。
当 Field.default
没有定义时,BooleanField
的默认值是 None
。
CharField
¶
一个字符串字段,适用于小到大的字符串。
对于大量的文本,使用 TextField
。
该字段的默认表单部件是一个 TextInput
。
CharField
具有以下额外参数:
- CharField.max_length¶
字段的最大长度(以字符为单位)。
max_length
在数据库级别和在 Django 的验证中使用MaxLengthValidator
来强制执行。除了 PostgreSQL 支持无限``VARCHAR``列外,它对于 Django 包含的所有数据库后端都是必需的。Note
如果你编写的应用程序必须可移植到多个数据库后端,你应该意识到,有些后端对
max_length
有限制。详情请参考 数据库后端注释。
- CharField.db_collation¶
可选的。该字段的数据库字符序名称。
Note
字符序名称是不标准化的。因此,这将无法在多个数据库后端之间进行移植。
Oracle
Oracle 只有在
MAX_STRING_SIZE
数据库初始化参数被设置为EXTENDED
时,才支持字符序。
DateField
¶
一个日期,在 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()
该字段的默认表单部件是一个 DateInput
。管理中增加了一个 JavaScript 日历,以及“今天”的快捷方式。包含一个额外的 invalid_date
错误信息键。
auto_now_add
、auto_now
和 default
选项是相互排斥的。这些选项的任何组合都会导致错误。
Note
目前,将 auto_now
或 auto_now_add
设置为 True
,将导致该字段设置为 editable=False
和 blank=True
。
Note
auto_now
和 auto_now_add
选项将始终使用创建或更新时 默认时区 的日期。如果你需要一些不同的东西,你可能需要考虑使用你自己的可调用的默认值,或者覆盖 save()
而不是使用 auto_now
或 auto_now_add
;或者使用 DateTimeField
而不是 DateField
,并决定如何在显示时间处理从日期时间到日期的转换。
Warning
Always use DateField
with a datetime.date
instance.
If you have a datetime.datetime
instance, it's recommended to convert
it to a datetime.date
first. If you don't, DateField
will
localize the datetime.datetime
to the default timezone and convert it to a datetime.date
instance, removing its time component. This is true for both storage and
comparison.
DateTimeField
¶
一个日期和时间,在 Python 中用一个 datetime.datetime
实例表示。与 DateField
一样,使用相同的额外参数。
该字段的默认表单部件是一个单独的 DateTimeInput
。管理中使用两个单独的 TextInput
部件,并使用 JavaScript 快捷方式。
Warning
Always use DateTimeField
with a datetime.datetime
instance.
If you have a datetime.date
instance, it's recommended to convert it to
a datetime.datetime
first. If you don't, DateTimeField
will
use midnight in the default timezone for
the time component. This is true for both storage and comparison. To
compare the date portion of a DateTimeField
with a
datetime.date
instance, use the date
lookup.
DecimalField
¶
一个固定精度的十进制数,在 Python 中用一个 Decimal
实例来表示。它使用 DecimalValidator
验证输入。
有以下 必需 参数:
- DecimalField.max_digits¶
数字中允许的最大位数。请注意,这个数字必须大于或等于
decimal_places
。
- DecimalField.decimal_places¶
与数字一起存储的小数位数。
例如,要存储最高为 999.99
的数字,精度为小数点后 2 位,你可以使用:
models.DecimalField(..., max_digits=5, decimal_places=2)
并以 10 位小数的精度来存储最多约 10 亿的数字:
models.DecimalField(..., max_digits=19, decimal_places=10)
当 localize
为 False
时是 NumberInput
否则,该字段的默认表单部件是 TextInput
。
Note
关于 FloatField
和 DecimalField
类之间差异的更多信息,请参见 FloatField vs. DecimalField。你还应该注意小数字段的 SQLite 限制。
DurationField
¶
一个用于存储时间段的字段——在 Python 中用 timedelta
建模。当在 PostgreSQL 上使用时,使用的数据类型是 interval
,在 Oracle 上使用的数据类型是 INTERVAL DAY(9) TO SECOND(6)
。否则使用微秒的 bigint
。
Note
DurationField
的算术在大多数情况下是可行的。但在 PostgreSQL 以外的所有数据库中,将 DurationField
的值与 DateTimeField
实例上的算术进行比较,将无法达到预期的效果。
EmailField
¶
一个 CharField
,使用 EmailValidator
来检查该值是否为有效的电子邮件地址。
FileField
¶
一个文件上传字段
Note
primary_key
参数不支持,如果使用,会引起错误。
具有以下可选参数:
- FileField.upload_to¶
这个属性提供了一种设置上传目录和文件名的方式,可以有两种设置方式。在这两种情况下,值都会传递给
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 风格的路径(带斜线),以便传给存储系统。这两个参数是:参数
描述
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)
该字段的默认表单部件是一个 ClearableFileInput
。
在模型中使用 FileField
或 ImageField
(见下文)需要几个步骤:
在你的配置文件中,你需要将
MEDIA_ROOT
定义为你希望 Django 存储上传文件的目录的完整路径。(为了提高性能,这些文件不会存储在数据库中。)将MEDIA_URL
定义为该目录的基本公共 URL。确保这个目录是可以被网络服务器的用户账户写入的。将
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
目录下。
如果你想检索上传文件的盘上文件名,或者文件的大小,可以分别使用 name
和 size
属性;关于可用属性和方法的更多信息,请参见 File
类参考和 管理文件 主题指南。
Note
文件在数据库中作为保存模型的一部分,因此在模型被保存之前,不能依赖磁盘上使用的实际文件名。
上传的文件的相对 URL 可以通过 url
属性获得。内部调用底层 Storage
类的 store()
方法。
请注意,无论何时你处理上传的文件,你都应该密切注意你在哪里上传文件以及它们是什么类型的文件,以避免安全漏洞。 验证所有上传的文件 ,这样你就能确定文件是你认为的那样。例如,如果你盲目地让别人上传文件,而不进行验证,到你的网站服务器的文件根目录中,那么有人就可以上传 CGI 或 PHP 脚本,并通过访问你网站上的 URL 来执行该脚本。不要允许这样做。
另外要注意的是,即使是上传的 HTML 文件,由于可以被浏览器执行(虽然不能被服务器执行),也会造成相当于 XSS 或 CSRF 攻击的安全威胁。
FileField
实例在数据库中被创建为 varchar
列,默认最大长度为 100 个字符。与其他字段一样,你可以使用 max_length
参数改变最大长度。
FileField
和 FieldFile
¶
当你访问一个模型上的 FileField
时,你会得到一个 FieldFile
的实例作为访问底层文件的代理。
FieldFile
的 API 与 File
的 API 相同,但有一个关键的区别。该类所封装的对象不一定是 Python 内置文件对象的封装 相反,它是 Storage.open()
方法结果的封装,该方法可能是 File
对象,也可能是自定义存储对 File
API 的实现。
除了从 File
继承的 API,如 read()
和 write()
之外,FieldFile
还包括一些可以用来与底层文件交互的方法:
- FieldFile.name¶
文件名,包括从关联的 Storage
的根部开始的相对路径 FileField
。
一个只读属性,通过调用底层的 path()
方法,访问文件的本地文件系统路径。
底层 Storage.size()
方法的结果。
一个只读属性,通过调用底层 Storage
类的 Storage()
方法来访问文件的相对 URL。
以指定的 mode
打开或重新打开与该实例相关的文件。与标准的 Python open()
方法不同,它不返回一个文件描述符。
因为在访问底层文件时,底层文件是隐式打开的,所以除了重置底层文件的指针或改变 mode
之外,可能没有必要调用这个方法。
类似于标准的 Python file.close()
方法,关闭与该实例相关的文件。
这个方法接收一个文件名和文件内容,并将它们传递给字段的存储类,然后将存储的文件与模型字段关联。如果你想手动将文件数据与模型上的 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")
更多信息,请参见 管理文件。
删除与此实例相关的文件,并清除字段的所有属性。注意:如果在调用 delete()
时,文件恰好被打开,本方法将关闭该文件。
可选的 save
参数控制在删除与该字段相关的文件后是否保存模型实例。默认值为 True
。
请注意,当一个模型被删除时,相关文件不会被删除。如果你需要清理遗留文件,你需要自己处理(例如,使用自定义管理命令,可以手动运行或通过例如 cron 定期运行)。
FilePathField
¶
- class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)[source]¶
一个 CharField
,其选择仅限于文件系统中某个目录下的文件名。有一些特殊的参数,其中第一个参数是 必须的。
- FilePathField.path¶
必须的。一个目录的绝对文件系统路径,这个
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.match¶
可选。一个正则表达式,作为一个字符串,
FilePathField
将用于过滤文件名。请注意,正则表达式将被应用于基本文件名,而不是完整的路径。例如:"foo.*.txt$"
,它将匹配名为foo23.txt
的文件,但不匹配bar.txt
或foo23.png
。
- 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
¶
在 Python 中用一个 float
实例表示的浮点数。
当 localize
为 False
时是 NumberInput
否则,该字段的默认表单部件是 TextInput
。
FloatField
vs. DecimalField
FloatField
类有时会与 DecimalField
类混淆。虽然它们都表示实数,但它们表示的方式不同。FloatField
内部使用 Python 的 float
类型,而 DecimalField
则使用 Python 的 Decimal
类型。关于两者之间的区别,请参见 Python 的 decimal
模块的文档。
GeneratedField
¶
这是一个根据模型中的其他字段始终计算的字段。该字段由数据库自身进行管理和更新。使用 GENERATED ALWAYS
SQL 语法。
有两种类型的生成列:存储的和虚拟的。存储的生成列在写入(插入或更新)时进行计算,并占用存储空间,就像是普通列一样。虚拟生成列不占用存储空间,在读取时进行计算。因此,虚拟生成列类似于视图,而存储的生成列类似于物化视图。
- GeneratedField.expression¶
数据库使用的
Expression
在每次模型更改时自动设置字段值。这些表达式应该是确定性的,并且只引用模型内部(同一数据库表)的字段。生成的字段不能引用其他生成的字段。数据库后端可以强加更多的限制。
- GeneratedField.output_field¶
一个模型字段实例,用于定义字段的数据类型。
- GeneratedField.db_persist¶
确定数据库列是否应该占用存储空间,就像是一个真实的列一样。如果为
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 格式,如 ::fffff:192.0.2.0
。例如,2001:0::0:01
将被标准化为 2001::1
,::fffff:0a0a:0a0a
将被标准化为 ::fffff:10.10.10.10
。所有字符都转换为小写。
- GenericIPAddressField.protocol¶
将有效输入限制为指定协议。接受的值是
'both'
(默认)、'IPv4'
或'IPv6'
。匹配是不分大小写的。
- GenericIPAddressField.unpack_ipv4¶
解压 IPv4 映射地址,如
::fffff:192.0.2.1
。如果启用该选项,该地址将被解压为192.0.2.1
。默认为禁用。只有当protocol
设置为'both'
时才会启用。
如果允许空值,就必须允许 null 值,因为空值会被存储为 null。
ImageField
¶
- class ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)[source]¶
继承 FileField
的所有属性和方法,但也验证上传的对象是有效的图像。
除了 FileField
的特殊属性外, ImageField
也有 height
和 width
属性。
为了方便对这些属性进行查询,ImageField
具有以下可选参数:
- ImageField.height_field¶
Name of a model field which is auto-populated with the height of the image each time an image object is set.
- ImageField.width_field¶
Name of a model field which is auto-populated with the width of the image each time an image object is set.
Requires the pillow library.
ImageField
实例在数据库中创建为 varchar
列,默认最大长度为 100 个字符。与其他字段一样,你可以使用 max_length
参数改变最大长度。
该字段的默认表单部件是一个 ClearableFileInput
。
IntegerField
¶
一个整数。从 -2147483648
到 2147483647
的值在 Django 支持的所有数据库中都是安全的。
它使用 MinValueValidator
和 MaxValueValidator
根据默认数据库支持的值来验证输入。
当 localize
为 False
时是 NumberInput
否则,该字段的默认表单部件是 TextInput
。
JSONField
¶
一个用于存储 JSON 编码数据的字段。在 Python 中,数据以其 Python 本地格式表示:字典、列表、字符串、数字、布尔值和 None
。
JSONField
在 MariaDB、MySQL、Oracle、PostgreSQL 和 SQLite(启用了 JSON1 扩展)上都得到了支持。
- JSONField.encoder¶
一个可选的
json.JSONEncoder
子类,用于序列化标准 JSON 序列化器不支持的数据类型(例如datetime.datetime
或UUID
)。例如,你可以使用DjangoJSONEncoder
类。默认为
json.JSONEncoder
。
- JSONField.decoder¶
一个可选的
json.JSONDecoder
子类,用于反序列化从数据库中获取的值。该值将采用自定义编码器选择的格式(通常是字符串)。你的反序列化可能需要考虑到你无法确定输入类型的事实。例如,你有可能返回一个datetime
,实际上是一个字符串,而这个字符串恰好与datetime
选择的格式相同。默认为
json.JSONDecoder
。
要在数据库中查询 JSONField
,请看 查询 JSONField。
默认值
如果你给字段一个 default
,确保它是一个可调用对象,例如 dict
类或一个每次返回新对象的函数。不正确地使用可变对象,比如 default={}
或 default=[]
,会创建一个在所有实例之间共享的可变默认值。
索引
Index
和 Field.db_index
都创建了一个 B 树索引,在查询 JSONField
的时候并不是特别有用。仅在 PostgreSQL 上,可以使用 GinIndex
比较适合。
PostgreSQL 用户
PostgreSQL 有两种基于 JSON 的原生数据类型: json
和 jsonb
。它们之间的主要区别在于它们的存储方式和查询方式。PostgreSQL 的 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
进行验证。
- SlugField.allow_unicode¶
如果是
True
,该字段除了接受 ASCII 字母外,还接受 Unicode 字母。默认值为False
。
SmallAutoField
¶
就像一个 AutoField
,但只允许值在一定(依赖于数据库)的限制下。1
到 32767
的值在 Django 支持的所有数据库中都是安全的。
SmallIntegerField
¶
就像一个 IntegerField
,但只允许在某一特定(依赖于数据库的)点下取值。从 -32768
到 32767
的值在 Django 支持的所有数据库中都是安全的。
TextField
¶
一个大的文本字段。该字段的默认表单部件是一个 Textarea
。
如果你指定了 max_length
属性,它将反映在自动生成的表单字段的 Textarea
部件中。但是,它并没有在模型或数据库层面被强制执行。使用一个 CharField
来实现。
- TextField.db_collation¶
可选的。该字段的数据库字符序名称。
Note
字符序名称是不标准化的。因此,这将无法在多个数据库后端之间进行移植。
Oracle
Oracle 不支持
TextField
的字符序。
TimeField
¶
一个时间,在 Python 中用 datetime.time
实例表示。接受与 DateField
相同的自动填充选项。
该字段默认的表单部件t是一个 TimeInput
。管理中添加了一些 JavaScript 快捷方式。
URLField
¶
URL 的 CharField
,由 URLValidator
验证。
该字段的默认表单部件是一个 URLInput
。
像所有的 CharField
子类一样, URLField
接受可选的 max_length
参数。如果你没有指定 max_length
参数,则使用默认的 200。
UUIDField
¶
用于存储通用唯一标识符的字段。使用 Python 的 UUID
类。在 PostgreSQL 和 MariaDB 10.7+ 上使用时,将存储在 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
请注意,一个可调用对象(省略括号)被传递给 default
,而不是 UUID
的实例。
PostgreSQL 和 MariaDB 10.7+ 上的查找
在 PostgreSQL 上使用 iexact
、contains
、icontains
、startswith
、istartswith
、endswith
或 iendswith
查找对于没有连字符的值不起作用,因为 PostgreSQL 和 MariaDB 10.7+ 将它们存储在带连字符的 uuid 数据类型中。
字段 API 参考¶
- class Field[source]¶
Field
是一个抽象的类,表示一个数据库表的列。Django 使用字段来创建数据库表(db_type()
),将 Python 类型映射到数据库(get_prep_value()
),反之亦然(from_db_value()
)。因此,一个字段在不同的 Django API 中是一个基本的部分,特别是
models
和querysets
。在模型中,字段被实例化为一个类属性,并代表一个特定的表列,见 模型。它的属性有
null
和unique
,以及 Django 用来将字段值映射到数据库特定值的方法。Field
是RegisterLookupMixin
的子类,因此Transform
和Lookup
都可以在它上面注册,以便在QuerySet
中使用(例如:field_name__exact="foo"
)。所有 内置查找 都是默认注册的。所有 Django 的内置字段,如
CharField
,都是Field
的特殊实现。如果你需要一个自定义的字段,你可以对任何一个内置字段进行子类化,或者从头开始写一个Field
。无论哪种情况,请参见 编写自定义模型字段。- description¶
字段的详细描述,例如:
django.contrib.admindocs
应用程序。描述的形式可以是:
description = _("String (up to %(max_length)s)")
其中的参数是从字段的
__dict__
中插入的。
为了将一个
Field
映射到数据库的特定类型,Django 提供了一些方法:- rel_db_type(connection)[source]¶
返回指向
Field
的ForeignKey
和OneToOneField
等字段的数据库列数据类型,并考虑connection
。参见 自定义数据库类型 在自定义字段中的用法。
Django 主要有三种情况需要与数据库后台和字段进行交互。
当它查询数据库时(Python 值 -> 数据库后台值)
当它从数据库中加载数据时(数据库后台值 -> Python 值)
当它保存到数据库时(Python 值 -> 数据库后端值)
查询时,使用
get_db_prep_value()
和get_prep_value()
。- get_prep_value(value)[source]¶
value
是模型属性的当前值,该方法应以准备作为查询参数的格式返回数据。见 将 Python 转为查询值 的用法。
- get_db_prep_value(value, connection, prepared=False)[source]¶
将
value
转换为后台特定的值,默认情况下,如果prepared=True
,它将返回value
。而如果是False
,它将返回get_prep_value()
。使用方法参见 将查询值转为数据库值。
加载数据时,使用
from_db_value()
。- from_db_value(value, expression, connection)¶
将数据库返回的值转换为 Python 对象。与
get_prep_value()
相反。这个方法不用于大多数内置字段,因为数据库后端已经返回了正确的 Python 类型,或者后端自己进行了转换。
expression
与self
相同。使用方法参见 将值转为 Python 对象。
Note
由于性能原因,
from_db_value
并没有在不需要它的字段上实现 no-op(所有 Django 字段)。因此,你不能在定义中调用super
。
保存时,使用
pre_save()
和get_db_prep_save()
:- get_db_prep_save(value, connection)[source]¶
与
get_db_prep_value()
相同,但当字段值必须 保存 到数据库中时,会被调用。默认情况下返回get_db_prep_value()
。
- pre_save(model_instance, add)[source]¶
在
get_db_prep_save()
之前调用的方法,在保存前准备好值(例如DateField.auto_now
)。model_instance
是该字段所属的实例,add
是该实例是否第一次被保存到数据库中。它应该从
model_instance
中返回这个字段的适当属性的值。属性名在self.attname
中(这是由Field
设置的)。使用方法参见 在保存前预处理数值。
字段经常以不同的类型接收它们的值,要么来自序列化,要么来自表单。
- to_python(value)[source]¶
将值转换为正确的 Python 对象。它的作用与
value_to_string()
相反,并且在clean()
中也被调用。使用方法参见 将值转为 Python 对象。
除了保存到数据库,字段还需要知道如何将其值序列化。
- value_from_object(obj)[source]¶
返回给定模型实例的字段值。
这个方法经常被
value_to_string()
使用。
- value_to_string(obj)[source]¶
将
obj
转换为字符串。用于序列化字段的值。使用方法参见 为序列化转换字段数据。
当使用
model forms
时,Field
需要知道它应该由哪个表单字段来表示。- formfield(form_class=None, choices_form_class=None, **kwargs)[source]¶
返回该字段默认的
django.forms.Field
给ModelForm
。默认情况下,如果
form_class
和choices_form_class
都是None
,则使用CharField
。如果字段有chips
,且choices_form_class
没有指定,则使用TypedChoiceField
。使用方法参见 为模型字段指定表单字段。
注册和获取查询¶
Field
实现了 查找注册 API。该 API 可以用于自定义哪些查找适用于字段类及其实例,以及如何从字段中获取查找。
字段属性参考¶
每个 Field
实例都包含几个属性,允许对其行为进行内省。当你需要编写依赖于字段功能的代码时,可以使用这些属性来代替 isinstance
检查。这些属性可以与 Model._meta API 一起使用,以缩小对特定字段类型的搜索范围。自定义模型字段应该实现这些标志。
字段的属性¶
- Field.auto_created¶
表示是否自动创建字段的布尔标志,如模型继承使用的
OneToOneField
。
- Field.concrete¶
布尔值标志,表示该字段是否有与之相关的数据库列。
布尔标志,指示字段是否隐藏,并且默认情况下不应由
Options.get_fields()
返回。一个示例是对于一个以'+'
开头的related_name
的ForeignKey
的反向字段。
- Field.is_relation¶
布尔值标志,表示一个字段是否包含对一个或多个其他模型的功能引用(如
ForeignKey
、ManyToManyField
、OneToOneField
等)。
- Field.model¶
返回定义字段的模型。如果一个字段定义在一个模型的超类上,
model
将指的是超类,而不是实例的类。
有关系的字段的属性¶
这些属性用于查询关系的基数和其他细节。这些属性在所有字段上都存在;但是,如果字段是关系类型( Field.is_relation=True
),它们只有布尔值(而不是 None
)。
- Field.many_to_many¶
如果字段有多对多关系,则为
True
,否则为False
。Django 中唯一一个是True
的字段是ManyToManyField
。
- Field.many_to_one¶
如果字段有多对一关系,如
ForeignKey
,则为True
;否则为False
。
- Field.one_to_many¶
如果该字段有一对多关系,如
GenericRelation
或ForeignKey
的反向关系,则为True
;否则为False
。
- Field.one_to_one¶
如果字段有一对一的关系,如
OneToOneField
,则为True
;否则为False
。
指向该字段所涉及的模型。例如,
ForeignKey(Author, on_delete=models.CASCADE)
中的Author
。GenericForeignKey
的related_model
总是None
。