型号字段参考

本文档包含Field的所有API参考,包括Django提供的字段选项字段类型

也可以看看

如果内置的字段没有办法,你可以尝试django-localflavor tt>(documentation),它包含了对特定国家有用的代码段文化。

而且,您可以轻松write your own custom model fields

注意

Technically, these models 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

避免在基于字符串的字段(如CharFieldTextField)上使用null 如果一个基于字符串的字段有null=True,这意味着它有两个可能的值为“no data”:NULL和空字符串。 在大多数情况下,对于“无数据”有两个可能的值是多余的,Django惯例是使用空字符串,而不是NULL 一个例外是当一个CharField同时设置unique=Trueblank=True时。 在这种情况下,当保存具有空白值的多个对象时,需要null=True来避免唯一的约束违规。

对于基于字符串的字段和基于非字符串的字段,如果您希望允许表单中的空值,则还需要将blank=True设置为null参数仅影响数据库存储(请参阅blank)。

注意

当使用Oracle数据库后端时,无论此属性如何,都将存储NULL值来表示空字符串。

If you want to accept null values with BooleanField, use NullBooleanField instead.

blank

Field.blank

如果True,则允许该字段为空。 默认是False

请注意,这不同于null null纯粹与数据库相关,而blank与验证相关。 如果一个字段有blank=True,表单验证将允许输入一个空值。 如果一个字段有blank=False,则该字段将是必需的。

choices

Field.choices

An iterable (e.g., a list or tuple) consisting itself of iterables of exactly two items (e.g. [(A, B), (A, B) ...]) to use as choices for this field. 如果这是给定的,默认的表单小部件将是一个选择框与这些选择,而不是标准的文本字段。

每个元组中的第一个元素是要在模型上设置的实际值,第二个元素是人类可读的名称。 例如:

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()

请注意,选择可以是任何可迭代对象 - 不一定是列表或元组。 这可以让你动态地构建选择。 But if you find yourself hacking choices to be dynamic, you’re probably better off using a proper database table with a ForeignKey. choices is meant for static data that doesn’t change much, if ever.

除非blank=Falsedefault一起在字段中设置,那么包含"---------"的标签将使用选择框进行渲染。 To override this behavior, add a tuple to choices containing None; e.g. (None, 'Your String For Display'). 或者,你可以使用一个空字符串,而不是None,这是有道理的,比如在CharField上。

db_column

Field.db_column

用于此字段的数据库列的名称。 如果没有给出,Django将使用该字段的名称。

如果您的数据库列名是SQL保留字,或者包含Python变量名中不允许使用的字符(特别是连字符),那就OK了。 Django在幕后引用列名和表名。

db_index

Field.db_index

如果True,则会为此字段创建一个数据库索引。

db_tablespace

Field.db_tablespace

如果此字段已编入索引,则用于此字段索引的database tablespace的名称。 缺省值是项目的DEFAULT_INDEX_TABLESPACE设置(如果已设置)或模型的db_tablespace(如果有)。 如果后端不支持索引的表空间,则忽略此选项。

default

Field.default

字段的默认值。 这可以是一个值或一个可调用的对象。 如果可调用,则每次创建新对象时都会调用它。

默认不能是一个可变对象(模型实例,listset等),作为对象的同一个实例的引用将被用作所有新模型实例中的默认值。 相反,将所需的默认值包装为可调用的。 例如,如果你想为JSONField指定一个默认的dict,使用一个函数:

def contact_default():
    return {"email": "to1@example.com"}

contact_info = JSONField("ContactInfo", default=contact_default)

lambdas can’t be used for field options like default because they can’t be serialized by migrations. 请参阅该文档以了解其他注意事项。

对于映射到模型实例的ForeignKey等字段,缺省值应该是它们引用字段的值(pk,除非设置to_field)而不是模型实例。

创建新模型实例时使用默认值,并且未为该字段提供值。 当该字段是主键时,当字段设置为None时,也使用默认值。

editable

Field.editable

如果False,该字段将不会显示在管理员或任何其他ModelForm中。 它们在model validation期间也被跳过。 默认是True

error_messages

领域。 error_messages T0> ¶ T1>

error_messages参数允许您覆盖该字段将引发的默认消息。 传入一个与您要覆盖的错误消息匹配的密钥的字典。

错误消息键包括nullblankinvalidinvalid_choiceunique unique_for_date 下面的字段类型部分中的每个字段都指定了其他错误消息键。

这些错误信息通常不会传播到表单。 请参阅Considerations regarding model’s error_messages

help_text

领域。 help_text T0> ¶ T1>

额外的“帮助”文本与窗体小部件一起显示。 即使您的字段没有在表单上使用,对于文档也是有用的。

请注意,该值在自动生成的表单中是转义的不是 如果您愿意,可以在help_text中包含HTML。 例如:

help_text="Please use the following format: <em>YYYY-MM-DD</em>."

或者,您可以使用纯文本和django.utils.html.escape()来转义任何HTML特殊字符。 确保您转义任何来自不受信任的用户的帮助文本,以避免跨站点脚本攻击。

primary_key

领域。 primary_key T0> ¶ T1>

如果True,则该字段是模型的主键。

如果你没有为模型中的任何字段指定primary_key=True,Django将自动添加AutoField来保存主键,所以你不需要设置primary_key=True,除非你想覆盖默认的主键行为。 有关更多信息,请参阅Automatic primary key fields

primary_key=True意味着null=Falseunique=True 一个对象只允许有一个主键。

主键字段是只读的。 如果您更改现有对象上主键的值并保存,则会在旧对象旁边创建一个新对象。

unique

