模型字段引用¶
本文档包含 Field
的所有API参考,包括 field options 和 field types Django提供。
注解
技术上,这些模型在 django.db.models.fields
中定义,但为了方便,它们被导入 django.db.models
;标准惯例是使用 from django.db import models
并将字段称为 models.<Foo>Field
。
字段选项¶
以下参数适用于所有字段类型。所有都是可选的。
null
¶
-
Field.
null
¶
如果 True
,Django将在数据库中将空值存储为 NULL
。默认为 False
。
避免在基于字符串的字段(如 CharField
和 TextField
)上使用 null
,因为空字符串值将始终存储为空字符串,而不是 NULL
。如果基于字符串的字段具有 null=True
,则意味着它对于“无数据”具有两个可能的值:NULL
和空字符串。在大多数情况下,对于“无数据”有两个可能的值是多余的: Django约定是使用空字符串,而不是 NULL
。
对于基于字符串和非字符串的字段,如果您希望在表单中允许空值,则还需要设置 blank=True
,因为 null
参数只影响数据库存储(请参阅 blank
)。
注解
当使用Oracle数据库后端时,值 NULL
将被存储以表示空字符串,而不管此属性。
如果要使用 BooleanField
接受 null
值,请改用 NullBooleanField
。
blank
¶
-
Field.
blank
¶
如果 True
,该字段允许为空。默认值为 False
。
请注意,这不同于 null
。 null
纯粹是数据库相关的,而 blank
是与验证相关的。如果字段具有 blank=True
,则表单验证将允许输入空值。如果字段具有 blank=False
,则该字段将是必需的。
choices
¶
-
Field.
choices
¶
一个可迭代的(例如,列表或元组)本身由恰好两个项目(例如 [(A, B), (A, B) ...]
)的迭代组成,以用作该字段的选择。如果给出了这一点,默认表单窗口小部件将是具有这些选项的选择框,而不是标准文本字段。
每个元组中的第一个元素是要在模型上设置的实际值,第二个元素是人类可读的名称。例如:
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
)
通常,最好在模型类中定义选择,并为每个值定义一个适当命名的常量:
from django.db import models
class Student(models.Model):
FRESHMAN = 'FR'
SOPHOMORE = 'SO'
JUNIOR = 'JR'
SENIOR = 'SR'
YEAR_IN_SCHOOL_CHOICES = (
(FRESHMAN, 'Freshman'),
(SOPHOMORE, 'Sophomore'),
(JUNIOR, 'Junior'),
(SENIOR, 'Senior'),
)
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'),
)
每个元组中的第一个元素是要应用于组的名称。第二个元素是一个2元组的迭代,每个2元组包含一个值和一个人类可读的选项名称。分组选项可以与单个列表(例如本示例中的 unknown 选项)中的未分组选项组合。
对于具有 choices
集合的每个模型字段,Django将添加一个方法来检索字段的当前值的人工可读名称。请参阅数据库API文档中的 get_FOO_display()
。
注意,选择可以是任何可迭代对象 - 不一定是列表或元组。这允许您动态构建选项。但是,如果你发现自己黑客 choices
是动态的,你可能最好使用一个合适的数据库表与 ForeignKey
。 choices
用于静态数据,如果有的话,变化不大。
除非 blank=False
与 default
一起设置在字段上,否则将使用选择框呈现包含 "---------"
的标签。要覆盖此行为,请向包含 None
的 choices
添加元组;例如 (None, 'Your String For Display')
。或者,您可以使用空字符串,而不是 None
,这是有意义的 - 例如在 CharField
。
db_column
¶
-
Field.
db_column
¶
要用于此字段的数据库列的名称。如果没有给出,Django将使用字段的名称。
如果您的数据库列名称是SQL保留字,或包含Python变量名中不允许的字符,特别是连字符 - 没关系。 Django在后台引用列和表名。
db_tablespace
¶
-
Field.
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
s不能用于像 default
这样的字段选项,因为它们不能是 通过迁移序列化。请参阅其他注意事项的文档。
对于映射到模型实例的 ForeignKey
等字段,默认值应为它们引用的字段的值(除非设置了 to_field
,否则为 pk
)而不是模型实例。
创建新模型实例并且未为字段提供值时,将使用默认值。当字段是主键时,当字段设置为 None
时,也使用默认值。
error_messages
¶
-
Field.
error_messages
¶
error_messages
参数允许您覆盖字段将引发的默认消息。传入具有与要覆盖的错误消息匹配的键的字典。
错误消息键包括 null
,blank
,invalid
,invalid_choice
,unique
和 unique_for_date
。在下面的 Field types 部分中为每个字段指定了其他错误消息键。
help_text
¶
-
Field.
help_text
¶
额外的“帮助”文本与窗体小部件一起显示。它对文档很有用,即使您的字段未在表单上使用。
请注意,此值是在自动生成的表单中转义的 not 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将自动添加一个 AutoField
来保存主键,因此您不需要在任何字段上设置 primary_key=True
,除非要覆盖默认主键行为。更多,见 自动主键字段。
primary_key=True
意味着 null=False
和 unique=True
。对象上只允许使用一个主键。
主键字段为只读。如果更改现有对象上主键的值,然后保存,将在旧对象旁边创建一个新对象。
unique
¶
-
Field.
unique
¶
如果是 True
,该字段在整个表中必须是唯一的。
这是在数据库级别和模型验证。如果您尝试在 unique
字段中保存具有重复值的模型,则 django.db.IntegrityError
将由模型的 save()
方法生成。
此选项对除 ManyToManyField
,OneToOneField
和 FileField
之外的所有字段类型有效。
注意,当 unique
是 True
时,您不需要指定 db_index
,因为 unique
意味着创建索引。
unique_for_date
¶
-
Field.
unique_for_date
¶
将此设置为 DateField
或 DateTimeField
的名称,以要求该字段对于日期字段的值是唯一的。
例如,如果您有一个具有 unique_for_date="pub_date"
的字段 title
,则Django将不允许输入具有相同 title
和 pub_date
的两个记录。
请注意,如果将此设置为指向 DateTimeField
,则只会考虑字段的日期部分。此外,当 USE_TZ
为 True
时,将在保存对象时在 当前时区 中执行检查。
这由 Model.validate_unique()
在模型验证期间强制执行,但不在数据库级别。如果任何 unique_for_date
约束涉及不是 ModelForm
的一部分的字段(例如,如果其中一个字段在 exclude
中列出或具有 editable=False
),则 Model.validate_unique()
将跳过该特定约束的验证。
字段类型¶
AutoField
¶
IntegerField
根据可用ID自动递增。你通常不需要直接使用这个;如果没有指定,主键字段将自动添加到模型中。见 自动主键字段。
BigAutoField
¶
-
class
BigAutoField
(**options)¶
一个64位整数,非常类似于 AutoField
,除了它保证适合从 1
到 9223372036854775807
的数字。
BigIntegerField
¶
一个64位整数,非常类似于 IntegerField
,除了它保证适合从 -9223372036854775808
到 9223372036854775807
的数字。此字段的默认表单窗口小部件是 TextInput
。
BinaryField
¶
用于存储原始二进制数据的字段。它只支持 bytes
分配。请注意,此字段的功能有限。例如,不能根据 BinaryField
值过滤查询集。也不可能在 ModelForm
中包括 BinaryField
。
滥用 BinaryField
虽然您可能会考虑将文件存储在数据库中,但在99%的情况下,它是不好的设计。此字段是 not,用于替换正确的 静态文件 处理。
BooleanField
¶
真/假字段。
此字段的默认表单窗口小部件是 CheckboxInput
。
如果您需要接受 null
值,则使用 NullBooleanField
。
当 Field.default
未定义时,BooleanField
的默认值为 None
。
CharField
¶
字符串字段,用于小到大字符串。
对于大量的文本,请使用 TextField
。
此字段的默认表单窗口小部件是 TextInput
。
CharField
有一个额外的必需参数:
-
CharField.
max_length
¶ 字段的最大长度(以字符为单位)。 max_length在数据库级别和Django的验证中强制执行。
注解
如果您正在编写一个必须可移植到多个数据库后端的应用程序,那么您应该注意,有些后端存在 max_length
限制。有关详细信息,请参阅 数据库后端记录。
MySQL用户
如果你使用这个字段与MySQLdb 1.2.2和 utf8_bin
排序规则(这是默认的 not),有一些问题需要注意。有关详细信息,请参阅 MySQL数据库笔记。
CommaSeparatedIntegerField
¶
1.9 版后已移除: 此字段已弃用,赞成 CharField
与 validators=[
validate_comma_separated_integer_list
]
。
由逗号分隔的整数字段。如在 CharField
中,需要 max_length
参数,并且应该注意关于数据库可移植性的注释。
DateField
¶
日期,由 datetime.date
实例在Python中表示。有一些额外的可选参数:
-
DateField.
auto_now
¶ 每次保存对象时,自动将字段设置为现在。用于“最后修改”的时间戳。注意当前日期是使用 always;它不只是一个默认值,你可以覆盖。
该字段仅在调用
Model.save()
时自动更新。在以其他方式(例如QuerySet.update()
)更新其他字段时,不会更新该字段,但您可以在此类更新中为字段指定自定义值。
-
DateField.
auto_now_add
¶ 在首次创建对象时自动将字段设置为现在。用于创建时间戳。注意当前日期是使用 always;它不只是一个默认值,你可以覆盖。因此,即使在创建对象时为此字段设置了一个值,它也将被忽略。如果您想要修改此字段,请设置以下内容而不是
auto_now_add=True
:对于
DateField
:default=date.today
- 来自datetime.date.today()
对于
DateTimeField
:default=timezone.now
- 来自django.utils.timezone.now()
此字段的默认表单窗口小部件是 TextInput
。管理员添加一个JavaScript日历和一个“今天”的快捷方式。包括一个额外的 invalid_date
错误消息键。
选项 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
;或者使用 DateTimeField
而不是 DateField
并且决定如何处理在显示时间从日期时间到日期的转换。
DateTimeField
¶
日期和时间,由Python在 datetime.datetime
实例中表示。采用与 DateField
相同的额外参数。
此字段的默认表单窗口小部件是单个 TextInput
。管理员使用两个单独的 TextInput
小部件与JavaScript快捷方式。
DecimalField
¶
一个固定精度的十进制数,由Python在 Decimal
实例中表示。有两个 需要 参数:
-
DecimalField.
max_digits
¶ 数字中允许的最大位数。请注意,此数字必须大于或等于
decimal_places
。
-
DecimalField.
decimal_places
¶ 要存储的数字的小数位数。
例如,要存储高达 999
的数字,分辨率为2位小数,请使用:
models.DecimalField(..., max_digits=5, decimal_places=2)
并且存储高达约十亿的数字,分辨率为10个小数位:
models.DecimalField(..., max_digits=19, decimal_places=10)
当 localize
为 False
或 TextInput
时,此字段的默认表单窗口小部件为 NumberInput
。
注解
有关 FloatField
和 DecimalField
类之间差异的更多信息,请参阅 FloatField与DecimalField。
DurationField
¶
一个用于存储时间段的字段 - 由 timedelta
在Python中建模。当在PostgreSQL上使用时,使用的数据类型是 interval
,在Oracle上,数据类型是 INTERVAL DAY(9) TO SECOND(6)
。否则使用微秒的 bigint
。
注解
使用 DurationField
的算术在大多数情况下都有效。但是在除PostgreSQL之外的所有数据库上,将 DurationField
的值与 DateTimeField
实例上的算法进行比较将无法按预期工作。
EmailField
¶
检查值是否为有效电子邮件地址的 CharField
。它使用 EmailValidator
来验证输入。
FileField
¶
文件上传字段。
注解
不支持 primary_key
和 unique
参数,如果使用 TypeError
将引发 TypeError
。
有两个可选参数:
-
FileField.
upload_to
¶ 此属性提供了设置上传目录和文件名的方法,并且可以通过两种方式设置。在这两种情况下,值都传递到
Storage.save()
方法。如果指定了字符串值,它可能包含
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。确保此目录可由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
中。
如果要检索上传文件的磁盘文件名或文件大小,可以分别使用 name
和 size
属性;有关可用属性和方法的更多信息,请参阅 File
类参考和 管理文件 主题指南。
注解
该文件将作为将模型保存在数据库中的一部分进行保存,因此在保存模型之前不能依赖磁盘上使用的实际文件名。
可以使用 url
属性获取上传文件的相对URL。在内部,这会调用底层 Storage
类的 url()
方法。
请注意,每当处理上传的文件时,都应该密切注意上传文件的位置和文件类型,以避免出现安全漏洞。 验证所有上传的文件,以便确保文件是你认为他们是。例如,如果您盲目地让某人将文件上传到Web服务器文档根目录中,那么有人可以上传CGI或PHP脚本,并通过访问您网站上的URL来执行该脚本。不要允许。
还要注意,即使上传的HTML文件,因为它可以由浏览器(虽然不是由服务器)执行,可以提出等同于XSS或CSRF攻击的安全威胁。
FileField
实例在数据库中创建为默认最大长度为100个字符的 varchar
列。与其他字段一样,您可以使用 max_length
参数更改最大长度。
FileField
和 FieldFile
¶
当您访问模型上的 FileField
时,您将获得一个 FieldFile
实例作为访问基础文件的代理。
FieldFile
的API与 File
的API相同,但有一个主要区别:由类包装的对象不一定是Python内置文件对象的包装器。 相反,它是 Storage.open()
方法的结果的包装器,它可以是 File
对象,也可以是 File
API的自定义存储器实现。
除了继承自 File
的API(例如 read()
和 write()
)之外,FieldFile
还包括几种可用于与底层文件交互的方法:
-
FieldFile.
name
¶
文件的名称,包括从关联的 FileField
的 Storage
的根目录的相对路径。
-
FieldFile.
size
¶
基础 Storage.size()
方法的结果。
-
FieldFile.
url
¶
通过调用基础 Storage
类的 url()
方法来访问文件的相对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
¶
CharField
,其选择仅限于文件系统上某个目录中的文件名。有三个特殊的论点,其中第一个是 需要:
-
FilePathField.
path
¶ 需要。该
FilePathField
应从中获取其选择的目录的绝对文件系统路径。示例:"/home/images"
。
-
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
实例在数据库中创建为默认最大长度为100个字符的 varchar
列。与其他字段一样,您可以使用 max_length
参数更改最大长度。
FloatField
¶
在Python中由 float
实例表示的浮点数。
当 localize
为 False
或 TextInput
时,此字段的默认表单窗口小部件为 NumberInput
。
FloatField
vs. DecimalField
FloatField
类有时与 DecimalField
类混淆。虽然它们都代表实数,但它们代表的是不同的数字。 FloatField
在内部使用Python的 float
类型,而 DecimalField
使用Python的 Decimal
类型。有关两者之间的区别的信息,请参阅 decimal
模块的Python文档。
ImageField
¶
-
class
ImageField
(upload_to=None, height_field=None, width_field=None, max_length=100, **options)[源代码]¶
继承 FileField
中的所有属性和方法,但也验证上传的对象是有效的图像。
除了可用于 FileField
的特殊属性,ImageField
还具有 height
和 width
属性。
为了方便查询这些属性,ImageField
有两个额外的可选参数:
-
ImageField.
height_field
¶ 模型字段的名称,每次保存模型实例时,将自动填充图像的高度。
-
ImageField.
width_field
¶ 每次保存模型实例时将自动填充图像宽度的模型字段的名称。
需要 Pillow 库。
ImageField
实例在数据库中创建为默认最大长度为100个字符的 varchar
列。与其他字段一样,您可以使用 max_length
参数更改最大长度。
此字段的默认表单窗口小部件是 ClearableFileInput
。
IntegerField
¶
整数。从 -2147483648
到 2147483647
的值在Django支持的所有数据库中都是安全的。当 localize
为 False
或 TextInput
时,此字段的默认表单窗口小部件为 NumberInput
。
GenericIPAddressField
¶
以字符串格式(例如 192.0.2.30
或 2a02:42fe::4
)的IPv4或IPv6地址。此字段的默认表单窗口小部件是 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
。所有字符都转换为小写。
-
GenericIPAddressField.
protocol
¶ 限制指定协议的有效输入。接受的值为
'both'
(默认),'IPv4'
或'IPv6'
。匹配不区分大小写。
-
GenericIPAddressField.
unpack_ipv4
¶ 解开IPv4映射地址(如
::ffff:192.0.2.1
)。如果启用此选项,则该地址将解包到192.0.2.1
。默认为禁用。只能在protocol
设置为'both'
时使用。
如果允许空值,则必须允许空值,因为空值存储为null。
NullBooleanField
¶
像 BooleanField
,但允许 NULL
作为选项之一。使用此代替 BooleanField
与 null=True
。此字段的默认表单窗口小部件是 NullBooleanSelect
。
PositiveIntegerField
¶
像 IntegerField
,但必须是正或零(0
)。从 0
到 2147483647
的值在Django支持的所有数据库中都是安全的。由于向后兼容性原因,接受值 0
。
PositiveSmallIntegerField
¶
像 PositiveIntegerField
,但只允许在某个(数据库相关)点下的值。从 0
到 32767
的值在Django支持的所有数据库中都是安全的。
SlugField
¶
Slug 是一个报纸术语。 lug是一个短标签,只包含字母,数字,下划线或连字符。它们通常用于网址。
像CharField一样,您可以指定 max_length
(也请阅读有关数据库可移植性和 max_length
的说明)。如果未指定 max_length
,Django将使用默认长度50。
将 Field.db_index
设置为 True
。
根据某些其他值的值自动预填充SlugField通常很有用。您可以在管理员中使用 prepopulated_fields
自动执行此操作。
-
SlugField.
allow_unicode
¶ - New in Django 1.9.
如果是
True
,该字段除了ASCII字母外,还接受Unicode字符。默认为False
。
SmallIntegerField
¶
像 IntegerField
,但只允许在某个(数据库相关)点下的值。从 -32768
到 32767
的值在Django支持的所有数据库中都是安全的。
TextField
¶
大文本字段。此字段的默认表单窗口小部件是 Textarea
。
如果指定 max_length
属性,它将反映在自动生成的表单字段的 Textarea
窗口小部件中。但是不会在模型或数据库级别强制执行。使用 CharField
。
MySQL用户
如果您使用此字段与MySQLdb 1.2.1p2和 utf8_bin
排序规则(这是默认的 not),有一些问题需要注意。有关详细信息,请参阅 MySQL数据库笔记。
TimeField
¶
一个时间,在Python中由 datetime.time
实例表示。接受与 DateField
相同的自动填充选项。
此字段的默认表单窗口小部件是 TextInput
。管理员添加一些JavaScript快捷方式。
URLField
¶
URL的 CharField
。
此字段的默认表单窗口小部件是 TextInput
。
像所有 CharField
子类一样,URLField
采用可选的 max_length
参数。如果不指定 max_length
,则使用默认值200。
UUIDField
¶
用于存储通用唯一标识符的字段。使用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
注意,可调用(省略括号)被传递给 default
,而不是 UUID
的实例。
字段API参考¶
-
class
Field
[源代码]¶ 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)¶ - New in Django 1.10.
返回指向
Field
的字段(如ForeignKey
和OneToOneField
)的数据库列数据类型,并考虑connection
。有关在自定义字段中的用法,请参阅 自定义数据库类型。
有三种主要情况,Django需要与数据库后端和字段交互:
当它查询数据库(Python值 - >数据库后端值)
当它从数据库加载数据(数据库后端值 - > Python值)
当它保存到数据库(Python值 - >数据库后端值)
查询时,使用
get_db_prep_value()
和get_prep_value()
:-
get_prep_value
(value)[源代码]¶ value
是模型属性的当前值,方法应以已准备好用作查询中的参数的格式返回数据。请参阅 将Python对象转换为查询值 的使用。
-
get_db_prep_value
(value, connection, prepared=False)[源代码]¶ 将
value
转换为后端特定值。默认情况下,如果prepared=True
和get_prep_value()
if是False
,则返回value
。请参阅 将查询值转换为数据库值 的使用。
当加载数据时,使用
from_db_value()
:-
from_db_value
(value, expression, connection, context)¶ 将数据库返回的值转换为Python对象。这是
get_prep_value()
的相反。此方法不用于大多数内置字段,因为数据库后端已返回正确的Python类型,或后端本身执行转换。
请参阅 将值转换为Python对象 的使用。
注解
出于性能原因,
from_db_value
不实现为不需要它的字段(所有Django字段)的no-op。因此,您不能在定义中调用super
。
保存时,使用
pre_save()
和get_db_prep_save()
:-
get_db_prep_save
(value, connection)[源代码]¶ 与
get_db_prep_value()
相同,但是当字段值必须是 saved 到数据库时调用。默认情况下返回get_db_prep_value()
。
-
pre_save
(model_instance, add)[源代码]¶ 在
get_db_prep_save()
之前调用以在保存之前准备值的方法(例如,对于DateField.auto_now
)。model_instance
是此字段所属的实例,add
是实例是否第一次保存到数据库。它应该从此字段的
model_instance
返回适当属性的值。属性名称在self.attname
中(这是由Field
设置的)。请参阅 保存前预处理值 的使用。
字段通常从不同的序列或表单中接收不同的值。
-
to_python
(value)[源代码]¶ 将值转换为正确的Python对象。它作为
value_to_string()
的反向,并且也在clean()
中被调用。请参阅 将值转换为Python对象 的使用。
除了保存到数据库之外,字段还需要知道如何序列化其值:
-
value_to_string
(obj)[源代码]¶ 将
obj
转换为字符串。用于序列化字段的值。请参阅 转换字段数据以进行序列化 的使用。
当使用
model forms
时,Field
需要知道应由哪个表单字段表示:-
formfield
(form_class=None, choices_form_class=None, **kwargs)[源代码]¶ 返回
ModelForm
的此字段的默认django.forms.Field
。默认情况下,如果
form_class
和choices_form_class
都是None
,则使用CharField
。如果字段有choices
且未指定choices_form_class
,则使用TypedChoiceField
。请参阅 指定模型字段的表单字段 的使用。
-
字段属性引用¶
每个 Field
实例包含几个允许内省其行为的属性。当您需要编写取决于字段功能的代码时,使用这些属性而不是 isinstance
检查。这些属性可以与 Model._meta API 一起使用,以缩小对特定字段类型的搜索。自定义模型字段应该实现这些标志。
字段的属性¶
-
Field.
auto_created
¶ 布尔标志,指示是否自动创建字段,例如模型继承使用的
OneToOneField
。
-
Field.
concrete
¶ 布尔标志,指示字段是否具有与其相关联的数据库列。
布尔标志,其指示是否使用字段来回复另一个非隐藏字段的功能(例如,构成
GenericForeignKey
的content_type
和object_id
字段)。hidden
标志用于区分模型上的字段的公共子集构成模型上的所有字段。注解
默认情况下,
Options.get_fields()
排除隐藏字段。传入include_hidden=True
以返回结果中的隐藏字段。
-
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
¶ 布尔标志,如果字段具有多对一关系,则为
True
,例如ForeignKey
;False
。
-
Field.
one_to_many
¶ 布尔标志,如果字段具有一对多关系(例如
GenericRelation
或ForeignKey
的反向),则为True
;False
。
-
Field.
one_to_one
¶ 如果字段具有一对一关系,则为
True
的布尔标志,例如OneToOneField
;False
。
指向字段涉及的模型。例如,
Author
在ForeignKey(Author, on_delete=models.CASCADE)
。GenericForeignKey
的related_model
总是None
。