表單渲染 API

Django 的表單 widget 是使用 Django 的 樣板引擎系統 進行渲染。

表單渲染程序可以在多個層級進行客製化

  • Widget 可以指定客製化的樣板名稱。

  • 表單和 widget 可以指定客製化的渲染器類別。

  • widget 的樣板可以由專案覆寫。（可重複使用的應用程式通常不應該覆寫內建樣板，因為它們可能會與專案的客製化樣板衝突。）

底層渲染 API

表單樣板的渲染由可客製化的渲染器類別控制。可以透過更新 FORM_RENDERER 設定來指定客製化的渲染器。它預設為 'django.forms.renderers.DjangoTemplates'。

透過指定客製化的表單渲染器並覆寫 form_template_name，您可以從單一位置調整整個專案的預設表單標記。

您也可以透過設定 Form.default_renderer 屬性，或使用 Form.render() 或 Widget.render() 的 renderer 引數，來提供每個表單或每個 widget 的客製化渲染器。

對應點適用於表單集合渲染。請參閱 在檢視和樣板中使用表單集合 以取得討論。

使用其中一個 內建樣板表單渲染器，或實作您自己的渲染器。客製化渲染器必須實作 render(template_name, context, request=None) 方法。它應該會傳回渲染過的樣板（以字串形式），或引發 TemplateDoesNotExist。

class BaseRenderer[原始碼]

內建表單渲染器的基礎類別。

form_template_name

要用於渲染表單的樣板預設名稱。

預設為 "django/forms/div.html" 樣板。

formset_template_name

要用於渲染表單集合的樣板預設名稱。

預設為 "django/forms/formsets/div.html" 樣板。

field_template_name
在 Django 5.0 中新增。

用於渲染 BoundField 的樣板預設名稱。

預設為 "django/forms/field.html"

get_template(template_name)[原始碼]

子類別必須使用適當的樣板尋找邏輯實作此方法。

render(template_name, context, request=None)[原始碼]

渲染給定的樣板，或引發 TemplateDoesNotExist。

內建樣板表單渲染器

DjangoTemplates

class DjangoTemplates[原始碼]

此渲染器使用獨立的 DjangoTemplates 引擎（未連線至您在 TEMPLATES 設定中可能已設定的內容）。它會先從 django/forms/templates 中的內建表單樣板目錄載入樣板，然後使用 app_directories 載入器從已安裝應用程式的樣板目錄載入。

如果您想要使用來自 TEMPLATES 設定的客製化內容來渲染樣板，例如內容處理器，請使用 TemplatesSetting 渲染器。

class DjangoDivFormRenderer[原始碼]

自 5.0 版起已棄用。

DjangoTemplates 的別名。

Jinja2

class Jinja2[原始碼]

此渲染器與 DjangoTemplates 渲染器相同，差別在於它使用 Jinja2 後端。內建 widget 的樣板位於 django/forms/jinja2，已安裝的應用程式可以在 jinja2 目錄中提供樣板。

若要使用此後端，專案及其第三方應用程式中的所有表單和 widget 都必須具有 Jinja2 樣板。除非您為沒有 Jinja2 樣板的 widget 提供自己的 Jinja2 樣板，否則您無法使用此渲染器。例如，django.contrib.admin 因為使用 Django 樣板標籤，所以不包含其 widget 的 Jinja2 樣板。

class Jinja2DivFormRenderer[原始碼]

自 5.0 版起已棄用。

Jinja2 的別名。

TemplatesSetting

class TemplatesSetting[原始碼]

此渲染器讓您完全掌控表單和小部件範本的來源方式。它使用 get_template() 根據 TEMPLATES 設定中的配置來尋找範本。

使用此渲染器以及內建範本需要滿足以下任一條件：

  • 在 INSTALLED_APPS 中包含 'django.forms'，並且至少有一個引擎的 APP_DIRS=True。

  • 在您的其中一個範本引擎的 DIRS 中加入內建範本目錄。產生該路徑的方式為：

    import django

django.__path__[0] + "/forms/templates"  # or '/forms/jinja2'

使用此渲染器需要確保您的專案所需的表單範本可以被找到。

表單集範本中可用的內容

表單集範本從 BaseFormSet.get_context() 接收內容。預設情況下，表單集會接收一個包含以下值的字典：

  • formset: 表單集實例。

表單範本中可用的內容

表單範本從 Form.get_context() 接收內容。預設情況下，表單會接收一個包含以下值的字典：

  • form: 綁定的表單。

  • fields: 所有綁定的欄位，隱藏欄位除外。

  • hidden_fields: 所有隱藏的綁定欄位。

  • errors: 所有非欄位相關或隱藏欄位相關的表單錯誤。

欄位範本中可用的內容

在 Django 5.0 中新增。

欄位範本從 BoundField.get_context() 接收內容。預設情況下，欄位會接收一個包含以下值的字典：

小部件範本中可用的內容

小部件範本從 Widget.get_context() 接收內容。預設情況下，小部件會在內容中接收一個單一值，即 widget。這是一個包含如下值的字典：

  • name

  • value

  • attrs

  • is_hidden

  • template_name

某些小部件會將更多資訊新增到內容中。例如，所有繼承 Input 的小部件都會定義 widget['type']，而 MultiWidget 則會定義 widget['subwidgets'] 以用於迴圈。

覆寫內建表單集範本

BaseFormSet.template_name

若要覆寫表單集範本，您必須使用 TemplatesSetting 渲染器。然後覆寫表單集範本的方式與覆寫專案中的任何其他範本相同。

覆寫內建表單範本

Form.template_name

若要覆寫表單範本，您必須使用 TemplatesSetting 渲染器。然後覆寫表單範本的方式與覆寫專案中的任何其他範本相同。

覆寫內建欄位範本

在 Django 5.0 中新增。

Field.template_name

若要覆寫欄位範本，您必須使用 TemplatesSetting 渲染器。然後覆寫欄位範本的方式與覆寫專案中的任何其他範本相同。

覆寫內建小部件範本

每個小部件都有一個 template_name 屬性，其值例如 input.html。內建小部件範本儲存在 django/forms/widgets 路徑中。您可以透過定義 django/forms/widgets/input.html，為 input.html 提供自訂範本。有關每個小部件範本的名稱，請參閱內建小部件。

若要覆寫小部件範本，您必須使用 TemplatesSetting 渲染器。然後覆寫小部件範本的方式與覆寫專案中的任何其他範本相同。

表單集函數
小部件
回到頂部