欄位類型¶

您模型中的每個欄位都應該是適當的 Field 類別的實例。Django 使用欄位類別類型來判斷幾件事

• 欄位類型，這會告訴資料庫要儲存什麼類型的資料（例如，INTEGER、VARCHAR、TEXT）。

• 在呈現表單欄位時要使用的預設 HTML widget (例如，<input type="text">、<select>)。

• 最小驗證需求，用於 Django 管理介面和自動產生的表單中。

Django 附帶了數十種內建欄位類型；您可以在模型欄位參考中找到完整的清單。如果 Django 的內建欄位無法滿足您的需求，您可以輕鬆撰寫自己的欄位；請參閱如何建立自訂模型欄位。

欄位選項¶

每個欄位都接受一組特定的欄位特定引數（記錄在模型欄位參考中）。例如，CharField（及其子類別）需要一個 max_length 引數，該引數指定用於儲存資料的 VARCHAR 資料庫欄位的大小。

還有一個所有欄位類型都可以使用的通用引數集。全部都是可選的。它們在參考中有完整的說明，但這裡快速總結一下最常用的引數

null

如果為 True，Django 會將空值儲存為資料庫中的 NULL。預設值為 False。

blank

如果為 True，則允許欄位為空白。預設值為 False。

請注意，這與 null 不同。null 純粹與資料庫相關，而 blank 則與驗證相關。如果欄位具有 blank=True，表單驗證將允許輸入空值。如果欄位具有 blank=False，則欄位將為必填。

choices

一個 2 值元組的序列、一個對應、一個列舉類型，或一個可呼叫的（不期望任何引數並傳回先前任何格式）函數，用於作為此欄位的選項。如果給定此選項，預設的表單 widget 將會是一個選取方塊，而不是標準的文字欄位，並且會將選項限制為給定的選項。

選項清單如下所示

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

注意

每次 choices 的順序變更時，都會建立新的遷移。

每個元組中的第一個元素是將儲存在資料庫中的值。第二個元素會由欄位的表單 widget 顯示。

給定一個模型實例，可以使用 get_FOO_display() 方法存取具有 choices 的欄位的顯示值。例如

from django.db import models


class Person(models.Model):
    SHIRT_SIZES = {
        "S": "Small",
        "M": "Medium",
        "L": "Large",
    }
    name = models.CharField(max_length=60)
    shirt_size = models.CharField(max_length=1, choices=SHIRT_SIZES)

>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
'L'
>>> p.get_shirt_size_display()
'Large'

您也可以使用列舉類別以簡潔的方式定義 choices

from django.db import models


class Runner(models.Model):
    MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
    name = models.CharField(max_length=60)
    medal = models.CharField(blank=True, choices=MedalType, max_length=10)

在模型欄位參考中提供了更多範例。

在 Django 5.0 中變更

新增了對對應和可呼叫的函數的支援。

default

欄位的預設值。這可以是值或可呼叫的物件。如果是可呼叫的，則每次建立新物件時都會呼叫它。

db_default

欄位的資料庫計算預設值。這可以是字面值或資料庫函數。

如果同時設定了 db_default 和 Field.default，則在 Python 程式碼中建立實例時，default 將優先。 db_default 仍然會在資料庫層級設定，並且會在 ORM 之外插入列，或在遷移中新增新欄位時使用。

help_text

要與表單 widget 一起顯示的額外「說明」文字。即使您的欄位未使用在表單上，它對於文件也很有用。

primary_key

如果為 True，則此欄位為模型的主鍵。

如果您未在模型的任何欄位中指定 primary_key=True，Django 會自動新增一個 IntegerField 來保存主鍵，因此您不需要在任何欄位上設定 primary_key=True，除非您想要覆寫預設的主鍵行為。更多資訊請參閱 自動主鍵欄位。

主鍵欄位是唯讀的。如果您更改現有物件的主鍵值然後儲存，則會建立一個與舊物件並存的新物件。例如：

from django.db import models


class Fruit(models.Model):
    name = models.CharField(max_length=100, primary_key=True)

>>> fruit = Fruit.objects.create(name="Apple")
>>> fruit.name = "Pear"
>>> fruit.save()
>>> Fruit.objects.values_list("name", flat=True)
<QuerySet ['Apple', 'Pear']>