领域。独特 T0> ¶ T1>

如果True,则该字段在整个表中必须是唯一的。

这是在数据库级和模型验证实施的。 If you try to save a model with a duplicate value in a unique field, a django.db.IntegrityError will be raised by the model’s save() method.

此选项在ManyToManyFieldOneToOneField以外的所有字段类型中均有效。

请注意,当uniqueTrue时,您不需要指定db_index,因为unique意味着创建索引。

在Django 1.11中更改:

在旧版本中,unique=True不能在FileField上使用。

unique_for_date

领域。 unique_for_date T0> ¶ T1>

将其设置为DateFieldDateTimeField的名称,以要求该字段对于日期字段的值是唯一的。

For example, if you have a field title that has unique_for_date="pub_date", then Django wouldn’t allow the entry of two records with the same title and pub_date.

请注意,如果您将其设置为指向DateTimeField,则只会考虑字段的日期部分。 此外,当USE_TZTrue时,将在保存对象时在current time zone执行检查。

这在模型验证期间由Model.validate_unique()实施,但不在数据库级。 If any unique_for_date constraint involves fields that are not part of a ModelForm (for example, if one of the fields is listed in exclude or has editable=False), Model.validate_unique() will skip validation for that particular constraint.

unique_for_month

领域。 unique_for_month T0> ¶ T1>

unique_for_date,但要求该字段相对于该月份是唯一的。

unique_for_year

领域。 unique_for_year T0> ¶ T1>

unique_for_dateunique_for_month

verbose_name

领域。 verbose_name T0> ¶ T1>

该字段的人类可读名称。 如果没有给出详细名称,Django将使用字段的属性名称自动创建它,将下划线转换为空格。 请参阅Verbose field names

validators

领域。验证 T0> ¶ T1>

要为此字段运行的验证程序列表。 有关更多信息,请参阅validators documentation

注册和提取查找

Field实现lookup registration API 该API可用于定制哪些查找可用于字段类,以及如何从字段中提取查找。

字段类型

AutoField

AutoField(**options)[source]

根据可用ID自动递增的IntegerField 你通常不需要直接使用它;如果不另外指定,则主键字段将自动添加到您的模型中。 请参阅Automatic primary key fields

BigAutoField

BigAutoField(**options)[source]

一个64位的整数,非常类似于AutoField,除了保证符合从19223372036854775807的数字。

BigIntegerField

BigIntegerField(**options)[source]

一个64位的整数,就像一个IntegerField,除了保证符合从-92233720368547758089223372036854775807的数字。 该字段的默认表单部件是TextInput

BinaryField

BinaryField(**options)[source]

用于存储原始二进制数据的字段。 它只支持bytes分配。 请注意,此字段的功能有限。 例如,不能过滤BinaryField值上的查询集。 ModelForm中包含BinaryField也是不可能的。

滥用BinaryField

尽管您可能会考虑将数据存储在数据库中,但考虑到这种情况在99%的情况下是不好的设计。 这个字段是不是正确的static files处理的替代。

BooleanField

BooleanField(**options)[source]

真实/虚假的领域。

这个字段的默认表单控件是一个CheckboxInput

如果您需要接受null值,请改为使用NullBooleanField

当没有定义Field.default时,BooleanField的默认值是None

CharField

CharFieldmax_length = None** options[source]

一个字符串字段,用于从小到大的字符串。

对于大量文本,请使用TextField

该字段的默认表单部件是TextInput

CharField has one extra required argument:

CharField。 MAX_LENGTH T0> ¶ T1>

字段的最大长度(以字符为单位)。 max_length是在数据库级别和Django验证中强制执行的。

注意

If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on max_length for some backends. 有关详细信息,请参阅database backend notes

DateField

DateField(auto_now=False, auto_now_add=False, **options)[source]

日期,用Python表示的一个datetime.date实例。 有一些额外的,可选的参数:

的DateField。 auto_now T0> ¶ T1>

每次保存对象时自动将该字段设置为现在。 用于“上次修改”时间戳。 Note that the current date is always used; it’s not just a default value that you can override.

调用Model.save()时,该字段只会自动更新。 当以其他方式(如QuerySet.update())更新其他字段时,字段不会更新,但可以像更新那样为字段指定自定义值。

的DateField。 auto_now_add T0> ¶ T1>

首次创建对象时自动将字段设置为现在。 用于创建时间戳。 Note that the current date is always used; it’s not just a default value that you can override. 所以即使你在创建对象时为这个字段设置了一个值,它也将被忽略。 如果您希望能够修改此字段,请设置以下字段而不是auto_now_add=True

该字段的默认表单部件是TextInput 管理员添加了JavaScript日历和“今天”的快捷方式。 包含一个额外的invalid_date错误消息密钥。

选项auto_now_addauto_nowdefault是互斥的。 这些选项的任何组合都会导致错误。

注意

按照目前的实施,将auto_nowauto_now_add设置为True将会使字段具有editable=Falseblank=True设置。

注意

在创建或更新时,auto_nowauto_now_add选项将始终使用default timezone中的日期。 If you need something different, you may want to consider simply using your own callable default or overriding save() instead of using auto_now or auto_now_add; or using a DateTimeField instead of a DateField and deciding how to handle the conversion from datetime to date at display time.

DateTimeField

DateTimeField(auto_now=False, auto_now_add=False, **options)[source]

一个日期和时间,在Python中由datetime.datetime实例表示。 采用与DateField相同的额外参数。

该字段的默认表单部件是一个TextInput 管理员使用两个独立的TextInput小部件和JavaScript快捷方式。

DecimalField

