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[來源]¶

以下述格式描述的對應或可迭代物件，用作此欄位的選項。如果提供選項，則會透過 模型驗證 強制執行，並且預設表單 widget 將是一個包含這些選項的選取方塊，而不是標準的文字欄位。

如果給定對應，則鍵元素是要在模型上設定的實際值，第二個元素是人類可讀的名稱。例如

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

您也可以傳遞一個序列，該序列本身由恰好包含兩個項目的可迭代物件組成 (例如 [(A1, B1), (A2, B2), …])。每個 tuple 中的第一個元素是要在模型上設定的實際值，第二個元素是人類可讀的名稱。例如

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)

當選項是

• I/O 繫結操作的結果時 (可能會快取)，例如在相同或外部資料庫中查詢資料表，或從靜態檔案存取選項時，傳遞可呼叫物件作為 choices 會特別方便。

• 一個大多穩定但可能不時或因專案而異的清單。此類別中的範例是使用第三方應用程式，這些應用程式提供了貨幣、國家/地區、語言、時區等眾所周知的數值清單。

通常，最好在模型類別內定義選項，並為每個值定義一個適當命名的常數

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-tuple 的清單

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

請注意，選項可以是任何序列物件，不一定是清單或 tuple。這可讓您動態建構選項。但是，如果您發現自己正在駭入 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 之外插入資料列或在遷移中新增欄位時使用。

如果欄位具有未設定 default 的 db_default，且未將值指派給該欄位，則會在未儲存的模型實例上以欄位值傳回 DatabaseDefault 物件。欄位的實際值由資料庫在儲存模型實例時決定。

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，也會使用預設值。

也可以使用 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。以下 欄位類型 部分中會為每個欄位指定其他錯誤訊息的鍵。

這些錯誤訊息通常不會傳播到表單。請參閱關於模型錯誤訊息的考量。

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¶

欄位的人性化名稱。如果未給定 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¶

可選。欄位的最大長度（以位元組為單位）。最大長度會使用 MaxLengthValidator 在 Django 的驗證中強制執行。

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 強制執行。對於 Django 包含的所有資料庫後端，除了支援無限制 VARCHAR 欄位的 PostgreSQL 之外，這都是必需的。

注意

如果您正在編寫必須可移植到多個資料庫後端的應用程式，您應該了解某些後端的 max_length 存在限制。有關詳細資訊，請參閱資料庫後端說明。

CharField.db_collation¶

選用。欄位的資料庫定序名稱。

注意

定序名稱並未標準化。因此，這將無法在多個資料庫後端之間移植。

Oracle

只有在 MAX_STRING_SIZE 資料庫初始化參數設定為 EXTENDED 時，Oracle 才支援定序。

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¶

要儲存的數字的小數位數。

例如，要儲存解析度為 2 位小數、最大值為 999.99 的數字，您會使用：

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

而要儲存解析度為 10 位小數、最大值約為 10 億的數字，則會使用：

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

當 localize 為 False 時，此欄位的預設表單小部件是 NumberInput，否則為 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¶

一個儲存物件，或是一個會回傳儲存物件的可呼叫物件。此物件處理檔案的儲存與檢索。關於如何提供此物件的詳細資訊，請參閱管理檔案。

此欄位的預設表單小工具是 ClearableFileInput。

在模型中使用 FileField 或 ImageField（見下文）需要幾個步驟：

1. 在您的設定檔中，您需要定義 MEDIA_ROOT 作為您希望 Django 儲存上傳檔案的完整路徑。（為了效能考量，這些檔案不會儲存在資料庫中。）定義 MEDIA_URL 作為該目錄的基本公開 URL。請確保此目錄可由網頁伺服器的使用者帳戶寫入。

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() 方法。

請注意，無論何時處理上傳的檔案，您都應密切注意您上傳檔案的位置以及檔案的類型，以避免安全漏洞。驗證所有上傳的檔案，以確保檔案是您認為的檔案。例如，如果您盲目地讓某人將檔案上傳到您網頁伺服器文件根目錄中的目錄，而未經驗證，那麼某人可能會上傳 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 實例表示。

當 localize 為 False 時，此欄位的預設表單小部件是 NumberInput，否則為 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 第 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¶

解壓縮類似 ::ffff:192.0.2.1 的 IPv4 對應位址。如果啟用此選項，則該位址將解壓縮為 192.0.2.1。預設為停用。僅當 protocol 設定為 'both' 時才能使用。

如果您允許空白值，則必須允許 Null 值，因為空白值會儲存為 Null。

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)[原始碼]¶

一個整數。在 Django 支援的所有資料庫中，從 -2147483648 到 2147483647 的值都是安全的。

它使用 MinValueValidator 和 MaxValueValidator，根據預設資料庫支援的值來驗證輸入。

當 localize 為 False 時，此欄位的預設表單小部件是 NumberInput，否則為 TextInput。

JSONField¶

class JSONField(encoder=None, decoder=None, **options)[原始碼]¶

一個用於儲存 JSON 編碼資料的欄位。在 Python 中，資料以其 Python 原生格式表示：字典、列表、字串、數字、布林值和 None。

MariaDB、MySQL、Oracle、PostgreSQL 和 SQLite（啟用 JSON1 擴充功能）支援 JSONField。

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)[原始碼]¶

一個大型文字欄位。此欄位的預設表單 Widget 是一個 Textarea。

如果您指定 max_length 屬性，它將反映在自動產生的表單欄位的 Textarea Widget 中。但是，它不會在模型或資料庫層級強制執行。請使用 CharField 來實現此目的。

TextField.db_collation¶

選用。欄位的資料庫定序名稱。

注意

定序名稱並未標準化。因此，這將無法在多個資料庫後端之間移植。

Oracle

Oracle 不支援 TextField 的排序規則。

TimeField¶

class TimeField(auto_now=False, auto_now_add=False, **options)[原始碼]¶

以 Python 的 datetime.time 實例表示的時間。接受與 DateField 相同的自動填入選項。

此欄位的預設表單 Widget 是一個 TimeInput。管理介面會加入一些 JavaScript 快捷方式。

URLField¶

class URLField(max_length=200, **options)[原始碼]¶

用於 URL 的 CharField，由 URLValidator 驗證。

此欄位的預設表單 Widget 是一個 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 選項。

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)[原始碼]¶

多對多關係。需要一個位置引數：模型關聯的類別，其工作方式與 ForeignKey 完全相同，包括遞迴和延遲關係。

可以使用欄位的 RelatedManager 新增、移除或建立關聯物件。

OneToOneField¶

class OneToOneField(to, on_delete, parent_link=False, **options)[原始碼]¶

一對一關係。概念上，這與具有 unique=True 的 ForeignKey 相似，但關係的「反向」端將直接返回單個物件。

這最常用於以某種方式「擴展」另一個模型之模型的主鍵；例如，多表繼承 是通過從子模型到父模型添加隱式的一對一關係來實現的。

需要一個位置引數：模型將與之關聯的類別。這與 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,
    )