字段选项
空值
Field.null
如果为True,Django将在数据库中将空值存储为NULL。默认值是 False。
字符串字段例如CharField 和TextField 要避免使用null,因为空字符串值将始终储存为空字符串而不是NULL。如果字符串字段的null=True,那意味着对于“无数据”有两个可能的值:NULL 和空字符串。在大多数情况下,对于“无数据”声明两个值是赘余的,Django 的惯例是使用空字符串而不是NULL。
无论是字符串字段还是非字符串字段,如果你希望在表单中允许空值,你将还需要设置blank=True,因为null 仅仅影响数据库存储(参见blank)。
如果你希望BooleanField 接受null 值,请用 NullBooleanField 代替。
字段类型
BooleanField
class BooleanField(**options)
true/false 字段。
此字段的默认表单挂件是一个CheckboxInput.
如果你需要设置null 值,则使用NullBooleanField 来代替BooleanField。
如果Field.default没有指定的话, BooleanField 的默认值是 None。
CommaSeparatedIntegerField
class CommaSeparatedIntegerField(max_length=None[, **options])
一个逗号分隔的整数字段。像 CharField一样, 需要一个max_length 参数, 同时数据库移植时也需要注意
DateField
class DateField([auto_now=False, auto_now_add=False, **options])
这是一个使用Python的datetime.date实例表示的日期. 有几个额外的设置参数:
DateField.auto_now
每次保存对象时,自动设置该字段为当前时间。用于"最后一次修改"的时间戳。注意,它总是使用当前日期;它不只是一个默认值,你可以覆盖。
DateField.auto_now_add
当对象第一次被创建时自动设置当前时间。用于创建时间的时间戳. 它总是使用当前日期;和你可以覆盖的那种默认值不一样。
auto_now_add, auto_now, and default 这些设置是相互排斥的. 他们之间的任何组合将会发生错误的结果.
注意
在目前的实现中,设置auto_now或者auto_now_add为True将为让这个字段同时得到editable=False和blank=True这两个设置.
注意
auto_now and auto_now_add这两个设置会在对象创建或更新的时刻,总是使用default timezone(默认时区)的日期.如果你不想这样,你可以考虑一下简单地使用你自己的默认调用或者重写save()(在save()函数里自己添加保存时间的机制.译者注)而不是使用auto_now 或者 auto_now_add;也可以使用DateTimeField字段类来替换DateField并且在给用户呈现时间的时候,决定如何处理从datetime到date的转换.
DateTimeField
class DateTimeField([auto_now=False, auto_now_add=False, **options])
它是通过Python datetime.datetime实例表示的日期和时间. 携带了跟DateField一样的额外参数.
该字段默认对应的表单控件是一个单个的TextInput(单文本输入框). 管理界面是使用两个带有 JavaScript控件的 TextInput 文本框
EmailField
class EmailField([max_length=254, **options])
一个 CharField 用来检查输入的email地址是否合法。它使用 EmailValidator 来验证输入合法性
FileField
class FileField([upload_to=None, max_length=100, **options])
一个上传文件的字段。
有两个可选参数:
FileField.upload_to¶
Changed in Django 1.7:
一个本地文件系统的路径,它将附加到MEDIA_ROOT 设置的后面来确定url 属性的值。
FileField.storage
一个Storage 对象,用于你的文件的存取。参见管理文件 获取如何提供这个对象的细节FileField.storage¶
class Banner(models.Model): title = models.CharField(max_length=100, verbose_name='标题') # 存放的是图片的路径地址 image = models.ImageField(upload_to='banner/%Y/%m', verbose_name='轮播', max_length=100) url = models.URLField(max_length=200, verbose_name='访问地址')
配置上传文件路径
MEDIA_URL = '/media/' MEDIA_ROOT = os.path.join(BASE_DIR, 'media') # 上传图片的路径
FileField 和FieldFile
class FieldFile[source]
当你添加 FileField 到你的模型中时, 你实际上会获得一个 FieldFile的实例来替代将要访问的文件。 除了继承至 django.core.files.File的功能外, 这个类还有其他属性和方法可以用于访问文件:
FieldFile.url
通过潜在Storage 类的url()方法可以只读地访问文件的URL。
FieldFile.open(mode='rb')[source]
该方法像标准的Python open() 方法,并可通过 mode参数设置打开模式.
FieldFile.close()[source]
该方法像标准的Pythonfile.close() 方法,并关闭相关文件.
FieldFile.save(name, content, save=True)[source]
这个方法会将文件名以及文件内容传递到字段的storage类中,并将模型字段与保存好的文件关联. 如果想要手动关联文件数据到你的模型中的 FileField实例, 则save() 方法总是用来保存该数据.
方法接受两个必选参数: name 文件名, 和 content 文件内容.可选参数save 控制模型实例在关联的文件被修改时是否保存.默认为 True.
注意参数 content 应该是 django.core.files.File的一个实例, 而不是Python内建的File对象.你可以用如下方法从一个已经存在的Python文件对象来构建 File :
from django.core.files import File # Open an existing file using Python's built-in open() f = open('/tmp/hello.world') myfile = File(f)
或者,你可以像下面的一样从一个python字符串中构建
from django.core.files.base import ContentFile myfile = ContentFile("hello world")
FieldFile.delete(save=True)[source]¶
删除与此实例关联的文件,并清除该字段的所有属性。注意︰ 如果它碰巧是开放的调用 delete() 方法 时,此方法将关闭该文件。
FilePathField
class FilePathField(path=None[, match=None, recursive=False, max_length=100, **options])
一个 CharField ,内容只限于文件系统内特定目录下的文件名。有三个参数, 其中第一个是 必需的:
FilePathField.path
必填。这个FilePathField 应该得到其选择的目录的绝对文件系统路径。例如: "/home/images".
FilePathField.match
可选的.FilePathField 将会作为一个正则表达式来匹配文件名。但请注意正则表达式将将被作用于基本文件名,而不是完整路径。例如: "foo.*.txt$", 将会匹配到一个名叫 foo23.txt 的文件,但不匹配到 bar.txt或者 foo23.png.
FilePathField.recursive
可选的.True 或 False.默认是False.声明是否包含所有子目录的路径
FilePathField.allow_files
可选的.True 或 False.默认是True.声明是否包含指定位置的文件。该参数或allow_folders 中必须有一个为True.
FilePathField.allow_folders
是可选的.输入 True 或者 False.默认值为 False.声明是否包含指定位置的文件夹。该参数或 allow_files中必须有一个为 True.
当然,这些参数可以同时使用。
有一点需要提醒的是 match只匹配基本文件名(base filename), 而不是整个文件路径(full path). 例如:
FilePathField(path="/home/images", match="foo.*", recursive=True)
...将匹配/home/images/foo.png而不是/home/images/foo/bar.png 因为只允许匹配 基本文件名(foo.png和 bar.png).
FilePathField实例被创建在您的数据库为varchar列默认最大长度为 100 个字符。作为与其他字段,您可以更改使用的max_length最大长度。
ImageField
class ImageField([upload_to=None, height_field=None, width_field=None, max_length=100, **options])
继承了 FileField的所有属性和方法, 但还对上传的对象进行校验,确保它是个有效的image.
除了从FileField继承来的属性外,ImageField 还有宽和 高属性。
为了更便捷的去用那些属性值, ImageField 有两个额外的可选参数
ImageField.height_field
该属性的设定会在模型实例保存时,自动填充图片的高度.
ImageField.width_field
该属性的设定会在模型实例保存时,自动填充图片的宽度.
ImageField字段需要调用Pillow 库.
ImageField会创建在你的数据库中 和 varchar 一样,默认最大长度为100和其他字段一样, 你可以使用max_length 参数来设置默认文件最大值.此字段的默认表单工具是ClearableFileInput.
GenericIPAddressField
class GenericIPAddressField([protocol=both, unpack_ipv4=False, **options])
一个 IPv4 或 IPv6 地址, 字符串格式 (例如 192.0.2.30 或 2a02:42fe::4). 这个字段的默认表单小部件是一个TextInput.
NullBooleanField
class NullBooleanField([**options])
类似BooleanField, 但是允许 NULL 作为一个选项.使用此代替null=True的BooleanField。此字段的默认表单widget为NullBooleanSelect。
PositiveIntegerField(正整数字段)
class PositiveIntegerField([**options])
类似 IntegerField, 但值必须是正数或者零(0). 从0到2147483647的值在Django支持的所有数据库中都是安全的。由于向后兼容性原因,接受值0
URLField
class URLField([max_length=200, **options])
一个CharField 类型的URL
此字段的默认表单widget为TextInput。
与所有CharField子类一样,URLField接受可选的max_length参数。如果不指定max_length,则使用默认值200。
关系字段
ForeignKey
ManyToManyField
OneToOneField
Field API 参考
class Field
Field 是一个抽象的类, 用来代表数据库中的表的一列. Django 使用这些fields 去创建表 (db_type()), 去建立Python中的类型和数据库中类型的映射关系 (get_prep_value()) 反之亦然 (from_db_value()), 并且实现Lookup API reference (get_prep_lookup()).