null¶

Field.null¶

如果为 True，Django 将在数据库中将空值存储为 NULL。默认值为 False。

避免在基于字符串的字段（如 CharField 和 TextField）上使用 null。如果基于字符串的字段具有 null=True，则意味着它具有两个可能的“无数据”值：NULL 和空字符串。在大多数情况下，拥有两个可能的“无数据”值是多余的；Django 约定是使用空字符串，而不是 NULL。一个例外是当 CharField 同时设置了 unique=True 和 blank=True 时。在这种情况下，需要 null=True 来避免在保存具有空值的多个对象时出现唯一约束冲突。

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

blank¶

Field.blank¶

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

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

choices¶

Field.choices¶

一个映射或可迭代对象，格式如下所示，用作此字段的选择。如果提供了选择，它们将通过 模型验证 强制执行，并且默认表单小部件将是一个选择框，其中包含这些选择，而不是标准文本字段。

如果提供了映射，则键元素是将要设置在模型上的实际值，第二个元素是人类可读的名称。例如

YEAR_IN_SCHOOL_CHOICES = {
    "FR": "Freshman",
    "SO": "Sophomore",
    "JR": "Junior",
    "SR": "Senior",
    "GR": "Graduate",
}

您还可以传递一个 sequence，它本身包含恰好两个项目的可迭代对象（例如 [(A1, B1), (A2, B2), …]）。元组中的第一个元素是将要设置在模型上的实际值，第二个元素是人类可读的名称。例如

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

choices 也可以定义为一个可调用对象，它不接受任何参数并返回上面描述的任何格式。例如

def get_currencies():
    return {i: i for i in settings.CURRENCIES}


class Expense(models.Model):
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    currency = models.CharField(max_length=3, choices=get_currencies)

为 choices 传递一个可调用对象在以下情况下特别有用，例如，选择是

• I/O 绑定操作（可能被缓存）的结果，例如查询同一数据库或外部数据库中的表，或从静态文件访问选择。
• 一个列表，该列表基本上是稳定的，但可能会随着时间或项目而有所不同。此类别的示例包括使用提供知名值库存的第三方应用程序，例如货币、国家/地区、语言、时区等。

通常，最好在模型类中定义选择，并为每个值定义一个命名合适的常量

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

您还可以使用序列，例如 2 元组列表

MEDIA_CHOICES = [
    (
        "Audio",
        (
            ("vinyl", "Vinyl"),
            ("cd", "CD"),
        ),
    ),
    (
        "Video",
        (
            ("vhs", "VHS Tape"),
            ("dvd", "DVD"),
        ),
    ),
    ("unknown", "Unknown"),
]

请注意，选择可以是任何序列对象 - 不一定是列表或元组。这使您可以动态构建选择。但是，如果您发现自己正在修改 choices 以使其动态，那么您可能最好使用具有 ForeignKey 的适当数据库表。 choices 旨在用于静态数据，这些数据很少或根本不会更改。

对于每个具有 choices 设置的模型字段，Django 将将选择规范化为 2 元组列表，并添加一个方法来检索字段当前值的人类可读名称。请参阅数据库 API 文档中的 get_FOO_display()。

除非在字段上设置了 blank=False 以及 default，否则将使用包含 "---------" 的标签渲染选择框。要覆盖此行为，请将包含 None 的元组添加到 choices 中；例如 (None, 'Your String For Display')。或者，您可以在有意义的情况下使用空字符串而不是 None - 例如在 CharField 上。

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,
        default=YearInSchool.FRESHMAN,
    )

    def is_upperclass(self):
        return self.year_in_school in {
            self.YearInSchool.JUNIOR,
            self.YearInSchool.SENIOR,
        }

>>> class Vehicle(models.TextChoices):
...     CAR = "C"
...     TRUCK = "T"
...     JET_SKI = "J"
...
>>> Vehicle.JET_SKI.label
'Jet Ski'

class Card(models.Model):
    class Suit(models.IntegerChoices):
        DIAMOND = 1
        SPADE = 2
        HEART = 3
        CLUB = 4

    suit = models.IntegerField(choices=Suit)

>>> 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')]

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

db_column¶

Field.db_column¶

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

如果您的数据库列名称是 SQL 保留字，或者包含 Python 变量名称中不允许的字符 - 尤其是连字符 - 那么没关系。Django 在幕后引用列名和表名。

db_comment¶

Field.db_comment¶

用于此字段的数据库列上的注释。它对于为可能没有查看您的 Django 代码的直接数据库访问人员记录字段很有用。例如

pub_date = models.DateTimeField(
    db_comment="Date and time when the article was published",
)

db_default¶

Field.db_default¶

此字段的数据库计算默认值。这可以是文字值或数据库函数，例如 Now

created = models.DateTimeField(db_default=Now())

可以使用更复杂的表达式，只要它们由文字和数据库函数组成。

