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[source]¶

下面描述的格式的映射或可迭代对象，用作此字段的选项。如果给出选项，则它们由 模型验证 强制执行，并且默认表单小部件将是具有这些选项的选择框，而不是标准文本字段。

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

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，否则选择框将显示包含 "---------" 的标签。要覆盖此行为，请向 choices 添加一个包含 None 的元组；例如 (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_default 但未设置 default，并且未为该字段赋值，则在未保存的模型实例上，DatabaseDefault 对象作为字段值返回。保存模型实例时，数据库将确定该字段的实际值。

db_index¶

Field.db_index¶

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

db_tablespace¶

Field.db_tablespace[source]¶

为此字段索引使用的 数据库表空间 的名称（如果此字段已编入索引）。默认值为项目的 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这样的映射到模型实例的字段，默认值应该是它们引用的字段的值（除非设置了to_field，否则为pk），而不是模型实例。

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

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

editable¶

Field.editable¶

如果为False，则该字段不会显示在管理员界面或任何其他ModelForm中。在模型验证期间也会跳过它们。默认为True。

error_messages¶

Field.error_messages[source]¶

使用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[source]¶

如果为True，则此字段在整个表中必须唯一。

这在数据库级别和模型验证时都会强制执行。如果您尝试保存一个在unique字段中具有重复值的模型，则模型的save()方法将引发django.db.IntegrityError。

此选项对ManyToManyField和OneToOneField以外的所有字段类型都有效。

请注意，当unique为True时，您不需要指定db_index，因为unique暗示创建索引。

unique_for_date¶

Field.unique_for_date¶

将其设置为DateField或DateTimeField的名称，以要求此字段对于日期字段的值是唯一的。

例如，如果您有一个具有unique_for_date="pub_date"的字段title，那么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¶

字段的可读名称。如果没有提供verbose_name，Django将自动使用字段的属性名创建它，并将下划线转换为空格。参见Verbose field names。

validators¶

Field.validators[source]¶

为此字段运行的验证器列表。有关更多信息，请参见validators documentation。

AutoField¶

class AutoField(**options)[source]¶

一个IntegerField，根据可用的ID自动递增。通常不需要直接使用它；如果未另行指定，则主键字段将自动添加到您的模型中。参见Automatic primary key fields。

BigAutoField¶

class BigAutoField(**options)[source]¶

一个64位整数，非常类似于AutoField，不同之处在于它保证可以容纳从1到9223372036854775807的数字。

BigIntegerField¶

class BigIntegerField(**options)[source]¶

一个64位整数，非常类似于IntegerField，不同之处在于它保证可以容纳从-9223372036854775808到9223372036854775807的数字。此字段的默认表单小部件是NumberInput。

BinaryField¶

class BinaryField(max_length=None, **options)[source]¶

用于存储原始二进制数据的字段。可以赋值bytes、bytearray或memoryview。

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

BinaryField.max_length¶

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

BooleanField¶

class BooleanField(**options)[source]¶

一个真/假字段。

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

当Field.default未定义时，BooleanField的默认值为None。

CharField¶

class CharField(max_length=None, **options)[source]¶

字符串字段，用于大小不一的字符串。

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

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

CharField 有以下额外参数

CharField.max_length¶

字段的最大长度（以字符为单位）。max_length在数据库级别和Django的验证中强制执行，使用MaxLengthValidator。除了PostgreSQL（支持无限长的VARCHAR列）之外，Django包含的所有数据库后端都需要此参数。

注意

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

CharField.db_collation¶

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

注意

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

Oracle

只有当MAX_STRING_SIZE数据库初始化参数设置为EXTENDED时，Oracle才支持排序规则。

DateField¶

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

日期，在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)[source]¶

日期和时间，在Python中由datetime.datetime实例表示。接受与DateField相同的额外参数。

此字段的默认表单小部件是一个单独的DateTimeInput。管理员使用带有JavaScript快捷方式的两个单独的TextInput小部件。

DecimalField¶

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

定点精度十进制数，在Python中由Decimal实例表示。它使用DecimalValidator验证输入。

具有以下**必需**参数

DecimalField.max_digits¶

数字允许的最大位数。请注意，此数字必须大于或等于decimal_places。

DecimalField.decimal_places¶

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

例如，要以2位小数的精度存储高达999.99的数字，可以使用

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)[source]¶

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

EmailField¶

