模型字段参考¶

本文档包含 Field 类的所有 API 参考，包括字段选项和字段类型。

参见

若内置字段未满足需求，你可以试试 django-localflavor （文档），它包含了针对各别国家和文件的代码。

注解

从技术上讲，这些方法都被定义在 django.db.models.fields，但为了方便，它们被导入到 django.db.models；标准的惯例是使用 from django.db import models 并利用 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 ）。

注解

当使用 Oracle 数据库后端时，不管这个属性是什么，都会存储 NULL 值来表示空字符串。

`blank`¶

Field.blank¶

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

注意，这与 null 不同。 null 纯属数据库相关，而 blank 则与验证相关。如果一个字段有 blank=True，表单验证将允许输入一个空值。如果一个字段有 blank=False，则该字段为必填字段。

`choices`¶

Field.choices¶

一个 sequence 本身由正好两个项目的迭代项组成（例如 [(A，B)，(A，B)...] ），作为该字段的选择。如果给定了选择，它们会被模型验证强制执行，默认的表单部件将是一个带有这些选择的选择框，而不是标准的文本字段。

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

YEAR_IN_SCHOOL_CHOICES = [
    ('FR', 'Freshman'),
    ('SO', 'Sophomore'),
    ('JR', 'Junior'),
    ('SR', 'Senior'),
    ('GR', 'Graduate'),
]

一般来说，最好在模型类内部定义选择，并为每个值定义一个合适的名称的常量：

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' 选项）。

对于每一个设置了 choice 的模型字段，Django 会添加一个方法来检索字段当前值的可读名称。参见数据库 API 文档中的 get_FOO_display()。

请注意，选择可以是任何序列对象——不一定是列表或元组。这让你可以动态地构造选择。但是如果你发现自己把 chips 魔改成动态的，你可能最好使用一个合适的的带有 ForeignKey 的数据库表。 chips 是用于静态数据的，如果有的话，不应该有太大的变化。

注解

每当 choices 的顺序变动时将会创建新的迁移。

除非 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.choices,
        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) 二元组。请看下面使用更复杂的数据类型子类化选择的例子。如果没有提供元组，或者最后一项不是（惰性）字符串，label 是从成员名自动生成。
在值上添加 .label 属性，以返回人类可读的名称。
在枚举类中添加了一些自定义属性—— .choice、.labs、.values 和 .names ——以便于访问枚举的这些单独部分的列表。在字段定义中，使用 .choice 作为一个合适的值传递给 choice。
强制使用 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.choices)

也可以使用 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)'

还有一些注意事项需要注意：

枚举类型不支持命名组。
因为具有具体数据类型的枚举要求所有值都与类型相匹配，所以不能通过创建一个值为 None 的成员来覆盖空白标签。相反，在类上设置 __empty__ 属性：
```
class Answer(models.IntegerChoices):
    NO = 0, _('No')
    YES = 1, _('Yes')

    __empty__ = _('(Unknown)')
```

`db_column`¶

Field.db_column¶

这个字段要使用的数据库列名。如果没有给出列名，Django 将使用字段名。

如果你的数据库列名是 SQL 的保留字，或者包含了 Python 变量名中不允许的字符——特别是连字符——那也没关系。Django 会在幕后引用列名和表名。

`db_index`¶

Field.db_index¶

如果是 True，将为该字段创建数据库索引。

`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 不能用于 default 等字段选项，因为它们不能被迁移序列化。其他注意事项见该文档。

对于像 ForeignKey 这样映射到模型实例的字段，默认应该是它们引用的字段的值（默认是 pk 除非 to_field 被设置了），而不是模型实例。

当创建新的模型实例且没有为该字段提供值时，使用默认值。当字段是主键时，当字段设置为``None`` 时，也使用默认值。

`editable`¶

Field.editable¶

如果是 False，该字段将不会在管理或任何其他 ModelForm 中显示。在模型验证中也会跳过。默认为 True。

`error_messages`¶

Field.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。一个对象只允许有一个主键。

主键字段是只读的。如果您改变了现有对象的主键值，然后将其保存，则会在旧对象旁边创建一个新对象。

Changed in Django 3.2:

在旧版本中，自动创建的主键字段总是 AutoField。

`unique`¶

Field.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`¶