month_due = models.DateField(
    db_default=TruncMonth(
        Now() + timedelta(days=90),
        output_field=models.DateField(),
    )
)

数据库默认值不能引用其他字段或模型。例如，这是无效的

end = models.IntegerField(db_default=F("start") + 50)

如果同时设置了 db_default 和 Field.default，则在 Python 代码中创建实例时，default 将优先。 db_default 仍将在数据库级别设置，并在 ORM 之外插入行或在迁移中添加新字段时使用。

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": "[email protected]"}


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

lambda 不能用于像 default 这样的字段选项，因为它们不能被 迁移序列化。有关其他注意事项，请参阅该文档。

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

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

默认值也可以使用 Field.db_default 在数据库级别设置。

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

主键字段是只读的。如果您更改现有对象的主键值，然后保存它，则会创建一个新对象，与旧对象并排。

在 删除 对象时，主键字段将设置为 None。

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_for_date 和 unique_for_month 相似。

verbose_name¶

Field.verbose_name¶

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

validators¶

Field.validators¶

要为此字段运行的验证器列表。有关更多信息，请参阅 验证器文档。

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 将 editable 设置为 False，在这种情况下，它不能包含在 ModelForm 中。

BinaryField.max_length¶

可选。字段的最大长度（以字节为单位）。最大长度在 Django 的验证中使用 MaxLengthValidator 强制执行。

BooleanField¶

class BooleanField(**options)¶

一个真/假字段。

此字段的默认表单小部件是 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 强制执行。它对于 Django 包含的所有数据库后端都是必需的，除了 PostgreSQL，它支持无限的 VARCHAR 列。

注意

如果您正在编写必须移植到多个数据库后端的应用程序，您应该注意，某些后端对 max_length 存在限制。有关详细信息，请参阅 数据库后端说明。

Django 4.2 中的更改

在 PostgreSQL 上添加了对无限 VARCHAR 列的支持。

CharField.db_collation¶

可选。字段的数据库排序规则名称。

注意

排序规则名称没有标准化。因此，这在多个数据库后端之间不可移植。

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 是互斥的。任何这些选项的组合都会导致错误。

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.99 且精度为 2 位小数的数字，可以使用

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

要存储最大为大约十亿且精度为 10 位小数的数字

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

此字段的默认表单小部件是 NumberInput（当 localize 为 False 时）或 TextInput（否则）。

DurationField¶

class DurationField(**options)¶

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

EmailField¶

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

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

FileField¶

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

文件上传字段。

具有以下可选参数

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¶

一个存储对象，或一个返回存储对象的 callable。这处理文件的存储和检索。有关如何提供此对象的详细信息，请参阅 管理文件。

此字段的默认表单小部件是 ClearableFileInput。

在模型中使用 FileField 或 ImageField（见下文）需要几个步骤

1. 在您的 settings 文件中，您需要定义 MEDIA_ROOT 作为 Django 要存储上传文件的目录的完整路径。（出于性能考虑，这些文件不会存储在数据库中。）定义 MEDIA_URL 作为该目录的公共基本 URL。确保此目录可由 Web 服务器的用户帐户写入。
2. 将 FileField 或 ImageField 添加到您的模型，定义 upload_to 选项以指定 MEDIA_ROOT 的子目录，用于存储上传的文件。
3. 数据库中只会存储文件的路径（相对于 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 类参考和 Managing files 主题指南。

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

请注意，无论何时处理上传的文件，都应密切注意上传文件的位置以及文件类型，以避免安全漏洞。验证所有上传的文件，以确保文件是你认为的文件。例如，如果你盲目地让某人上传文件，而没有验证，到 web 服务器文档根目录中的目录，那么某人可以上传 CGI 或 PHP 脚本，并通过访问你网站上的 URL 来执行该脚本。不要允许这样做。

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

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

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)

from django.core.files.base import ContentFile

myfile = ContentFile("hello world")

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 实例表示。

此字段的默认表单小部件是 NumberInput（当 localize 为 False 时）或 TextInput（否则）。

GeneratedField¶

class GeneratedField(expression, output_field, db_persist=None, **kwargs)¶

一个始终根据模型中的其他字段计算的字段。此字段由数据库本身管理和更新。使用 GENERATED ALWAYS SQL 语法。

有两种类型的生成列：存储的和虚拟的。存储的生成列在写入（插入或更新）时计算，并占用存储空间，就像它是常规列一样。虚拟生成列不占用任何存储空间，并在读取时计算。因此，虚拟生成列类似于视图，而存储的生成列类似于物化视图。

GeneratedField.expression¶

一个 Expression，数据库使用它在每次更改模型时自动设置字段值。

表达式应是确定性的，并且仅引用模型内的字段（在同一个数据库表中）。生成字段不能引用其他生成字段。数据库后端可能会施加更多限制。

GeneratedField.output_field¶

一个模型字段实例，用于定义字段的数据类型。

GeneratedField.db_persist¶