唯一

如果為 True，則此欄位在整個表格中必須是唯一的。

再次強調，這些只是最常見欄位選項的簡短描述。完整細節請見通用模型欄位選項參考。

自動主鍵欄位¶

預設情況下，Django 會為每個模型提供一個自動遞增的主鍵，其類型由每個應用程式在 AppConfig.default_auto_field 中指定，或在 DEFAULT_AUTO_FIELD 設定中全域指定。例如：

id = models.BigAutoField(primary_key=True)

如果您想指定自訂主鍵，請在您的其中一個欄位上指定 primary_key=True。如果 Django 發現您已明確設定 Field.primary_key，則它不會新增自動的 id 欄位。

每個模型都需要恰好一個欄位具有 primary_key=True（明確宣告或自動新增）。

詳細欄位名稱¶

除了 ForeignKey、ManyToManyField 和 OneToOneField 之外，每個欄位類型都接受一個可選的第一個位置參數 – 詳細名稱。如果未提供詳細名稱，Django 會自動使用欄位的屬性名稱建立它，並將底線轉換為空格。

在此範例中，詳細名稱為 "person's first name"

first_name = models.CharField("person's first name", max_length=30)

在此範例中，詳細名稱為 "first name"

first_name = models.CharField(max_length=30)

ForeignKey、ManyToManyField 和 OneToOneField 要求第一個參數為模型類別，因此請使用 verbose_name 關鍵字參數。

poll = models.ForeignKey(
    Poll,
    on_delete=models.CASCADE,
    verbose_name="the related poll",
)
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    verbose_name="related place",
)

慣例是不將 verbose_name 的第一個字母大寫。Django 會在需要時自動將第一個字母大寫。

關聯性¶

顯然，關聯式資料庫的威力在於將表格彼此關聯。Django 提供了定義三種最常見資料庫關聯類型的方法：多對一、多對多和一對一。

from django.db import models


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


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

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

from django.db import models


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


class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

from django.db import models


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

    def __str__(self):
        return self.name


class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, through="Membership")

    def __str__(self):
        return self.name


class Membership(models.Model):
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    date_joined = models.DateField()
    invite_reason = models.CharField(max_length=64)

>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(
...     person=ringo,
...     group=beatles,
...     date_joined=date(1962, 8, 16),
...     invite_reason="Needed a new drummer.",
... )
>>> m1.save()
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>]>
>>> ringo.group_set.all()
<QuerySet [<Group: The Beatles>]>
>>> m2 = Membership.objects.create(
...     person=paul,
...     group=beatles,
...     date_joined=date(1960, 8, 1),
...     invite_reason="Wanted to form a band.",
... )
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>

>>> beatles.members.add(john, through_defaults={"date_joined": date(1960, 8, 1)})
>>> beatles.members.create(
...     name="George Harrison", through_defaults={"date_joined": date(1960, 8, 1)}
... )
>>> beatles.members.set(
...     [john, paul, ringo, george], through_defaults={"date_joined": date(1960, 8, 1)}
... )

>>> Membership.objects.create(
...     person=ringo,
...     group=beatles,
...     date_joined=date(1968, 9, 4),
...     invite_reason="You've been gone for a month and we miss you.",
... )
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>
>>> # This deletes both of the intermediate model instances for Ringo Starr
>>> beatles.members.remove(ringo)
>>> beatles.members.all()
<QuerySet [<Person: Paul McCartney>]>

>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
<QuerySet []>

# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith="Paul")
<QuerySet [<Group: The Beatles>]>

# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
...     group__name="The Beatles", membership__date_joined__gt=date(1961, 1, 1)
... )
<QuerySet [<Person: Ringo Starr]>

>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

跨檔案的模型¶

將模型與另一個應用程式中的模型關聯完全沒問題。若要執行此操作，請在定義模型之檔案的頂端匯入相關模型。然後，在任何需要的地方參照其他模型類別。例如：

from django.db import models
from geography.models import ZipCode


class Restaurant(models.Model):
    # ...
    zip_code = models.ForeignKey(
        ZipCode,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )

欄位名稱限制¶

Django 對模型欄位名稱施加了一些限制：