Field.validators¶

要为该字段运行的验证器列表。更多信息请参见验证器文档。

注册和获取查询¶

Field 实现了查询注册 API。该 API 可用于自定义字段类的哪些查询是可用的，以及如何从字段中获取查询。

字段类型¶

`AutoField`¶

class AutoField(**options)¶

一个 IntegerField，根据可用的 ID 自动递增。你通常不需要直接使用它；如果你没有指定，主键字段会自动添加到你的模型中。参见自动设置主键。

`BigAutoField`¶

class BigAutoField(**options)¶

一个 64 位整数，与 AutoField 很相似，但保证适合 1 到 9223372036854775807 的数字。

`BigIntegerField`¶

class BigIntegerField(**options)¶

一个 64 位的整数，和 IntegerField 很像，只是它保证适合从 -9223372036854775808 到 9223372036854775807 的数字。该字段的默认表单部件是一个 NumberInput。

`BinaryField`¶

class BinaryField(max_length=None, **options)¶

一个用于存储原始二进制数据的字段。可以指定为 bytes、bytearray 或 memoryview。

默认情况下，BinaryField 将 ediditable` 设置为 False，在这种情况下，它不能被包含在 ModelForm 中。

BinaryField 有一个额外的可选参数：

BinaryField.max_length¶: The maximum length (in bytes) of the field. The maximum length is enforced in Django's validation using MaxLengthValidator.

滥用 BinaryField

虽然你可能会想到在数据库中存储文件，但考虑到这在99%的情况下是糟糕的设计。这个字段不能代替正确的静态文件处理。

`BooleanField`¶

class BooleanField(**options)¶

一个 true／false 字段。

该字段的默认表单部件是 CheckboxInput，或者如果 null=True 则是 NullBooleanSelect。

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

`CharField`¶

class CharField(max_length=None, **options)¶

一个字符串字段，适用于小到大的字符串。

对于大量的文本，使用 TextField。

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

CharField 有两个额外的参数：

CharField.max_length¶: 必须的。该字段的最大长度（以字符为单位）。max_length 在数据库层面强制执行，在 Django 的验证中使用 MaxLengthValidator。

注解

如果你编写的应用程序必须可移植到多个数据库后端，你应该意识到，有些后端对 max_length 有限制。详情请参考数据库后端注释。

CharField.db_collation¶: New in Django 3.2.

可选的。该字段的数据库字符序名称。

注解

字符序名称是不标准化的。因此，这将无法在多个数据库后端之间进行移植。

Oracle

Oracle 只有在 MAX_STRING_SIZE 数据库初始化参数被设置为 EXTENDED 时，才支持字符序。

`DateField`¶

class 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 ——来自 datetime.date.today()
对于 DateTimeField: default=timezone.now ——来自 django.utils.timezone.now()

该字段的默认表单部件是一个 DateInput。管理中增加了一个 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`¶

class DateTimeField(auto_now=False, auto_now_add=False, **options)¶

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

该字段的默认表单部件是一个单独的 DateTimeInput。管理中使用两个单独的 TextInput 部件，并使用 JavaScript 快捷方式。

`DecimalField`¶

class DecimalField(max_digits=None, decimal_places=None, **options)¶

一个固定精度的十进制数，在 Python 中用一个 Decimal 实例来表示。它使用 DecimalValidator 验证输入。

有两个 必要的 参数：

DecimalField.max_digits¶: 数字中允许的最大位数。请注意，这个数字必须大于或等于 decimal_places。

DecimalField.decimal_places¶: 与数字一起存储的小数位数。