class EmailField(max_length=254, **options)[source]¶

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

FileField¶

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

文件上传字段。

具有以下可选参数

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¶

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

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

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

1. 在你的设置文件中，你需要将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 类参考和文件管理主题指南。

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

请注意，每当处理上传的文件时，都应密切注意上传文件的位置和文件类型，以避免安全漏洞。验证所有上传的文件，确保文件是您认为的文件。例如，如果您盲目地允许某人将文件上传到 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)[source]¶

一个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)[source]¶

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

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

GeneratedField¶

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

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

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

GeneratedField.expression¶

数据库用来在每次更改模型时自动设置字段值的 Expression。

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

GeneratedField.output_field¶

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

GeneratedField.db_persist¶

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

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

GenericIPAddressField¶

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

一个 IPv4 或 IPv6 地址，以字符串格式（例如 192.0.2.30 或 2a02:42fe::4）。此字段的默认表单小部件是 TextInput。

IPv6 地址规范化遵循 RFC 4291 第 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)[source]¶

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

除了 FileField 可用的特殊属性外，ImageField 还具有 height 和 width 属性。

为了方便对这些属性进行查询，ImageField 具有以下可选参数

ImageField.height_field¶

每次设置图像对象时，自动填充图像高度的模型字段名称。

ImageField.width_field¶

每次设置图像对象时，自动填充图像宽度的模型字段名称。

需要 pillow 库。

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

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

IntegerField¶

class IntegerField(**options)[source]¶

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

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

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

JSONField¶

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

用于存储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)[source]¶

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

PositiveIntegerField¶

class PositiveIntegerField(**options)[source]¶

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

PositiveSmallIntegerField¶

class PositiveSmallIntegerField(**options)[source]¶

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

SlugField¶

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

Slug 是新闻术语。Slug 是事物的简短标签，仅包含字母、数字、下划线或连字符。它们通常用于 URL。

与 CharField 一样，您可以指定 max_length（也请阅读关于数据库可移植性和max_length的那一部分说明）。如果未指定max_length，Django 将使用默认长度 50。

意味着将Field.db_index设置为True。

通常情况下，根据其他字段的值自动填充 SlugField 非常有用。您可以使用 prepopulated_fields在admin中自动执行此操作。

它使用validate_slug或validate_unicode_slug进行验证。

SlugField.allow_unicode¶

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

SmallAutoField¶

class SmallAutoField(**options)[source]¶

类似于AutoField，但仅允许小于某个（取决于数据库）限制的值。在 Django 支持的所有数据库中，1到32767的值都是安全的。

SmallIntegerField¶

class SmallIntegerField(**options)[source]¶

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

TextField¶

class TextField(**options)[source]¶

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

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

TextField.db_collation¶

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

注意

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

Oracle

Oracle 不支持 TextField 的排序规则。

TimeField¶

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

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

此字段的默认表单小部件是TimeInput。admin 添加了一些 JavaScript 快捷方式。

URLField¶

class URLField(max_length=200, **options)[source]¶

一个用于 URL 的CharField，由URLValidator验证。

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

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

UUIDField¶

class UUIDField(**options)[source]¶

用于存储通用唯一标识符的字段。使用 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)[source]¶

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

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()


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

第一个位置参数可以是具体的模型类或对模型类的 延迟引用。还支持 递归关系，其中模型与其自身具有关系。

有关第二个位置参数的详细信息，请参阅 ForeignKey.on_delete。

数据库索引会自动在 ForeignKey 上创建。可以通过将 db_index 设置为 False 来禁用此功能。如果您出于一致性而不是连接的目的创建外键，或者如果您将创建替代索引（例如部分索引或多列索引），则可能需要避免索引的开销。

ManyToManyField¶

class ManyToManyField(to, **options)[source]¶

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

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

OneToOneField¶

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

一对一关系。从概念上讲，这类似于 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 的使用方法示例，请参阅 一对一关系。

延迟关系¶

延迟关系允许通过其名称（作为字符串）引用模型或创建递归关系。字符串可用作任何关系字段中的第一个参数，以延迟地引用模型。延迟引用可以是 递归的、相对的 或 绝对的。

from django.db import models


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

from django.db import models


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


class Manufacturer(models.Model):
    name = models.TextField()
    suppliers = models.ManyToManyField("self", symmetrical=False)

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):
    name = models.TextField()


class Car(AbstractCar):
    pass

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