DecimalField(max_digits=None, decimal_places=None, **options)[source]

一个固定精度的十进制数,在Python中由Decimal实例表示。 有两个必需的参数:

DecimalField。 max_digits T0> ¶ T1>

号码中允许的最大位数。 请注意,此数字必须大于或等于decimal_places

DecimalField。 decimal_places T0> ¶ T1>

与数字一起存储的小数位数。

例如,要将分辨率为2位小数的数字存储到999,您可以使用:

models.DecimalField(..., max_digits=5, decimal_places=2)

而要存储数量达10亿左右的小数点后10个位数:

models.DecimalField(..., max_digits=19, decimal_places=10)

localizeFalseTextInput时,此字段的默认表单窗口小部件为NumberInput

注意

有关FloatFieldDecimalField类之间差异的更多信息,请参阅FloatField vs. DecimalField

DurationField

DurationField(**options)[source]

一个用于存储时间的字段 - 由timedelta在Python中建模。 When used on PostgreSQL, the data type used is an interval and on Oracle the data type is INTERVAL DAY(9) TO SECOND(6). Otherwise a bigint of microseconds is used.

注意

在大多数情况下,使用DurationField进行算术运算。 但是,除PostgreSQL以外的所有数据库,将DurationField的值与DateTimeField实例的算术值进行比较将无法按预期进行。

EmailField

EmailFieldmax_length = 254**选项[source]

一个CharField,用于检查该值是否为有效的电子邮件地址。 它使用EmailValidator来验证输入。

FileField

class FileField(upload_to=None, max_length=100, **options)[source]

文件上传字段。

注意

不支持primary_key参数,如果使用,会引发错误。

有两个可选参数:

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 may also be a callable, such as a function. 这将被调用来获取上传路径,包括文件名。 这个可调用的方法必须接受两个参数,并返回一个Unix风格的路径(带正斜杠)传递给存储系统。 两个论点是:

论据 描述

定义了FileField的模型实例。 更具体地说,这是当前文件被附加的特定实例。

在大多数情况下,这个对象还没有被保存到数据库中,所以如果它使用默认的AutoField它可能还没有一个主键字段的值

文件名 最初提供给文件的文件名。 在确定最终目的地路径时,这可能会也可能不会被考虑在内。

例如:

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

存储对象,用于处理文件的存储和检索。 有关如何提供此对象的详细信息,请参见Managing files

该字段的默认表单部件是ClearableFileInput

在模型中使用FileFieldImageField(见下文)需要几个步骤:

  1. 在您的设置文件中,您需要将MEDIA_ROOT定义为您希望Django存储上传文件的目录的完整路径。 (对于性能,这些文件不存储在数据库中。) MEDIA_URL定义为该目录的基本公用URL。 确保该目录可由Web服务器的用户帐户写入。
  2. FileFieldImageField添加到您的模型中,定义upload_to选项以指定要使用的MEDIA_ROOT的子目录上传的文件。
  3. 所有将存储在数据库中的文件都是一个路径(相对于MEDIA_ROOT)。 你很可能想使用Django提供的方便的url属性。 For example, if your ImageField is called mug_shot, you can get the absolute path to your image in a template with {{ object.mug_shot.url }}.

例如,假设您的MEDIA_ROOT设置为'/home/media'upload_to设置为'photos/%Y/%m/%d' The '%Y/%m/%d' part of upload_to is strftime() formatting; '%Y' is the four-digit year, '%m' is the two-digit month and '%d' is the two-digit day. 如果您在2007年1月15日上传文件,它将被保存在/home/media/photos/2007/01/15目录中。

如果要检索上传文件的磁盘文件名或文件大小,可分别使用namesize属性;有关可用属性和方法的更多信息,请参阅File类引用和Managing files主题指南。

注意

该文件作为模型保存在数据库中的一部分进行保存,因此在保存模型之后,不能依赖磁盘上使用的实际文件名。

上传文件的相对URL可以使用url属性获取。 在内部,它调用底层Storage类的url()方法。

请注意,无论何时处理上传的文件,都应密切注意您上传的文件的位置以及它们的类型,以避免安全漏洞。 验证所有上传的文件,以确保文件是您认为的文件。 例如,如果您盲目地让某人上传文件(无需验证)到Web服务器文档根目录中的某个目录,则有人可以上传CGI或PHP脚本,并通过访问您网站上的URL来执行该脚本。 不要让这个。

还要注意,即使是上传的HTML文件,由于它可以被浏览器(尽管不是由服务器执行)执行,也可能构成与XSS或CSRF攻击等效的安全威胁。

FileField instances are created in your database as varchar columns with a default max length of 100 characters. 与其他字段一样,您可以使用max_length参数更改最大长度。

FileFieldFieldFile

class FieldFile[source]

在模型上访问FileField时,会为您提供FieldFile的实例作为访问基础文件的代理。

FieldFile的API反映了File的API,唯一的区别在于: 由类包装的对象不一定是Python内置文件对象的包装。 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

文件的名称,包括相关FileFieldStorage根目录的相对路径。

FieldFile.size

底层的Storage.size()方法的结果。

FieldFile.url

通过调用底层Storage类的url()方法来访问文件相对URL的只读属性。

FieldFile.open(mode='rb')[source]

以指定的mode打开或重新打开与此实例关联的文件。 与标准的Python open()方法不同,它不返回文件描述符。

由于底层文件在访问时是隐式打开的,因此可能不需要调用此方法,除非将指针重置为底层文件或更改mode

FieldFile.close()[source]

行为与标准的Python file.close()方法类似,并关闭与此实例关联的文件。

FieldFile.save(name, content, save=True)[source]