例如，如果要存储精度为小数点后两位的 999 的数字，你可以使用：

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

并以 10 位小数的精度来存储最多约 10 亿的数字：

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

当 localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。

注解

关于 FloatField 和 DecimalField 类之间差异的更多信息，请参见 FloatField vs. DecimalField。你还应该注意小数字段的 SQLite 限制。

`DurationField`¶

class DurationField(**options)¶

一个用于存储时间段的字段——在 Python 中用 timedelta 建模。当在 PostgreSQL 上使用时，使用的数据类型是 interval，在 Oracle 上使用的数据类型是 INTERVAL DAY(9) TO SECOND(6)。否则使用微秒的 bigint。

注解

DurationField 的算术在大多数情况下是可行的。但在 PostgreSQL 以外的所有数据库中，将 DurationField 的值与 DateTimeField 实例上的算术进行比较，将无法达到预期的效果。

`EmailField`¶

class EmailField(max_length=254, **options)¶

一个 CharField，使用 EmailValidator 来检查该值是否为有效的电子邮件地址。

`FileField`¶

class FileField(upload_to=None, max_length=100, **options)¶

一个文件上传字段

注解

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)

FileField.storage¶: 一个存储对象，或是一个返回存储对象的可调用对象。它处理你的文件的存储和检索。参见管理文件，了解如何提供这个对象。

Changed in Django 3.1:
增加了提供可调用对象的能力。

该字段的默认表单部件是一个 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 类的 store() 方法。

需要注意的是，无论何时处理上传的文件，你都应该密切关注你上传的文件在哪里，是什么类型的文件，以避免安全漏洞。对所有上传的文件进行验证，这样你才能确定文件是你认为的那样。例如，如果你盲目地让别人上传文件，不经过验证，就上传文件到你的 Web 服务器的文档根目录下，那么有人就可以上传一个 CGI 或 PHP 脚本，并通过访问它的 URL 在你的网站上执行该脚本。不要允许这种情况发生。

另外要注意的是，即使是上传的 HTML 文件，由于可以被浏览器执行（虽然不能被服务器执行），也会造成相当于 XSS 或 CSRF 攻击的安全威胁。

FileField 实例在数据库中被创建为 varchar 列，默认最大长度为 100 个字符。与其他字段一样，你可以使用 max_length 参数改变最大长度。

`FileField` 和 `FieldFile`¶

class FieldFile¶

当你访问一个模型上的 FileField 时，你会得到一个 FieldFile 的实例作为访问底层文件的代理。

FieldFile 的 API 与 File 的 API 相同，但有一个关键的区别。该类所封装的对象不一定是 Python 内置文件对象的封装 相反，它是 Storage.open() 方法结果的封装，该方法可能是 File 对象，也可能是自定义存储对 File API 的实现。

除了从 File 继承的 API，如 read() 和 write() 之外，FieldFile 还包括一些可以用来与底层文件交互的方法：

警告

该类的两个方法 save() 和 delete()，默认为将与相关 FieldFile 的模型对象保存在数据库中。

FieldFile.name¶

文件名，包括从关联的 Storage 的根部开始的相对路径 FileField。

FieldFile.path¶

一个只读属性，通过调用底层的 path() 方法，访问文件的本地文件系统路径。

FieldFile.size¶

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

FieldFile.url¶

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

FieldFile.open(mode='rb')¶

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

因为在访问底层文件时，底层文件是隐式打开的，所以除了重置底层文件的指针或改变 mode 之外，可能没有必要调用这个方法。

FieldFile.close()¶

类似于标准的 Python file.close() 方法，关闭与该实例相关的文件。

FieldFile.save(name, content, save=True)¶

这个方法接收一个文件名和文件内容，并将它们传递给字段的存储类，然后将存储的文件与模型字段关联。如果你想手动将文件数据与模型上的 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")

更多信息，请参见管理文件。

FieldFile.delete(save=True)¶