1. 欄位名稱不能是 Python 保留字，因為這會導致 Python 語法錯誤。例如：

   class Example(models.Model):
       pass = models.IntegerField() # 'pass' is a reserved word!
   

2. 欄位名稱不能連續包含多個底線，因為這是 Django 查詢查找語法的運作方式。例如：

   class Example(models.Model):
       foo__bar = models.IntegerField()  # 'foo__bar' has two underscores!
   

3. 由於類似的原因，欄位名稱不能以底線結尾。

不過，這些限制可以解決，因為您的欄位名稱不一定必須與您的資料庫資料行名稱相符。請參閱 db_column 選項。

SQL 保留字（例如 join、 where 或 select）*允許* 作為模型欄位名稱，因為 Django 會在每個基礎 SQL 查詢中逸出所有資料庫資料表名稱和資料行名稱。它使用您特定資料庫引擎的引用語法。

自訂欄位類型¶

如果現有的模型欄位之一無法用於滿足您的目的，或者如果您希望利用一些較不常見的資料庫資料行類型，您可以建立自己的欄位類別。建立您自己的欄位的完整涵蓋範圍，請參閱 如何建立自訂模型欄位。

覆寫預定義的模型方法¶

還有另一組 模型方法，封裝了您想要自訂的大量資料庫行為。尤其是您經常會想要變更 save() 和 delete() 的運作方式。

您可以自由覆寫這些方法（以及任何其他模型方法）以變更行為。

覆寫內建方法的經典用例是，如果您希望在每次儲存物件時都發生某些事情。例如（請參閱 save() 以取得它接受的參數的文件）

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, **kwargs):
        do_something()
        super().save(**kwargs)  # Call the "real" save() method.
        do_something_else()

您也可以阻止儲存

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, **kwargs):
        if self.name == "Yoko Ono's blog":
            return  # Yoko shall never have her own blog!
        else:
            super().save(**kwargs)  # Call the "real" save() method.

請務必記得呼叫超類別方法 – 即 super().save(**kwargs) 的用法 – 以確保物件仍會儲存到資料庫中。如果您忘記呼叫超類別方法，則不會發生預設行為，並且不會接觸到資料庫。

您也必須傳遞可以傳遞給模型方法的引數 – 這就是 **kwargs 位元的作用。Django 會不時擴展內建模型方法的功能，加入新的關鍵字引數。如果您在方法定義中使用 **kwargs，則可以保證您的程式碼會在新增這些引數時自動支援它們。

如果您希望在 save() 方法中更新欄位值，您可能也會希望將此欄位新增到 update_fields 關鍵字引數。這將確保在指定 update_fields 時儲存欄位。例如

from django.db import models
from django.utils.text import slugify


class Blog(models.Model):
    name = models.CharField(max_length=100)
    slug = models.TextField()

    def save(self, **kwargs):
        self.slug = slugify(self.name)
        if (
            update_fields := kwargs.get("update_fields")
        ) is not None and "name" in update_fields:
            kwargs["update_fields"] = {"slug"}.union(update_fields)
        super().save(**kwargs)

請參閱 指定要儲存的欄位 以取得更多詳細資料。

執行自訂 SQL¶

另一種常見模式是在模型方法和模組級方法中撰寫自訂 SQL 陳述式。如需使用原始 SQL 的更多詳細資料，請參閱使用原始 SQL的文件。

抽象基底類別¶

當您想要將一些通用資訊放入多個其他模型中時，抽象基底類別很有用。您撰寫您的基底類別，並在 Meta 類別中放入 abstract=True。然後，此模型將不會用於建立任何資料庫表格。相反地，當它用作其他模型的基底類別時，它的欄位將會新增至子類別的欄位中。

一個範例

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True


class Student(CommonInfo):
    home_group = models.CharField(max_length=5)

Student 模型將具有三個欄位：name、age 和 home_group。CommonInfo 模型不能用作一般的 Django 模型，因為它是抽象基底類別。它不會產生資料庫表格或具有管理員，而且不能直接執行個體化或儲存。

從抽象基底類別繼承的欄位可以使用另一個欄位或值覆寫，或使用 None 移除。