此方法将文件名和文件内容传递给字段的存储类,然后将存储的文件与模型字段相关联。 如果要手动将文件数据与模型上的FileField实例相关联,则使用save()方法来保留该文件数据。

Takes two required arguments: name which is the name of the file, and content which is an object containing the file’s contents. 可选的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)[source]

删除与此实例关联的文件,并清除该字段上的所有属性。 注意:当调用delete()时,这个方法会关闭文件。

可选的save参数控制在与该字段关联的文件被删除后是否保存模型实例。 默认为True

请注意,删除模型时,相关文件不会被删除。 如果您需要清理孤立的文件,则需要自己处理(例如,使用自定义管理命令,可以手动运行或计划通过例如cron定期运行)。

FilePathField

class FilePathField(path=None, match=None, recursive=False, max_length=100, **options)[source]

一个CharField,它们的选择仅限于文件系统上某个目录中的文件名。 有三个特殊的论点,其中第一个是要求

FilePathField.path

需要。 The absolute filesystem path to a directory from which this FilePathField should get its choices. 例如:"/home/images"

FilePathField.match

可选的。 一个正则表达式,作为一个字符串,FilePathField将用于过滤文件名。 请注意,正则表达式将应用于基本文件名,而不是完整路径。 例: “富。* \。TXT $”,它将匹配一个名为foo23.txt但不是bar.txtfoo23.png的文件。

FilePathField.recursive

可选的。 可以是TrueFalse 默认是False 指定是否应包含path的所有子目录

FilePathField.allow_files

可选的。 可以是TrueFalse 默认是True 指定是否应该包含指定位置的文件。 这个或者allow_folders必须是True

FilePathField.allow_folders

可选的。 可以是TrueFalse 默认是False 指定是否应该包含指定位置的文件夹。 这个或者allow_files必须是True

当然,这些参数可以一起使用。

一个潜在的问题是match适用于基本文件名,而不是完整路径。 所以,这个例子:

FilePathField(path="/home/images", match="foo.*", recursive=True)

...匹配/home/images/foo.png,但不匹配/home/images/foo/bar.png,因为match适用于基本文件名(foo.pngbar.png)。

FilePathField instances are created in your database as varchar columns with a default max length of 100 characters. 与其他字段一样,您可以使用max_length参数更改最大长度。

FloatField

FloatField(**options)[source]

Python中由float实例表示的浮点数。

localizeFalseTextInput时,此字段的默认表单窗口小部件为NumberInput

FloatFieldDecimalField

有时将FloatField类与DecimalField类混淆。 尽管它们都代表实数,但它们代表的数字不同。 FloatField uses Python’s float type internally, while DecimalField uses Python’s Decimal type. 有关这两者之间的区别的信息,请参阅decimal模块的Python文档。

ImageField

ImageField(upload_to=None, height_field=None, width_field=None, max_length=100, **options)[source]

继承FileField中的所有属性和方法,但也验证上传的对象是否是有效的图像。

除了可用于FileField的特殊属性之外,ImageField还具有heightwidth属性。

To facilitate querying on those attributes, ImageField has two extra optional arguments:

的ImageField。 height_field T0> ¶ T1>

每次保存模型实例时将使用图像的高度自动填充模型字段的名称。

的ImageField。 width_field T0> ¶ T1>

每次保存模型实例时将使用图像宽度自动填充模型字段的名称。

需要枕头库。

ImageField instances are created in your database as varchar columns with a default max length of 100 characters. 与其他字段一样,您可以使用max_length参数更改最大长度。

该字段的默认表单部件是ClearableFileInput

IntegerField

IntegerField(**options)[source]

一个整数。 -21474836482147483647的值在Django支持的所有数据库中都是安全的。 localizeFalseTextInput时,此字段的默认表单窗口小部件为NumberInput

GenericIPAddressField

GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)[source]