删除与此实例相关的文件，并清除字段的所有属性。注意：如果在调用 delete() 时，文件恰好被打开，本方法将关闭该文件。

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

请注意，当一个模型被删除时，相关文件不会被删除。如果你需要清理遗留文件，你需要自己处理（例如，使用自定义管理命令，可以手动运行或通过例如 cron 定期运行）。

`FilePathField`¶

class FilePathField(path='', match=None, recursive=False, allow_files=True, allow_folders=False, max_length=100, **options)¶

一个 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.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 FloatField(**options)¶

在 Python 中用一个 float 实例表示的浮点数。

当 localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。

FloatField vs. DecimalField

FloatField 类有时会与 DecimalField 类混淆。虽然它们都表示实数，但它们表示的方式不同。FloatField 内部使用 Python 的 float 类型，而 DecimalField 则使用 Python 的 Decimal 类型。关于两者之间的区别，请参见 Python 的 decimal 模块的文档。

`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 实例在数据库中创建为 varchar 列，默认最大长度为 100 个字符。与其他字段一样，你可以使用 max_length 参数改变最大长度。

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

`IntegerField`¶

class IntegerField(**options)¶

一个整数。从 -2147483648 到 2147483647 的值在 Django 支持的所有数据库中都是安全的。

它使用 MinValueValidator 和 MaxValueValidator 根据默认数据库支持的值来验证输入。

当 localize 为 False 时是 NumberInput 否则，该字段的默认表单部件是 TextInput。

`GenericIPAddressField`¶

class GenericIPAddressField(protocol='both', unpack_ipv4=False, **options)¶

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。

`JSONField`¶

class JSONField(encoder=None, decoder=None, **options)¶

New in Django 3.1.

一个用于存储 JSON 编码数据的字段。在 Python 中，数据以其 Python 本地格式表示：字典、列表、字符串、数字、布尔值和 None。

JSONField 在 MariaDB 10.2.7+、MySQL 5.7.8+、Oracle、PostgreSQL 和 SQLite（在 JSON1 扩展被启用的情况下）都支持。

JSONField.encoder¶

一个可选的 json.JSONEncoder 子类，用于序列化标准 JSON 序列化器不支持的数据类型（例如 datetime.datetime 或 UUID ）。例如，你可以使用 DjangoJSONEncoder 类。

默认为 json.JSONEncoder。

JSONField.decoder¶

一个可选的 json.JSONDecoder 子类，用于反序列化从数据库中获取的值。该值将采用自定义编码器选择的格式（通常是字符串）。你的反序列化可能需要考虑到你无法确定输入类型的事实。例如，你有可能返回一个 datetime，实际上是一个字符串，而这个字符串恰好与 datetime 选择的格式相同。

默认为 json.JSONDecoder。

如果你给字段一个 default，确保它是一个不可变的对象，比如 str，或者是一个每次返回一个新的可变对象的可调用对象，比如 dict 或一个函数。提供一个像 default={} 或 default=[] 这样的可改变的默认对象，在所有模型实例之间共享一个对象。

要在数据库中查询 JSONField，请看查询 JSONField。

索引

Index 和 Field.db_index 都创建了一个 B 树索引，在查询 JSONField 的时候并不是特别有用。仅在 PostgreSQL 上，可以使用 GinIndex 比较适合。

PostgreSQL 用户

PostgreSQL 有两种基于 JSON 的原生数据类型： json 和 jsonb。json 和 jsonb。它们之间的主要区别在于它们的存储方式和查询方式。PostgreSQL 的 json 字段是作为 JSON 的原始字符串表示来存储的，当根据键来查询时，必须同时进行解码。jsonb 字段是基于 JSON 的实际结构存储的，它允许索引。这样做的代价是在写入 jsonb 字段时增加了一点成本。JSONField 使用 jsonb。

Oracle 用户

Oracle 数据库不支持存储 JSON 标量值。只支持 JSON 对象和数组（在 Python 中使用 dict 和 list 表示)。

`NullBooleanField`¶

class NullBooleanField(**options)¶

就像 BooleanField 的 null=True。

3.1 版后已移除: NullBooleanField 已被废弃，改为 BooleanField(null=True)。

`PositiveBigIntegerField`¶

class PositiveBigIntegerField(**options)¶

New in Django 3.1.

就像一个 PositiveIntegerField，但只允许在某一特定点下的值（依赖于数据库）。0 到 9223372036854775807 的值在 Django 支持的所有数据库中都是安全的。

`PositiveIntegerField`¶

class PositiveIntegerField(**options)¶

就像 IntegerField 一样，但必须是正值或零（ 0 ）。从 0 到 2147483647 的值在 Django 支持的所有数据库中都是安全的。出于向后兼容的原因，接受 0 的值。

`PositiveSmallIntegerField`¶

class PositiveSmallIntegerField(**options)¶

就像一个 PositiveIntegerField，但只允许在某一特定（数据库依赖的）点下取值。0 到 32767 的值在 Django 支持的所有数据库中都是安全的。

`SlugField`¶

class SlugField(max_length=50, **options)¶

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`¶