确定数据库列是否应占用存储空间，就像它是真实列一样。如果为 False，则该列充当虚拟列，不占用数据库存储空间。

PostgreSQL 仅支持持久化列。Oracle 仅支持虚拟列。

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 格式，例如 ::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' 时使用。

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

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 根据默认数据库支持的值来验证输入。

此字段的默认表单小部件是 NumberInput（当 localize 为 False 时）或 TextInput（否则）。

JSONField¶

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

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

JSONField 在 MariaDB、MySQL、Oracle、PostgreSQL 和 SQLite（启用 JSON1 扩展）上受支持。

JSONField.encoder¶

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

默认为 json.JSONEncoder。

JSONField.decoder¶

一个可选的 json.JSONDecoder 子类，用于反序列化从数据库检索的值。该值将采用自定义编码器选择的格式（通常是字符串）。您的反序列化可能需要考虑您无法确定输入类型的事实。例如，您有风险返回一个 datetime，它实际上是一个字符串，碰巧与为 datetime 选择的相同格式。

默认为 json.JSONDecoder。

要查询数据库中的 JSONField，请参阅 查询 JSONField。

PositiveBigIntegerField¶

class PositiveBigIntegerField(**options)¶

类似于 PositiveIntegerField，但只允许小于某个（依赖于数据库）的值。在 Django 支持的所有数据库中，从 0 到 9223372036854775807 的值都是安全的。

PositiveIntegerField¶

class PositiveIntegerField(**options)¶

类似于 IntegerField，但必须为正数或零 (0)。在 Django 支持的所有数据库中，从 0 到 2147483647 的值都是安全的。出于向后兼容性的原因，接受值 0。

PositiveSmallIntegerField¶

class PositiveSmallIntegerField(**options)¶

类似于 PositiveIntegerField，但只允许小于某个（依赖于数据库）的值。在 Django 支持的所有数据库中，从 0 到 32767 的值都是安全的。

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，但只允许小于某个（依赖于数据库）的值。在 Django 支持的所有数据库中，从 1 到 32767 的值都是安全的。

SmallIntegerField¶

class SmallIntegerField(**options)¶

类似于 IntegerField，但只允许小于某个（依赖于数据库）的值。在 Django 支持的所有数据库中，从 -32768 到 32767 的值都是安全的。

TextField¶

class TextField(**options)¶

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

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

TextField.db_collation¶

可选。字段的数据库排序规则名称。

注意

排序规则名称没有标准化。因此，这在多个数据库后端之间不可移植。

Oracle

Oracle 不支持 TextField 的排序规则。

TimeField¶

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

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

此字段的默认表单小部件是 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 和 MariaDB 10.7+ 上使用时，它存储在 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

请注意，可调用对象（省略括号）传递给 default，而不是 UUID 的实例。

ForeignKey¶

class ForeignKey(to, on_delete, **options)¶

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

要创建递归关系（一个对象与自身具有多对一关系），请使用 models.ForeignKey('self', on_delete=models.CASCADE)。

如果您需要在尚未定义的模型上创建关系，可以使用模型的名称，而不是模型对象本身

from django.db import models


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


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

在 抽象模型 上以这种方式定义的关系在模型被子类化成具体模型时被解析，并且与抽象模型的 app_label 无关

from django.db import models


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

    class Meta:
        abstract = True

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 来禁用它。如果您出于一致性而不是连接而创建外键，或者如果您将创建替代索引（如部分索引或多列索引），则可能希望避免索引的开销。

ManyToManyField¶

class ManyToManyField(to, **options)¶

多对多关系。需要一个位置参数：模型相关的类，其工作方式与 ForeignKey 完全相同，包括 递归 和 延迟 关系。

可以使用字段的 RelatedManager 添加、删除或创建相关对象。

OneToOneField¶

class OneToOneField(to, on_delete, parent_link=False, **options)¶

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

这在作为以某种方式“扩展”另一个模型的模型的主键时最有用；多表继承 是通过在子模型中添加一个隐式的从子模型到父模型的一对一关系来实现的，例如。

需要一个位置参数：模型将关联到的类。这与 ForeignKey 的工作方式完全相同，包括有关 递归 和 延迟 关系的所有选项。

如果您没有为 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

当访问反向关系时，如果相关表中不存在条目，则会引发 RelatedObjectDoesNotExist 异常。这是目标模型的 Model.DoesNotExist 异常的子类，可以作为反向访问器的属性访问。例如，如果用户没有由 MySpecialUser 指定的监督者

try:
    user.supervisor_of
except User.supervisor_of.RelatedObjectDoesNotExist:
    pass

此外，OneToOneField 接受 ForeignKey 接受的所有额外参数，以及一个额外参数

OneToOneField.parent_link¶

当为 True 并且在从另一个 具体模型 继承的模型中使用时，表示此字段应用作指向父类的链接，而不是通常由子类化隐式创建的额外 OneToOneField。

有关 OneToOneField 的使用示例，请参阅 一对一关系。