字符串格式的IPv4或IPv6地址(例如192.0.2.302a02: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。协议 T0> ¶ T1>

限制有效的输入到指定的协议。 接受的值是'both'(默认),'IPv4''IPv6' 匹配不区分大小写。

GenericIPAddressField。 unpack_ipv4 T0> ¶ T1>

解压IPv4映射地址,如::ffff:192.0.2.1 如果启用此选项,则该地址将被解压到192.0.2.1 默认是禁用的。 只能在protocol设置为'both'时使用。

如果允许空白值,则必须允许空值,因为空白值存储为空。

NullBooleanField

NullBooleanField(**options)[source]

就像一个BooleanField,但允许NULL作为其中一个选项。 null=True代替BooleanField 该字段的默认表单控件是一个NullBooleanSelect

PositiveIntegerField

PositiveIntegerField(**options)[source]

IntegerField一样,但必须是正数或零(0)。 在Django支持的所有数据库中,02147483647的值是安全的。 出于向后兼容性原因,接受值0

PositiveSmallIntegerField

PositiveSmallIntegerField(**options)[source]

PositiveIntegerField一样,但只允许某个(数据库相关)点下的值。 在Django支持的所有数据库中,032767的值是安全的。

SlugField

SlugField(max_length=50, **options)[source]

Slug is a newspaper term. 一个slu is是一个短的标签的东西,只包含字母,数字,下划线或连字符。 它们通常用在URL中。

就像CharField一样,你可以指定max_length(阅读关于数据库可移植性的注释和max_length)。 如果未指定max_length,则Django将使用默认长度50。

意味着将Field.db_index设置为True

根据其他值的值自动预填充SlugField通常是有用的。 您可以使用prepopulated_fields自动在管理员中执行此操作。

SlugField。 allow_unicode T0> ¶ T1>

如果True,该字段除ASCII字母外还接受Unicode字母。 默认为False

SmallIntegerField

SmallIntegerField(**options)[source]

像一个IntegerField,但只允许某个(数据库相关)点下的值。 在Django支持的所有数据库中,-3276832767的值是安全的。

TextField

TextField(**options)[source]

一个大的文本字段。 这个字段的默认表单部件是一个Textarea

如果指定了max_length属性,它将反映在自动生成的表单字段的Textarea小部件中。 但是,它不是在模型或数据库级别执行的。 为此,请使用CharField

TimeField

TimeField(auto_now=False, auto_now_add=False, **options)[source]

一段时间,在Python中由datetime.time实例表示。 接受与DateField相同的自动填充选项。

该字段的默认表单部件是TextInput 管理员添加了一些JavaScript快捷方式。

URLField

URLFieldmax_length = 200**选项[source]

一个URL的CharField

该字段的默认表单部件是TextInput

像所有的CharField子类一样,URLField采用可选的max_length参数。 如果您不指定max_length,则使用默认值200。

UUIDField

UUIDField(**options)[source]

用于存储通用唯一标识符的字段。 使用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的实例。

关系字段

Django还定义了一组代表关系的字段。

ForeignKey

ForeignKeytoon_delete** options[source] ¶ T6>

多对一的关系。 需要两个位置参数:模型相关的类和on_delete选项。

To create a recursive relationship – an object that has a many-to-one relationship with itself – use models.ForeignKey('self', on_delete=models.CASCADE).

If you need to create a relationship on a model that has not yet been defined, you can use the name of the model, rather than the model object itself:

from django.db import models

class Car(models.Model):
    manufacturer = models.ForeignKey(
        'Manufacturer',
        on_delete=models.CASCADE,
    )
    # ...

class Manufacturer(models.Model):
    # ...
    pass

当模型被作为一个具体的模型进行子类化,而不是与抽象模型的app_label相关时,在abstract models

产品/ models.py
from django.db import models

class AbstractCar(models.Model):
    manufacturer = models.ForeignKey('Manufacturer', on_delete=models.CASCADE)

    class Meta:
        abstract = True
生产/ models.py
from django.db import models
from products.models import AbstractCar

class Manufacturer(models.Model):
    pass

class Car(AbstractCar):
    pass

# Car.manufacturer will point to `production.Manufacturer` here.

要引用另一个应用程序中定义的模型,可以使用完整的应用程序标签明确指定一个模型。 例如,如果上面的Manufacturer模型在另一个名为production的应用程序中定义,那么您需要使用:

class Car(models.Model):
    manufacturer = models.ForeignKey(
        'production.Manufacturer',
        on_delete=models.CASCADE,
    )

当解决两个应用程序之间的循环导入依赖关系时,这种称为懒惰关系的引用可能很有用。

数据库索引自动创建在ForeignKey上。 您可以通过将db_index设置为False来禁用此功能。 如果要为一致性而不是连接创建外键,或者要创建一个可选索引(如部分或多列索引),则可能需要避免索引的开销。

数据库表示

Django在后台添加"_id"字段名称来创建其数据库列名称。 在上面的例子中,Car模型的数据库表将有一个manufacturer_id列。 (你可以通过指定db_column来明确地改变它)但是,除非你编写自定义的SQL,否则你的代码不应该处理数据库的列名。 你总是处理你的模型对象的字段名称。

参数¶ T0>

ForeignKey accepts other arguments that define the details of how the relation works.

ForeignKey的。 on_delete T0> ¶ T1>

当一个ForeignKey引用的对象被删除时,Django将模拟on_delete参数指定的SQL约束的行为。 例如,如果您有一个可以为空的ForeignKey,并且希望在删除引用的对象时将其设置为null:

user = models.ForeignKey(
    User,
    models.SET_NULL,
    blank=True,
    null=True,
)

可以在django.db.models中找到on_delete的可能值:

  • CASCADE[source]

    级联删除。 Django模拟SQL约束ON DELETE CASCADE的行为,并删除包含ForeignKey的对象。

  • PROTECT[source]

    通过引发ProtectedErrordjango.db.IntegrityError的子类)来防止删除引用的对象。

  • SET_NULL[source]

    设置ForeignKey null;这只有在nullTrue的情况下才有可能。

  • SET_DEFAULT[source]

    ForeignKey设置为其默认值;必须设置ForeignKey的默认值。

  • SET()[source]

    ForeignKey设置为传递给SET()的值,或者如果传递了可调用对象,则调用它的结果。 在大多数情况下,为了避免在导入models.py时执行查询,必须传递可调用对象:

    from django.conf import settings
    from django.contrib.auth import get_user_model
    from django.db import models
    
    def get_sentinel_user():
        return get_user_model().objects.get_or_create(username='deleted')[0]
    
    class MyModel(models.Model):
        user = models.ForeignKey(
            settings.AUTH_USER_MODEL,
            on_delete=models.SET(get_sentinel_user),
        )
    
  • DO_NOTHING[source]

    不采取行动。 If your database backend enforces referential integrity, this will cause an IntegrityError unless you manually add an SQL ON DELETE constraint to the database field.

ForeignKey的。 limit_choices_to T0> ¶ T1>

当使用ModelForm或admin(默认情况下,查询集中的所有对象可供选择)呈现此字段时,为此字段的可用选项设置限制。 Either a dictionary, a Q object, or a callable returning a dictionary or Q object can be used.

例如:

staff_member = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    limit_choices_to={'is_staff': True},
)

导致ModelForm上的相应字段仅列出Users,其is_staff=True 这可能对Django管理员有帮助。