class SmallAutoField(**options)¶

就像一个 AutoField，但只允许值在一定（依赖于数据库）的限制下。1 到 32767 的值在 Django 支持的所有数据库中都是安全的。

`SmallIntegerField`¶

class SmallIntegerField(**options)¶

就像一个 IntegerField，但只允许在某一特定（依赖于数据库的）点下取值。从 -32768 到 32767 的值在 Django 支持的所有数据库中都是安全的。

`TextField`¶

class TextField(**options)¶

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

如果你指定了 max_length 属性，它将反映在自动生成的表单字段的 Textarea 部件中。但是，它并没有在模型或数据库层面被强制执行。使用一个 CharField 来实现。

TextField.db_collation¶: New in Django 3.2.

该字段的数据库字符序名称。

注解

字符序名称是不标准化的。因此，这将无法在多个数据库后端之间进行移植。

Oracle

Oracle 不支持 TextField 的字符序。

`TimeField`¶

class TimeField(auto_now=False, auto_now_add=False, **options)¶

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

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

`URLField`¶

class URLField(max_length=200, **options)¶

URL 的 CharField，由 URLValidator 验证。

该字段的默认表单部件是一个 URLInput。

像所有的 CharField 子类一样， URLField 接受可选的 max_length 参数。如果你没有指定 max_length 参数，则使用默认的 200。

`UUIDField`¶

class UUIDField(**options)¶

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

在 PostgreSQL 上查找

在 PostgreSQL 上使用 iexact、contains、icontains、startswith、istartswith、endswith 或 iendswith 在 PostgreSQL 上查找没有连字符的值是行不通的，因为 PostgreSQL 将它们存储在一个连字符的 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。无论哪种情况，请参见编写自定义模型字段(model fields)。

description¶

字段的详细描述，例如： django.contrib.admindocs 应用程序。

描述的形式可以是：

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

其中的参数是从字段的 __dict__ 中插入的。

descriptor_class¶: 一个实现描述符协议的类，它被实例化并分配给模型实例属性。构造函数必须接受一个参数，即 Field 实例。覆盖该类属性可以自定义获取和设置行为。

为了将一个 Field 映射到数据库的特定类型，Django 提供了一些方法：

get_internal_type()¶

返回一个字符串，用于命名这个字段，以满足后台的特定目的。默认情况下，它返回的是类名。

参见仿造内置字段类型在自定义字段中的用法。

db_type(connection)¶

返回 Field 的数据库列数据类型，并考虑 connection。

参见自定义数据库类型在自定义字段中的用法。

rel_db_type(connection)¶

返回指向 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，则返回 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 对象。

注解