對於許多用途而言，此類型的模型繼承正是您想要的。它提供一種在 Python 級別分解通用資訊的方法，同時仍然只在資料庫級別為每個子模型建立一個資料庫表格。

from django.db import models


class CommonInfo(models.Model):
    # ...
    class Meta:
        abstract = True
        ordering = ["name"]


class Student(CommonInfo):
    # ...
    class Meta(CommonInfo.Meta):
        db_table = "student_info"

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True
        ordering = ["name"]


class Unmanaged(models.Model):
    class Meta:
        abstract = True
        managed = False


class Student(CommonInfo, Unmanaged):
    home_group = models.CharField(max_length=5)

    class Meta(CommonInfo.Meta, Unmanaged.Meta):
        pass

from django.db import models


class Base(models.Model):
    m2m = models.ManyToManyField(
        OtherModel,
        related_name="%(app_label)s_%(class)s_related",
        related_query_name="%(app_label)s_%(class)ss",
    )

    class Meta:
        abstract = True


class ChildA(Base):
    pass


class ChildB(Base):
    pass

from common.models import Base


class ChildB(Base):
    pass

多表格繼承¶

Django 支援的第二種模型繼承類型是當階層中的每個模型本身都是一個模型時。每個模型都對應到自己的資料庫表格，並且可以單獨查詢和建立。繼承關係會在子模型和其每個父模型之間引入連結（透過自動建立的 OneToOneField）。例如：

from django.db import models


class Place(models.Model):
    name = models.CharField(max_length=50)
    address = models.CharField(max_length=80)


class Restaurant(Place):
    serves_hot_dogs = models.BooleanField(default=False)
    serves_pizza = models.BooleanField(default=False)

Place 的所有欄位也會在 Restaurant 中提供使用，儘管資料將會存在於不同的資料庫表格中。所以這兩種都是可行的：

>>> Place.objects.filter(name="Bob's Cafe")
>>> Restaurant.objects.filter(name="Bob's Cafe")

如果你有一個同時也是 Restaurant 的 Place，你可以使用模型名稱的小寫版本，從 Place 物件取得 Restaurant 物件：

>>> p = Place.objects.get(id=12)
# If p is a Restaurant object, this will give the child class:
>>> p.restaurant
<Restaurant: ...>

然而，如果上面範例中的 p 不是 Restaurant（它是直接作為 Place 物件建立的，或是某些其他類別的父類別），參考 p.restaurant 將會引發 Restaurant.DoesNotExist 例外。

在 Restaurant 上自動建立的 OneToOneField 將其連結到 Place，看起來像這樣：

place_ptr = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    parent_link=True,
    primary_key=True,
)

你可以透過在 Restaurant 上宣告你自己的 OneToOneField，並使用 parent_link=True 來覆寫該欄位。

class ChildModel(ParentModel):
    # ...
    class Meta:
        # Remove parent's ordering effect
        ordering = []

class Supplier(Place):
    customers = models.ManyToManyField(Place)

Reverse query name for 'Supplier.customers' clashes with reverse query
name for 'Supplier.place_ptr'.

HINT: Add or change a related_name argument to the definition for
'Supplier.customers' or 'Supplier.place_ptr'.

代理模型¶

當使用 多表繼承 時，會為模型的每個子類別建立一個新的資料庫表格。這通常是期望的行為，因為子類別需要一個地方來儲存基本類別上不存在的任何其他資料欄位。但是，有時您只想變更模型的 Python 行為 - 可能要變更預設的管理員，或新增一個新方法。

這就是代理模型繼承的用途：為原始模型建立代理。您可以建立、刪除和更新代理模型的實例，並且所有資料都會被儲存，就像您正在使用原始（非代理）模型一樣。不同之處在於，您可以在代理中變更預設的模型排序或預設的管理員等，而無需變更原始模型。

代理模型會像普通模型一樣宣告。您通過將 Meta 類別的 proxy 屬性設定為 True 來告訴 Django 它是一個代理模型。

例如，假設您想向 Person 模型新增一個方法。您可以這樣做

from django.db import models


class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)


class MyPerson(Person):
    class Meta:
        proxy = True

    def do_something(self):
        # ...
        pass

MyPerson 類別與其父類別 Person 類別在同一個資料庫表格上操作。特別是，任何新的 Person 實例也可以通過 MyPerson 存取，反之亦然