可调用表单可以是有用的,例如,当与Python datetime模块结合使用时,可以限制按日期范围进行的选择。 例如:

def limit_pub_date_choices():
    return {'pub_date__lte': datetime.date.utcnow()}

limit_choices_to = limit_pub_date_choices

如果limit_choices_to是或返回Q object,这对于complex queries ,那么当模型的ModelAdminraw_id_fields中未列出字段时,它只会影响管理员的选择。

注意

如果limit_choices_to使用了一个可调用对象,那么每次新的表单被实例化时都会调用它。 也可以在模型验证时调用,例如通过管理命令或管理员。 admin构造查询集以多次验证其在各种边界情况下的表单输入,所以有可能你的可调用可能被调用多次。

ForeignKey的。 related_name T0> ¶ T1>

从相关对象返回到这个关系的名称。 这也是related_query_name(用于来自目标模型的反向过滤器名称的名称)的默认值。 有关完整的解释和示例,请参阅related objects documentation 请注意,在定义abstract models上的关系时,必须设置此值;当你这样做some special syntax是可用的。

如果你想让Django不要创建一个向后的关系,把related_name设置为'+',或者用'+'结束。 例如,这将确保User模型不会与此模型有倒退关系:

user = models.ForeignKey(
    User,
    on_delete=models.CASCADE,
    related_name='+',
)
ForeignKey的。 related_query_name T0> ¶ T1>

用于来自目标模型的反向过滤器名称的名称。 如果设置,它默认为related_namedefault_related_name的值,否则默认为模型的名称:

# Declare the ForeignKey with related_query_name
class Tag(models.Model):
    article = models.ForeignKey(
        Article,
        on_delete=models.CASCADE,
        related_name="tags",
        related_query_name="tag",
    )
    name = models.CharField(max_length=255)

# That's now the name of the reverse filter
Article.objects.filter(tag__name="important")

Like related_name, related_query_name supports app label and class interpolation via some special syntax.

ForeignKey的。 to_field T0> ¶ T1>

与关系相关的对象上的字段。 默认情况下,Django使用相关对象的主键。 如果您引用不同的字段,则该字段必须具有unique=True

ForeignKey的。 db_constraint T0> ¶ T1>

控制是否应在数据库中为该外键创建约束。 默认是True,这几乎可以肯定你想要的;将其设置为False对数据完整性可能非常不利。 这就是说,这里有一些你可能想要这样做的场景:

  • 您的遗留数据无效。
  • 你正在分解你的数据库。

如果设置为False,则访问不存在的相关对象将引发DoesNotExist异常。

ForeignKey的。交换 T0> ¶ T1>

如果这个ForeignKey指向可交换模型,则控制迁移框架的反应。 如果它是True - 默认值 - 那么如果ForeignKey指向一个匹配settings.AUTH_USER_MODEL可交换的模型设置),关系将被存储在使用对设置的引用的迁移中,而不是直接存储到模型中。

如果您确定模型应始终指向交换模型,例如,如果它是专门为您的自定义用户模型设计的配置文件模型,则只需将其覆盖为False

将它设置为False并不意味着即使被换出,也可以引用可交换模型 - False意味着使用此ForeignKey进行的迁移将始终引用准确模型您指定(如果用户尝试使用您不支持的用户模型运行它将会失败)。

如果有疑问,请将其保留为True的默认值。

ManyToManyField

ManyToManyFieldto** options[source]

多对多的关系。 需要一个位置参数:与模型相关的类,其工作原理与ForeignKey完全相同,包括recursivelazy关系。

相关对象可以被添加,删除,或创建字段的RelatedManager

数据库表示

在幕后,Django创建了一个中间连接表来表示多对多的关系。 默认情况下,该表名是使用多对多字段的名称和包含它的模型的表名生成的。 由于某些数据库不支持超过一定长度的表名,因此这些表名将自动截断为64个字符,并使用唯一性散列。 这意味着你可能会看到像author_books_9cdf4这样的表名。这是完全正常的。 您可以使用db_table选项手动提供连接表的名称。

参数¶ T0>

ManyToManyField accepts an extra set of arguments – all optional – that control how the relationship functions.

ManyToManyField。 related_name T0> ¶ T1>

ForeignKey.related_name相同。

ManyToManyField。 related_query_name T0> ¶ T1>

ForeignKey.related_query_name相同。

ManyToManyField。 limit_choices_to T0> ¶ T1>

ForeignKey.limit_choices_to相同。

limit_choices_to has no effect when used on a ManyToManyField with a custom intermediate table specified using the through parameter.

ManyToManyField。对称 T0> ¶ T1>

仅用于自定义ManyToManyFields。 考虑以下模型:

from django.db import models

class Person(models.Model):
    friends = models.ManyToManyField("self")

When Django processes this model, it identifies that it has a ManyToManyField on itself, and as a result, it doesn’t add a person_set attribute to the Person class. 相反,我们假设ManyToManyField是对称的 - 也就是说,如果我是你的朋友,那么你就是我的朋友。

如果您不想在与self的多对多关系中使用对称性,请将symmetrical设置为False This will force Django to add the descriptor for the reverse relationship, allowing ManyToManyField relationships to be non-symmetrical.

ManyToManyField。到 T0> ¶ T1>

Django将自动生成一个表来管理多对多的关系。 但是,如果要手动指定中间表,则可以使用through选项来指定表示要使用的中间表的Django模型。

The most common use for this option is when you want to associate extra data with a many-to-many relationship.

如果不指定明确的through模型,仍然有一个隐含的through模型类,您可以使用它来直接访问创建的表来保存关联。 它有三个领域来链接模型。