由于性能原因，from_db_value 并没有在不需要它的字段上实现 no-op（所有 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() 之前调用的方法，在保存前准备好值（例如 DateField.auto_now ）。

model_instance 是该字段所属的实例，add 是该实例是否第一次被保存到数据库中。

它应该从 model_instance 中返回这个字段的适当属性的值。属性名在 self.attname 中（这是由 Field 设置的）。

使用方法参见在保存前预处理数值。

字段经常以不同的类型接收它们的值，要么来自序列化，要么来自表单。

to_python(value)¶

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

使用方法参见将值转为 Python 对象。

除了保存到数据库，字段还需要知道如何将其值序列化。

value_from_object(obj)¶

返回给定模型实例的字段值。

这个方法经常被 value_to_string() 使用。

value_to_string(obj)¶

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

使用方法参见为序列化转换字段数据。

当使用 model forms 时，Field 需要知道它应该由哪个表单字段来表示。

formfield(form_class=None, choices_form_class=None, **kwargs)¶

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

默认情况下，如果 form_class 和 choices_form_class 都是 None，则使用 CharField。如果字段有 chips，且 choices_form_class 没有指定，则使用 TypedChoiceField。

使用方法参见为模型字段指定表单字段。

deconstruct()¶

返回一个包含足够信息的四元元组来重新创建字段。

模型上的字段名称。
字段的导入路径（例如 "django.db.models.IntegerField" ）。这应该是最可移植版本，所以不那么具体可能更好。
一个位置参数的列表。
一个关键字参数的字典。

这个方法必须添加到 1.7 之前的字段中，才能使用迁移迁移其数据。

Django 3.2.11.dev 文档

模型字段参考¶

字段选项¶

null¶

blank¶

choices¶

枚举类型¶

db_column¶

db_index¶

db_tablespace¶

default¶

editable¶

error_messages¶

help_text¶

primary_key¶

unique¶

unique_for_date¶

unique_for_month¶

unique_for_year¶

verbose_name¶

validators¶

注册和获取查询¶

字段类型¶

AutoField¶

BigAutoField¶

BigIntegerField¶

BinaryField¶

BooleanField¶

CharField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FileField 和 FieldFile¶

FilePathField¶

FloatField¶

ImageField¶

IntegerField¶

GenericIPAddressField¶

JSONField¶

NullBooleanField¶

PositiveBigIntegerField¶

PositiveIntegerField¶

PositiveSmallIntegerField¶

SlugField¶

SmallAutoField¶

SmallIntegerField¶

TextField¶

TimeField¶

URLField¶

UUIDField¶

关系字段¶

ForeignKey¶

数据库表现¶

参数¶

ManyToManyField¶

数据库表现¶

参数¶

OneToOneField¶

字段 API 参考¶

字段属性参考¶

字段的属性¶

有关系的字段的属性¶

Last update:

`null`¶

`blank`¶

`choices`¶

`db_column`¶

`db_index`¶

`db_tablespace`¶

`default`¶

`editable`¶

`error_messages`¶

`help_text`¶

`primary_key`¶

`unique`¶

`unique_for_date`¶

`unique_for_month`¶

`unique_for_year`¶

`verbose_name`¶

`validators`¶

`AutoField`¶

`BigAutoField`¶

`BigIntegerField`¶

`BinaryField`¶

`BooleanField`¶

`CharField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FileField` 和 `FieldFile`¶

`FilePathField`¶

`FloatField`¶

`ImageField`¶

`IntegerField`¶

`GenericIPAddressField`¶

`JSONField`¶

`NullBooleanField`¶

`PositiveBigIntegerField`¶

`PositiveIntegerField`¶

`PositiveSmallIntegerField`¶

`SlugField`¶

`SmallAutoField`¶

`SmallIntegerField`¶

`TextField`¶

`TimeField`¶

`URLField`¶

`UUIDField`¶

`ForeignKey`¶

`ManyToManyField`¶

`OneToOneField`¶