>>> p = Person.objects.create(first_name="foobar")
>>> MyPerson.objects.get(first_name="foobar")
<MyPerson: foobar>

您也可以使用代理模型在模型上定義不同的預設排序。您可能不總是想排序 Person 模型，但在您使用代理時，通常會依 last_name 屬性排序

class OrderedPerson(Person):
    class Meta:
        ordering = ["last_name"]
        proxy = True

現在，普通的 Person 查詢將不會排序，而 OrderedPerson 查詢將依 last_name 排序。

代理模型繼承 Meta 屬性，與一般模型相同的方式。

from django.db import models


class NewManager(models.Manager):
    # ...
    pass


class MyPerson(Person):
    objects = NewManager()

    class Meta:
        proxy = True

# Create an abstract class for the new manager.
class ExtraManagers(models.Model):
    secondary = NewManager()

    class Meta:
        abstract = True


class MyPerson(Person, ExtraManagers):
    class Meta:
        proxy = True

多重繼承¶

就像 Python 的子類別化一樣，Django 模型可以從多個父模型繼承。請記住，會套用一般的 Python 名稱解析規則。特定名稱（例如 Meta）出現的第一個基本類別將是被使用的類別；例如，這表示如果多個父類別包含 Meta 類別，則只會使用第一個，而所有其他的都會被忽略。

一般來說，您不需要從多個父類別繼承。這種方法有用的主要使用案例是用於「混入」類別：將特定的額外欄位或方法新增到繼承混入的每個類別。盡量使您的繼承層次結構盡可能簡單和直接，這樣您就不必費力地弄清楚特定資訊的來源。

請注意，從具有共同 id 主索引鍵欄位的多個模型繼承會引發錯誤。要正確使用多重繼承，您可以在基本模型中使用明確的 AutoField

class Article(models.Model):
    article_id = models.AutoField(primary_key=True)
    ...


class Book(models.Model):
    book_id = models.AutoField(primary_key=True)
    ...


class BookReview(Book, Article):
    pass

或者使用一個共同的祖先來持有 AutoField。這需要從每個父模型到共同的祖先使用明確的 OneToOneField，以避免自動產生並由子項繼承的欄位之間發生衝突。

class Piece(models.Model):
    pass


class Article(Piece):
    article_piece = models.OneToOneField(
        Piece, on_delete=models.CASCADE, parent_link=True
    )
    ...


class Book(Piece):
    book_piece = models.OneToOneField(Piece, on_delete=models.CASCADE, parent_link=True)
    ...


class BookReview(Book, Article):
    pass

不允許「隱藏」欄位名稱¶

在一般的 Python 類別繼承中，子類別可以覆寫父類別的任何屬性。在 Django 中，模型欄位通常不允許這樣做。如果一個非抽象模型基底類別有一個名為 author 的欄位，你不能在任何繼承自該基底類別的類別中建立另一個模型欄位或定義一個名為 author 的屬性。

此限制不適用於從抽象模型繼承的模型欄位。這些欄位可以使用另一個欄位或值覆寫，或者透過設定 field_name = None 來移除。

覆寫父模型中的欄位會導致在初始化新實例（指定在 Model.__init__ 中初始化哪個欄位）和序列化等領域出現困難。這些功能是正常的 Python 類別繼承不需要以完全相同的方式處理的，因此 Django 模型繼承和 Python 類別繼承之間的差異並非任意的。

此限制僅適用於 Field 實例的屬性。如果需要，可以覆寫一般的 Python 屬性。它也僅適用於 Python 所看到的屬性名稱：如果你是手動指定資料庫欄名稱，則可以在子模型和祖先模型中，針對多表繼承使用相同的欄名稱（它們是兩個不同資料庫表中的欄位）。

如果你在任何祖先模型中覆寫任何模型欄位，Django 將會引發 FieldError。

請注意，由於在類別定義期間解析欄位的方式，從多個抽象父模型繼承的模型欄位會以嚴格的深度優先順序解析。這與標準的 Python MRO 相反，後者在菱形繼承的情況下會以廣度優先的方式解析。這種差異只會影響複雜的模型層次結構，你應該（按照上面的建議）盡量避免這種情況。