如果源模型和目标模型不同,则会生成以下字段:

  • id:关系的主键。
  • <containing_model>_id:声明ManyToManyField的模型的id
  • <other_model>_idManyToManyField指向的模型的id

如果ManyToManyField指向同一个模型,则会生成以下字段:

  • id:关系的主键。
  • from_<model>_id: the id of the instance which points at the model (i.e. the source instance).
  • to_<model>_id:关系指向的实例(即,目标模型实例)的id

这个类可以用来查询给定模型实例的关联记录,就像普通模型一样。

ManyToManyField。 through_fields T0> ¶ T1>

仅在指定自定义中介模型时使用。 Django通常会决定使用哪个中介模型的字段,以便自动建立多对多的关系。 但是,请考虑以下型号:

from django.db import models

class Person(models.Model):
    name = models.CharField(max_length=50)

class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(
        Person,
        through='Membership',
        through_fields=('group', 'person'),
    )

class Membership(models.Model):
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    inviter = models.ForeignKey(
        Person,
        on_delete=models.CASCADE,
        related_name="membership_invites",
    )
    invite_reason = models.CharField(max_length=64)

Membership has two foreign keys to Person (person and inviter), which makes the relationship ambiguous and Django can’t know which one to use. 在这种情况下,必须使用through_fields显式指定Django应该使用哪个外键,如上例所示。

through_fields accepts a 2-tuple ('field1', 'field2'), where field1 is the name of the foreign key to the model the ManyToManyField is defined on (group in this case), and field2 the name of the foreign key to the target model (person in this case).

当一个中介模型上有多个外键给参与多对多关系的模型(或者甚至是两个模型)时,必须指定through_fields 这也适用于recursive relationships当使用中间模型时,并且模型中有两个以上的外键,或者您想明确指定哪个Django应该使用哪个。

使用中间模型的递归关系总是被定义为非对称的 - 也就是说,symmetrical=False - 因此,存在“源”和“目标”的概念。 In that case 'field1' will be treated as the “source” of the relationship and 'field2' as the “target”.

ManyToManyField。 db_table T0> ¶ T1>

用于存储多对多数据的表的名称。 如果没有提供,Django将根据以下名称采用默认名称:定义关系的模型的表格和字段本身的名称。

ManyToManyField。 db_constraint T0> ¶ T1>

控制是否应在数据库中为中间表中的外键创建约束。 默认是True,这几乎可以肯定你想要的;将其设置为False对数据完整性可能非常不利。 这就是说,这里有一些你可能想要这样做的场景:

  • 您的遗留数据无效。
  • 你正在分解你的数据库。

db_constraintthrough是错误的。

ManyToManyField。交换 T0> ¶ T1>

如果这个ManyToManyField指向可交换模型,则控制迁移框架的反应。 如果它是True - 默认值 - 那么如果ManyToManyField指向一个匹配settings.AUTH_USER_MODEL可交换的模型设置),关系将被存储在使用对设置的引用的迁移中,而不是直接存储到模型中。

如果您确定模型应始终指向交换模型,例如,如果它是专门为您的自定义用户模型设计的配置文件模型,则只需将其覆盖为False

如果有疑问,请将其保留为True的默认值。

ManyToManyField does not support validators.

null没有效果,因为在数据库级别上没有办法需要关系。

OneToOneField

OneToOneField(to, on_delete, parent_link=False, **options)[source]

一对一的关系。 从概念上讲,这与ForeignKey类似于unique=True,但是关系的“反向”侧将直接返回单个对象。

This is most useful as the primary key of a model which “extends” another model in some way; Multi-table inheritance is implemented by adding an implicit one-to-one relation from the child model to the parent model, for example.

需要一个位置参数:与模型相关的类。 这与ForeignKey完全相同,包括关于recursivelazy关系的所有选项。

如果您不为OneToOneField指定related_name参数,则Django将使用当前模型的小写名称作为默认值。

用下面的例子:

from django.conf import settings
from django.db import models

class MySpecialUser(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )
    supervisor = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='supervisor_of',
    )

您的结果User模型将具有以下属性:

>>> user = User.objects.get(pk=1)
>>> hasattr(user, 'myspecialuser')
True
>>> hasattr(user, 'supervisor_of')
True

如果相关表中的条目不存在,则在访问反向关系时引发DoesNotExist异常。 例如,如果用户没有由MySpecialUser指定的主管:

>>> user.supervisor_of
Traceback (most recent call last):
    ...
DoesNotExist: User matching query does not exist.

Additionally, OneToOneField accepts all of the extra arguments accepted by ForeignKey, plus one extra argument:

True用于从另一个concrete model继承的模型中时,表示该字段应该用作返回到父类的链接,而不是额外的OneToOneField通常通过子类隐式创建。

有关OneToOneField的使用示例,请参阅One-to-one relationships

字段API参考

Field[source]

