24-Django模型字段
原文:https://django-chinese-doc.readthedocs.io/zh_CN/latest/ref/models/fields.html
本文档包含了Django提供的全部模型 Field
包括 字段选项 和 字段类型 的API参考。
注解
严格意义上来讲, Model定义在 django.db.models.fields
里面, 但为了使用方便,它们被导入到 django.db.models
中;一般使用 from django.db import models
导入, 然后使用 models.<Foo>Field
的形式使用字段。
字段选项
下列参数是全部字段类型都可用的,而且都是可选择的。
null
Field.
null
如果为 True
, Django 将把空值在数据库中存为 NULL
,默认为 is False
。
不要为字符串类型字段设置 null
,例如 CharField
和 TextField
。因为这样会把空字符串存为 NULL
。 如果字符串字段设置了 null=True
,那意味着对于“无数据”有两个可能的值: null
和空字符串。 这种明显是多余的,Django 的惯例是使用空字符串而不是NULL。
无论是字符串字段还是非字符串字段,如果你希望在表单中允许存在空值,必须要设置 blank=True
,因为仅仅影响数据库存储。(参见 blank
)。
注解
在使用Oracle 数据库时,数据库将存储 NULL
来表示空字符串,而与这个属性无关。
如果你希望 BooleanField
接受 null
值, 那么使用 NullBooleanField
代替。
blank
Field.
blank
如果为 True
, 则该字段允许为空。默认为 False
。
注意它和 null
不同。 null
纯粹是数据库范畴的概念,而 blank
是数据验证范畴。 如果字段设置 blank=True
, 表单验证时将允许输入空值。如果字段设置 blank=False
, 则该字段为必填。
choices
Field.
choices
它是一个可迭代的结构(e.g., 列表或元组) 。由可迭代的二元组组成 (e.g. [(A, B), (A, B) ...]
), 用来给字段提供选择项。如果设置了 choices
, 默认表格样式就会显示选择框,而不是标准的文本框,而且这个选择框的选项就是 choices
中的元组。
每个元组中的第一个元素,是存储在数据库中的值;第二个元素是该选项描述。 比如:
YEAR_IN_SCHOOL_CHOICES = (
('FR', 'Freshman'),
('SO', 'Sophomore'),
('JR', 'Junior'),
('SR', 'Senior'),
)
一般来说,最好在模型类内部定义choices,然后再给每个值定义一个合适名字:
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)
当然也可以在模型类的外部定义choices然后引用它, 但是在模型类中定义choices和其每个choice的name(即元组的第二个元素)可以保存所有使用choices的信息, 也使得choices更容易被应用(例如, Student.SOPHOMORE
可以在任何引入 Student
模型的地方生效)。
也可以将选项归类到已命名的组中用来达成组织整理的目的:
MEDIA_CHOICES = (
('Audio', (
('vinyl', 'Vinyl'),
('cd', 'CD'),
)
),
('Video', (
('vhs', 'VHS Tape'),
('dvd', 'DVD'),
)
),
('unknown', 'Unknown'),
)
每个元组的第一个元素是组的名字。 第二个元素是一组可迭代的二元元组, 每一个二元元组包含一个值和一个适合人看的名字构成一个选项。 分组的选项可能会和未分组的选项合在同一个list中。 (就像例中的 unknown 选项)。
对于包含 choices
的模型字段, Django 将会加入一个方法来获取当前字段值的易于理解的名称 (即元组的第二个值)。参见数据库API文档中的 get_FOO_display()
。
choices 只要是可迭代的对象就行 – 并不一定要是列表和元组。这样你可以动态构建choices。 但是如果你自己搞不定动态的 choices
。你最好还是使用 ForeignKey
来构建一个合适的数据库表。 而对于静态数据来说, choices
是不改变的。
除非在字段中设置了 blank=False
否则将选择框中将包含一个 "---------"
的标签。 只要在添加一个 None
到 choices
元组中就可以改变这一行为。e.g. (None, 'Your String For Display')
, 或者, 你可以用一个空字符串代替 None
比如在一个 CharField
。
db_column
Field.
db_column
数据库中储存该字段的列名。如果未指定,那么Django将会使用Field名作为字段名。
如果你的数据库列名是SQL语句的保留字,或者是包含不能作为Python 变量名的字符,如连字符。这也不会有问题, Django 会在后台给列名和表名加上双引号。
db_index
Field.
db_index
如果为 True
,将会为这个字段创建数据库索引。
db_tablespace
Field.
db_tablespace
The name of the database tablespace to use for this field’s index, if this field is indexed. The default is the project’s DEFAULT_INDEX_TABLESPACE
setting, if set, or the db_tablespace
of the model, if any. If the backend doesn’t support tablespaces for indexes, this option is ignored.
default
Field.
default
该字段的默认值. 它可以是一个值或者一个可调用对象。 如果是一个可调用对象,将会在创建新对象时调用。
这个默认值不可以是一个可变对象(比如 模型实例
, 列表
, 集合
等等)。 因为对于所有模型的一个新的实例来说,它们指向同一个引用。 或者,把他们封装为一个可调用的对象。 例如,有一个自定义的 JSONField
,想指定一个特定的字典值,可以这样:
def contact_default():
return {"email": "to1@example.com"}
contact_info = JSONField("ContactInfo", default=contact_default)
lambda
表达式不能作为 default
的参数值,因为她们无法 被migrations序列化 。
对于将映射到模型实例的外键之类的字段,默认值应该是它们引用的字段的值(除非to字段设置为pk),而不是模型实例。
对于将映射到模型实例的字段,例如 ForeignKey
。其默认值应该是他们引用的字段值( 除非to_field
设置了 pk
)而不是模型实例。
默认值会在新实例创建并且没有给该字段提供值时使用。如果字段为主键,默认值也会在设置为 None````None
时使用。
error_messages
Field.
error_messages
-
error_messages
参数用于重写默认的错误提示,通过字典的key来匹配将要改变的错误类型。
错误提示的key包括 null
, blank
, invalid
, invalid_choice
, unique
, 和 unique_for_date
。 下面的 字段类型 中的 error_messages 的 keys 是不一样的。
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特定的字符。 请确保你所使用的help text能够避免一些不信任用户的跨站脚本攻击。
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
字段保存重复的值,save()
方法将回抛出 django.db.IntegrityError
异常。
这个选项适用于除了 ManyToManyField
, OneToOneField
, FileField
的其他所有字段。
当设置了 unique
为 True
后,可以不必再指定 db_index
, 因为 unique
也会创建索引。
unique_for_date
Field.
unique_for_date
设置为 DateField
或者 DateTimeField
字段的名字,表示要求该字段对于相应的日期字段值是唯一的。
例如,字段 title
设置了 unique_for_date="pub_date"
,那么Django将不会允许在同一 pub_date
的两条记录的 title
相同。
需要注意的是,如果你设置的是一个 DateTimeField
, 也只会考虑日期部分。 此外,如果设置了 USE_TZ
为 True
, 检查将以对象保存时的 当前时区 进行。
这是在模型验证期间通过 Model.validate_unique()
强制执行的, 而不是在数据库层级进行验证。 如果 unique_for_date
约束涉及的字段不是 ModelForm
中的字段(例如, exclude
中列出的字段或者设置了 editable=False
), Model.validate_unique()
将忽略该特殊的约束。
verbose_name
Field.
verbose_name
为字段设置的可读性更高的名称。如果用户没有定义改选项, Django会自动将自动创建,内容是该字段属性名中的下划线转换为空格的结果。可以参照 Verbose field names.
validators
Field.
validators
该字段将要运行的一个Validator的列表。 更多信息参见 validators 文档 。
注册和查询
Field
实现了 查询注册API 。 该API 可以用于自定义一个字段类型的查询,以及如何从一个字段获取查询。
字段类型
AutoField
- class
django.db.models.
AutoField
(**options)
一个根据实际ID自动增长的 IntegerField
。 通常不需要直接使用它,如果表中没有设置主键时,将会自动添加一个自增主键。参考 自增主键 。
BigAutoField
- class
django.db.models.
BigAutoField
(**options)
一个64位整数, 和 AutoField
类似,不过它的范围是 1
到 9223372036854775807
。
BigIntegerField
- class
django.db.models.
BigIntegerField
(**options)
一个64位整数, 和 IntegerField
类似,不过它允许的值范围是 -9223372036854775808
到 9223372036854775807
。这个字段默认的表单组件是一个 TextInput
.
BinaryField
- class
django.db.models.
BinaryField
(**options)
这是一个用来存储原始二进制码的字段。支持 bytes
赋值。 注意这个字段只有很有限的功能。 比如,不能在一个 BinaryField
值的上进行查询过滤。 ModelForm
中也不允许包含 BinaryField
。
滥用 BinaryField
可能你想使用数据库来存储文件,但是99%的情况下这都是不好的设计。 这个字段 不是 代替 静态文件 的最佳方式。
BooleanField
- class
django.db.models.
BooleanField
(**options)
一个 true/false 字段。
这个字段的默认表单部件是 CheckboxInput
。
如果要允许 null
值,那么可以使用 NullBooleanField
代替。
- 如果
Field.default
没有指定, BooleanField
的默认值将是None
。
CharField
- class
django.db.models.
CharField
(max_length=None, **options)
字符字段。
对于比较大的文本内容,请使用 TextField
类型。
这个字段的默认表单部件是 TextInput
.
CharField
字段有个额外参数:
CharField.
max_length
-
字段允许的最大字符串长度。这将在数据库中和表单验证时生效。
注解
如果你在写一个需要导出到多个不同数据库后端的应用,你需要注意某些后端对 max_length
有一些限制, 查看 数据库后端注意事项 来获取更多的细节。
MySQL users
如果你使用的是 MySQLdb 1.2.2 设置的是 utf8_bin
校对 (这 不是 默认项), 你必须了解一些问题。详细请参考 MySQL 数据库注意事项 。
CommaSeparatedIntegerField
- class
django.db.models.
CommaSeparatedIntegerField
(max_length=None, **options)
1.9 版后已移除: 这个字段可以使用 CharField
的 validators=[
validate_comma_separated_integer_list
]
代替。
一个逗号分隔的整数字段。 和 CharField
一样, max_length
是必填参数,同时再数据库移植时也需要注意。
DateField
- class
django.db.models.
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
- fromdatetime.date.today()
- 对于
DateTimeField
:default=timezone.now
- fromdjango.utils.timezone.now()
- 对于
这个字段的默认表单部件是 TextInput
。在admin中会添加一个JavaScript的日期插件,带有一个 “Today” 的快捷按钮。 也包含 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
,然后在显示时间的时候再决定如何从 datetime 转换到 date。
DateTimeField
- class
django.db.models.
DateTimeField
(auto_now=False, auto_now_add=False, **options)
时间和日期, 表现为 Python 中的 datetime.datetime
实例。 和 DateField
有相同的额外参数。
默认的表单部件是一个 TextInput
。admin页面使用两个带有 JavaScript控件的 TextInput
。
DecimalField
- class
django.db.models.
DecimalField
(max_digits=None, decimal_places=None, **options)
十进制数,表现为Python中 Decimal
实例,有两个 必填 参数:
DecimalField.
max_digits
-
允许的最大位数包括小数点后的位数。必须大于等于
decimal_places
。
DecimalField.
decimal_places
-
小数点后的位数。
举个例子,要储存最大为 999
带有两位小数的数字,需要这样设置:
models.DecimalField(..., max_digits=5, decimal_places=2)
而要存储那些将近10亿,并且要求达到小数点后十位精度的数字:
models.DecimalField(..., max_digits=19, decimal_places=10)
该字段默认的表单部件是 NumberInput
, 如果 localize
设置为 False
则是 TextInput
。
注解
关于更多 FloatField
和 DecimalField
的区别信息,请参考 FloatField vs. DecimalField 。
DurationField
- class
django.db.models.
DurationField
(**options)
用作存储一段时间的字段类型 - 类似Python中的 timedelta
。.当数据库使用的是 PostgreSQL, 该数据类型使用的是一个 interval
, 而在Oracle上,则使用的是 INTERVAL DAY(9) TO SECOND(6)
。其他情况使用微秒的的 bigint
。
注解
DurationField
的算数运算在多数情况下可以很好的工作。 然而,在除了 PostgreSQL之外的其他数据库中, 将 DurationField
和 DateTimeField
的实例比较则不会得到正确的结果。
EmailField
- class
django.db.models.
EmailField
(max_length=254, **options)
一个检查输入的email地址是否合法的 CharField
类型。 它使用 EmailValidator
来验证输入合法性。
FileField
- class
django.db.models.
FileField
(upload_to=None, max_length=100, **options)
上传文件字段。
注解
primary_key
和 unique
在这个字段中不支持, 如果使用在抛出 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 风格的路径(带有前向/)给存储系统。将传递的两个参数为:Argument Description 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)
FileField.
storage
-
一个Storage 对象,用于你的文件的存取。参见 Managing files 查看如何提供这个对象的细节。
这个字段的默认表单部件是一个 ClearableFileInput
。
在模式中使用 FileField
类型或 ImageField
(见下文) 需要如下几步:
- 在 settings 文件中, 将Django储存文件的的完整路径设置到
MEDIA_ROOT
项。 (从性能上考虑,不要将这些文件存在数据库中) 定义一个MEDIA_URL
作为基础目录的URL。确保web server账户对这个目录有读写权限。 - 添加
FileField
或者ImageField
到模型中, 定义 属性upload_to
用来存放上传的文件,应该是MEDIA_ROOT
的子目录。 - 数据库中存放的仅是这个文件的路径 (相对于
MEDIA_ROOT
)。 然后使用url
属性 来获取。例如, 一个叫做mug_shot
的ImageField
字段,可以使用{{ object.mug_shot.url }}
来获取它的绝对路径。
假如, 你将 MEDIA_ROOT
设置为 '/home/media'
, upload_to
属性设置为 'photos/%Y/%m/%d'
。upload_to
的 '%Y/%m/%d'
部分是 strftime()
的格式化字符。 '%Y'
表示四位数的年份, '%m'
表示两位数的月份, '%d'
表示两位数的日份。 如果文件上传时间是 Jan. 15, 2007,将被存到目录 /home/media/photos/2007/01/15
。
如果想要知道上传文件的磁盘文件名或文件大小, 可以使用 name
和 size
属性得到;关于更多支持的方法和属性。请参考 File
的参考文档 Managing files 。
注解
文件作为模型存储在数据库中的一部分,磁盘上文件名在模型保存完毕之前是不可靠的。
上传的文件对应的URL可以通过使用 url
属性获得. 其实在内部,是调用 Storage
类的 url()
方法。
值得注意的是,无论任何时候处理上传文件时,都应该密切关注文件将被上传到哪里,上传的文件类型,以避免安全漏洞。 检查所有上传文件 确保上传的文件是被允许的文件。 例如,如果你盲目的允许其他人在无需认证的情况下上传文件至你的web服务器的root目录中, 那么别人可以上传一个CGI或者PHP脚本然后通过访问一个你网站的URL来执行这个脚本。 所以,不要允许这种事情发生。
甚至是上传HTML文件也需要注意,它可以通过浏览器(虽然不是服务器)执行,也可以引发相当于是XSS或者CSRF攻击的安全威胁。
FileField
对象在数据库中以最大长度100个字节的 varchar
类型存在。 和普通字段一样。也可以使用 max_length
参数限制。
FileField
和 FieldFile
- class
django.db.models.fields.files.
FieldFile
当添加一个 FileField
字段到模型中时,实际上是一个 FieldFile
实例作为将要访问文件的代理。
The API of FieldFile
mirrors that of File
, with one key difference: The object wrapped by the class is not necessarily a wrapper around Python’s built-in file object. Instead, it is a wrapper around the result of the Storage.open()
method, which may be a File
object, or it may be a custom storage’s implementation of the File
API.
In addition to the API inherited from File
such as read()
and write()
, FieldFile
includes several methods that can be used to interact with the underlying file:
警告
Two methods of this class, save()
and delete()
, default to saving the model object of the associated FieldFile
in the database.
FieldFile.
name
文件的名称,Storage
的根路径, FileField
的相对路径。
FieldFile.
size
下面 Storage.size()
方法的返回结果。
FieldFile.
url
通过下面 Storage
类的 url()
方法只读地访问文件的URL。
FieldFile.
open
(mode='rb')
在指定 模式 下打开或重写与该实例相关联的文件,和Python的标准 open()
方法不同的是,它不返回文件描述符。
由于底层文件在访问它时隐式地打开,因此调用此方法可能没有必要,除非将指针重置到底层文件或更改 模式。
FieldFile.
close
()
类似Python的 file.close()
方法,关闭相关文件。
FieldFile.
save
(name, content, save=True)
这个方法会将文件名以及文件内容传递到字段的storage类中,并将模型字段与保存好的文件关联。 I 如果想要手动关联文件数据到你的模型中的 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")
其他更多信息, 参见 Managing files.
FieldFile.
delete
(save=True)
删除与此实例关联的文件,并清除该字段的所有属性。 注意:如果在调用 delete()
时有打开操作,该方法将关闭该文件。
save
控制模型实例在关联的文件被修改时是否保存,默认为 True
。
注意,model删除的时候,与之关联的文件并不会被删除。如果你要把文件也清理掉,你需要自己处理
FilePathField
- class
django.db.models.
FilePathField
(path=None, match=None, recursive=False, max_length=100, **options)
一个 CharField
内容只限于文件系统内特定目录下的文件名,有几个特殊参数, 其中第一个是 必须的:
FilePathField.
path
-
必传。
FilePathField
应该得到的选择目录的绝对文件系统路径。例如:"/home/images"
.
FilePathField.
match
-
可选。 一个字符串形式的正则表达式。
FilePathField
使用其过滤文件名。 regex将应用于基本文件名,而不是全部路径。例如:"foo.*\.txt$"
将会匹配到foo23.txt
但不会匹配到bar.txt
或foo23.png
。
FilePathField.
recursive
-
可选。 只能是
True
或者False
。默认为False
。声明是否包含所有子目录的path
。
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
- class
django.db.models.
FloatField
(**options)
用Python的一个 float
实例来表示一个浮点数。
如果属性 localize
为 False
则默认表单部件是一个 NumberInput
, 否则是一个 TextInput
。
FloatField
vs. DecimalField
有时候 FloatField
类可能会和 DecimalField
类产生混淆。虽然它们表示都表示实数,但是二者表示数字的方式不一样。 FloatField
使用Python内部的 float
类型,而 DecimalField
使用的是Python的 Decimal
类型。 想要了解更多二者的差别, 可以查看Python文档中的 decimal
模块。
ImageField
- class
django.db.models.
ImageField
(upload_to=None, height_field=None, width_field=None, max_length=100, **options)
继承了:class:FileField 类的所有方法和属性,而且还对上传的对象进行校验,确保它是个有效的image。
除了从 FileField
继承的属性外, ImageField
类还增加了 height
和 width
属性。
为了更便捷的去用这些属性值, ImageField
有两个额外的可选参数:
ImageField.
height_field
-
该属性的设定会在模型实例保存时,自动填充图片的高度。
ImageField.
width_field
-
该属性的设定会在模型实例保存时,自动填充图片的宽度。
ImageField需要 Pillow 库支持。
ImageField
实例在数据库中以 varchar
类型存在,默认最大长度为100个字节, 和普通字段一样。也可以使用 max_length
参数限制。
该字段默认的表单部件是一个 ClearableFileInput
。
IntegerField
- class
django.db.models.
IntegerField
(**options)
一个整数。在Django所有支持的数据库中,-2147483648
到 2147483647
范围才是合法的。 如果设置了 localize
为 False
,那么默认表单部件将是一个 NumberInput
否则是一个 TextInput
。
GenericIPAddressField
- class
django.db.models.
GenericIPAddressField
(protocol='both', unpack_ipv4=False, **options)
一条IPv4或IPv6地址, 字符串格式是 (e.g. 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
。所有字符都转换为小写。
GenericIPAddressField.
protocol
-
限制指定协议的有效输入。接受的值为
'both'
(默认),'IPv4'
或'IPv6'
。匹配不区分大小写。
GenericIPAddressField.
unpack_ipv4
-
解析IPv4映射地址如
::ffff:192.0.2.1
. 如果启用该选项,则地址将被解析到192.0.2.1
。默认是禁用。只有当protocol
设置为'both'
时才可以使用。
如果允许空值,则必须允许null值,因为空值存储为null。
NullBooleanField
- class
django.db.models.
NullBooleanField
(**options)
类似 BooleanField
, 但是它允许 NULL
值。 可以用它来代替 BooleanField
字段设置 null=True
的情况。它的默认表单是 NullBooleanSelect
。
PositiveIntegerField
- class
django.db.models.
PositiveIntegerField
(**options)
类似 IntegerField
类型, 但必须是整数或者零 (0
)。 取值范围是 0
到 2147483647
。 允许 0
是为了向后兼容。
PositiveSmallIntegerField
- class
django.db.models.
PositiveSmallIntegerField
(**options)
类似 PositiveIntegerField
类型, 但其允许的值必须小于某个特定值 (有数据库决定)。在Django所支持的数据库中 0
到 32767
内的值是绝对允许的。
SlugField
- class
django.db.models.
SlugField
(max_length=50, **options)
Slug 是一个新闻术语, 通常叫做短标题。slug只能包含字母、数字、下划线或者是连字符。通常它们是用来放在URL里的。
类似 CharField 类型, 可以指定 max_length
(请参阅该部分中的有关数据库可移植性的说明和max_length
) 如果没有指定 max_length
属性,将默认使用50。
同时 Field.db_index
设置为 True
。
比较可行的做法是根据其他值的内容自动预填 SlugField 的值。 在admin中可以使用prepopulated_fields
来实现。
SlugField.
allow_unicode
-
如果设置为
True
, 该字段除了ASCII之外,还接受Unicode字母。默认为False
.
SmallIntegerField
- class
django.db.models.
SmallIntegerField
(**options)
类似 IntegerField
, 但只允许某些特定的值 (数据库决定)。 在Django所支持的数据库中 -32768
到 32767
之前是绝对允许的。
TextField
- class
django.db.models.
TextField
(**options)
大文本字段。默认的表单部件是一个 Textarea
。
如果指定了 max_length
属性, 它将会在渲染页面时表单部件 Textarea
中体现出来,但是却不会在模型和数据库中有这个限制。 如果需要这样清使用 CharField
类型。
MySQL 用户
如果在 MySQLdb 1.2.1p2 中使用该字段,并且是 utf8_bin
排序规则(默认*不是* 这个) 则需要注意几个问题。参考 MySQL database notes 。
TimeField
- class
django.db.models.
TimeField
(auto_now=False, auto_now_add=False, **options)
时间字段, 类似于Python datetime.time
实例. 和 DateField
具有相同的选项.
默认的表单部件是一个 TextInput
. 在Admin中添加了一些JavaScript快捷方式。
URLField
- class
django.db.models.
URLField
(max_length=200, **options)
一个 CharField
类型的URL.
默认的表单部件是一个 TextInput
.
与所有 CharField
子类一样, URLField
接受 max_length
可选参数. 如果没有特别指定 max_length
默认长度是200.
UUIDField
- class
django.db.models.
UUIDField
(**options)
一个用于存储唯一标识符的字段. 使用 Python 的 UUID
类. 如果使用 PostgreSQL, 将使用 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
注意传入的是一个可调用的对象(即一个省略括号的方法) 而不是传入一个 UUID
实例给 default
.
Field API参考
- class
django.db.models.
Field
-
Field
是一个抽象的类, 用来表示数据库中的表的列.Django使用字段创建数据库表(
db_type()
), 将Python类型映射到数据库(get_prep_value()
), 反之亦然(from_db_value()
).在各个版本的Django API中field是最根本的部分, 尤其是
models
和querysets
.在模型中, 字段被实例化为类的属性, 并表现为一个特定的表的列, 详情参考 模型. 它具有许多属性,如
null
和unique
等, 以及用于将字段值映射到数据库特定值的方法.Field
是RegisterLookupMixin
的子类, 因此可以在其上注册Transform
和Lookup
,也就可以在QuerySet
中使用(例如field_name__="foo"
). 所有 内置查询 都是默认注册好的.Django的所有内建字段,如
CharField
都是Field
的特殊实现. 如果需要自定义字段,则可以将任何内置字段重载,也可以重写一个新的Field
. 无论哪种情况,请参考 Writing custom model fields.description
-
字段的详细描述,例如用于
django.contrib.admindocs
应用程序.描述可以是以下形式:
description = _("String (up to %(max_length)s)")
其中参数从字段的
__dict__
去获取.
为了将
Field
映射到数据库特定类型,Django开放了几种方法:get_internal_type
()-
返回一个命名此字段的字符串用于后端特定用途. 默认情况下, 它返回类名.
有关自定义字段中的用法,请参见 Emulating built-in field types.
db_type
(connection)-
返回
Field
的数据库列数据类型,同时考虑connection
.有关自定义字段中使用 Custom database types.
rel_db_type
(connection)-
返回指向
Field
的字段的数据库列数据类型,例如ForeignKey
和OneToOneField
, 并考虑connection
.有关自定义字段中使用 Custom database types.
有三种主要情况,Django需要与数据库后端和字段交互:
- 当它查询数据库 (Python value -> database backend value)
- 当它从数据库加载数据 (database backend value -> Python value)
- 当它保存到数据库 (Python value -> database backend value)
查询时,
get_db_prep_value()
和get_prep_value()
将被用到:get_prep_value
(value)-
value
是模型属性的当前值, 该方法应返回用作查询的参数的格式数据.有关使用方法,请参阅 Converting Python objects to query values.
get_db_prep_value
(value, connection, prepared=False)-
将
value
转换为特定后端值. 如果设置prepared=True
,则默认返回value
. 如果为False
则返回get_prep_value()
.有关使用方法,请参阅 Converting query values to database values.
加载数据时
from_db_value()
将被使用:from_db_value
(value, expression, connection, context)-
将数据库返回的值转换为Python对象. 它与
get_prep_value()
相反.此方法不使用于大多数内置字段, 因为这些字段在数据库后端已返回正确的Python类型,或后端本身执行转换.
有关使用方法,请参阅 Converting values to Python objects.
注解
出于性能原因,
from_db_value
没有在不需要它的字段上实现(所有Django字段). 因此,您不能在定义中调用super
.
保存数据时,
pre_save()
和get_db_prep_save()
将被使用:get_db_prep_save
(value, connection)-
类似于
get_db_prep_value()
, 但仅仅在字段值一定会 保存 到数据库时调用. 默认返回get_db_prep_value()
.
pre_save
(model_instance, add)-
在
get_db_prep_save()
之前调用, 以在保存之前准备好值. (e.g. forDateField.auto_now
).model_instance
是该字段所属的实例,add
是首次将实例保存到数据库.它会返回此字段的
model_instance
适当属性的值. 属性名称位于self.attname
(这个由Field
设置)有关使用方法,请参阅 Preprocessing values before saving.
字段通常以不同的类型接收它们的值,无论是序列化还是表单.
to_python
(value)-
将value值转换为正确的python对象. 它作为
value_to_string()
的反向操作,也是在clean()
中调用.有关使用方法,请参阅 Converting values to Python objects.
除了保存到数据库,字段还需要知道如何序列化值:
value_to_string
(obj)-
将
obj
转换成字符串. 用于序列化字段的值.有关使用方法,请参阅 Converting field data for serialization.
使用
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
.
deconstruct
()-
返回足够多信息的4元元祖, 用来重新创建字段:
- 模型中的字段名称.
- 字段的导入路径 (e.g.
"django.db.models.IntegerField"
). - 这最好是能够兼容的版本,所以不要太具体更好.
- 字段的导入路径 (e.g.
- 位置参数列表.
- 关键词参数列表.
必须将此方法添加到1.7之前的字段, 才能使用 Migrations 迁移其数据.
字段属性参考
每个 Field
实例包含几个允许内省其行为的属性. 当需要编写依赖于字段功能的代码时,就可以使用这些属性而不是 isinstance
检查. 这些属性可以与 Model._meta API 一起使用, 缩小搜索特定字段类型的范围.自定义模型字段应实现这些标志.
字段属性
Field.
auto_created
-
布尔标志, 指示是否自动创建字段, 例如模型继承使用的
OneToOneField
.
Field.
concrete
-
布尔标志, 指示字段是否具有与其相关联的数据库列.
-
布尔标志, 指示字段是否用于支持另一个非隐藏字段的功能. (e.g.
content_type
和object_id
构成了字段GenericForeignKey
).hidden
标志用于区分模型上的公共字段子集构成模型上的所有字段.注解
Options.get_fields()
默认不返回隐藏字段. 可以通过设置include_hidden=True
返回隐藏字段.
Field.
is_relation
-
布尔标志,表示字段是否包含对一个或多个其他模型的引用. (e.g.
ForeignKey
,ManyToManyField
,OneToOneField
, etc.).
Field.
model
-
返回定义字段的模型。如果在模型的超类上定义了一个字段,
model
将引用父类,而不是实例的类.
关系字段属性
这些属性用于查询关系的基数和其他详细信息. 这些属性存在于所有字段中; 但是, 如果该字段是关系类型 ( Field.is_relation=True
) 它们将只有布尔值 (而不是 None
).
Field.
many_to_many
-
布尔标志, 如果该字段具有多对多关系,则为
True
; 否则False
. Django中只有ManyToManyField
为True
.
Field.
many_to_one
-
布尔标志, 如果字段具有多对一关联关系则为
True
. 比如ForeignKey
; 其他为False
.
Field.
one_to_many
-
布尔标志, 如果字段具有一对多关联关系则为
True
. 比如GenericRelation
或者反向ForeignKey
; 其他情况为False
.
Field.
one_to_one
-
布尔标志, 如果字段具有一对一关联关系则为
True
.比如OneToOneField
; 其他情况为False
.
-
指向字段关联的模型. 例如,
ForeignKey(Author, on_delete=models.CASCADE)
中的Author
.GenericForeignKey
中的related_model
始终为None
.