Field is an abstract class that represents a database table column. Django使用字段创建数据库表(db_type()),将Python类型映射到数据库(get_prep_value()),反之亦然(from_db_value()

因此,一个字段在不同的Django API中是最基本的部分,特别是modelsquerysets

在模型中,一个字段被实例化为一个类属性,并表示一个特定的表列,参见Models 它具有nullunique等属性,以及Django用于将字段值映射到特定于数据库的值的方法。

A Field is a subclass of RegisterLookupMixin and thus both Transform and Lookup can be registered on it to be used in QuerySets (e.g. field_name__exact="foo"). 所有built-in lookups都是默认注册的。

所有Django的内置字段(如CharField)都是Field的特定实现。 如果你需要一个自定义字段,你可以将任何内置字段子类化或从头开始写一个Field 无论哪种情况,请参阅Writing custom model fields

描述 T0> ¶ T1>

对该字段的详细描述,例如用于django.contrib.admindocs应用程序。

描述可以是这样的形式:

description = _("String (up to %(max_length)s)")

参数是从字段的__dict__内插的。

为了将Field映​​射到数据库特定的类型,Django公开了几种方法:

get_internal_type()[source]

返回一个命名此字段的字符串,用于后端特定目的。 默认情况下,它返回类名称。

请参阅Emulating built-in field types以在自定义字段中使用。

db_type(connection)[source]

返回Field的数据库列数据类型,并考虑到connection

有关自定义字段中的用法,请参阅Custom database types

rel_db_type(connection)[source]

返回指向FieldForeignKeyOneToOneField等字段的数据库列数据类型,同时考虑到connection

有关自定义字段中的用法,请参阅Custom database types

Django需要与数据库后端和字段交互的主要有三种情况:

  • 当它查询数据库时(Python值 - >数据库后端值)
  • 当它从数据库加载数据(数据库后端值 - > Python值)
  • 当它保存到数据库(Python值 - >数据库后端值)

查询时,使用get_db_prep_value()get_prep_value()

get_prep_value(value)[source]

value是模型属性的当前值,并且方法应该以查询中准备用作参数的格式返回数据。

有关用法,请参见Converting Python objects to query values

get_db_prep_valuevalueconnectionprepared = False[source] ¶ T6>

value转换为后端特定的值。 如果prepared=Trueget_prep_value() if False,则默认返回value

有关使用情况,请参阅Converting query values to database values

加载数据时,使用from_db_value()

from_db_valuevalue表达式连接

将数据库返回的值转换为Python对象。 它与get_prep_value()相反。

此方法不适用于大多数内置字段,因为数据库后端已经返回了正确的Python类型,或者后端本身进行了转换。

请参阅Converting values to Python objects以供使用。

注意

出于性能方面的原因,from_db_value没有作为不需要的字段(所有的Django字段)实现。 因此,您可能不会在您的定义中调用super

When saving, pre_save() and get_db_prep_save() are used:

get_db_prep_save连接[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设置)。

请参阅Preprocessing values before saving以供使用。

字段通常从序列化或表单中获取其值作为不同的类型。

to_python(value)[source]

将该值转换为正确的Python对象。 它的作用与value_to_string()相反,也在clean()中调用。

请参阅Converting values to Python objects以供使用。

除了保存到数据库之外,该字段还需要知道如何序列化其值:

value_to_string(obj)[source]

obj转换为一个字符串。 用于序列化字段的值。

请参阅Converting field data for serialization以供使用。

当使用model forms时,Field需要知道应由哪个表单字段表示:

formfield(form_class=None, choices_form_class=None, **kwargs)[source]

返回ModelForm的该字段的默认django.forms.Field

默认情况下,如果form_classchoices_form_class都是None,则使用CharField 如果该字段有choices,并且choices_form_class未指定,则它使用TypedChoiceField

请参阅Specifying the form field for a model field以供使用。

deconstruct()[source]

返回具有足够信息的4元组来重新创建该字段:

  1. 模型上的字段的名称。
  2. 该字段的导入路径(例如"django.db.models.IntegerField")。 这应该是最便携的版本,所以不太具体可能会更好。
  3. 位置参数列表。
  4. 关键字参数的字典。

必须将此方法添加到1.7之前的字段以使用Migrations来迁移其数据。

字段属性引用

每个Field实例都包含几个允许内省其行为的属性。 当需要编写依赖字段功能的代码时,使用这些属性而不是isinstance来检查。 这些属性可以与Model._meta API一起使用,以缩小对特定字段类型的搜索范围。 自定义模型字段应该实现这些标志。

字段的属性

Field.auto_created

指示字段是否自动创建的布尔标志,例如模型继承使用的OneToOneField

Field.concrete

布尔标志,指示该字段是否有与之关联的数据库列。

Field.hidden

Boolean flag that indicates if a field is used to back another non-hidden field’s functionality (e.g. the content_type and object_id fields that make up a GenericForeignKey). hidden标志用于区分模型上所有字段的模型字段的公共子集。

注意

Options.get_fields() excludes hidden fields by default. 传入include_hidden=True以返回结果中的隐藏字段。

Field.is_relation

布尔型标志,指示某个字段是否包含对其功能的一个或多个其他模型的引用(例如,ForeignKeyManyToManyFieldOneToOneField等) 。

Field.model

返回定义字段的模型。 如果在模型的超类上定义了一个字段,那么model将引用超类,而不是实例的类。

关系的字段的属性

这些属性用于查询关系的基数和其他细节。 这些属性出现在所有的领域;但是,如果字段是关系类型(Field.is_relation=True),则它们将只有布尔值(而不是None)。

Field.many_to_many

如果该字段具有多对多关系,则为True的布尔标志;否则,False Django中包含True的唯一字段是ManyToManyField

Field.many_to_one

Boolean flag that is True if the field has a many-to-one relation, such as a ForeignKey; False otherwise.

Field.one_to_many

Boolean flag that is True if the field has a one-to-many relation, such as a GenericRelation or the reverse of a ForeignKey; False otherwise.

Field.one_to_one

Boolean flag that is True if the field has a one-to-one relation, such as a OneToOneField; False otherwise.

Field.related_model

指向该领域涉及的模型。 例如,在ForeignKey(Author, on_delete = models.CASCADE)中的Author GenericForeignKeyrelated_model总是None