取得協助

el
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
語言：en

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
dev
文件版本：5.1

表單欄位¶

class Field[原始碼]¶

當您建立 Form 類別時，最重要的部分是定義表單的欄位。每個欄位都有自訂的驗證邏輯，以及一些其他的鉤子。

Field.clean(value)[原始碼]¶

雖然您使用 Field 類別的主要方式是在 Form 類別中，您也可以實例化它們並直接使用它們，以更好地了解它們的工作方式。每個 Field 實例都有一個 clean() 方法，它接受單一參數，並拋出 django.core.exceptions.ValidationError 例外，或者返回經過清理的值。

>>> from django import forms
>>> f = forms.EmailField()
>>> f.clean("foo@example.com")
'foo@example.com'
>>> f.clean("invalid email address")
Traceback (most recent call last):
...
ValidationError: ['Enter a valid email address.']

核心欄位引數¶

每個 Field 類別建構子至少接受這些引數。某些 Field 類別會接受額外的、特定於欄位的引數，但以下引數應始終被接受

`required`¶

Field.required¶

預設情況下，每個 Field 類別都假設該值是必要的，因此如果您傳遞一個空值 — None 或空字串 ("") — 則 clean() 將會拋出 ValidationError 例外。

>>> from django import forms
>>> f = forms.CharField()
>>> f.clean("foo")
'foo'
>>> f.clean("")
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(None)
Traceback (most recent call last):
...
ValidationError: ['This field is required.']
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

若要指定欄位是不必要的，請將 required=False 傳遞給 Field 建構子。

>>> f = forms.CharField(required=False)
>>> f.clean("foo")
'foo'
>>> f.clean("")
''
>>> f.clean(None)
''
>>> f.clean(0)
'0'
>>> f.clean(True)
'True'
>>> f.clean(False)
'False'

如果 Field 具有 required=False 並且您將空值傳遞給 clean()，則 clean() 將會返回一個正規化的空值，而不是拋出 ValidationError。對於 CharField，這將返回 empty_value，預設為空字串。對於其他 Field 類別，它可能是 None。(這因欄位而異。)

必要表單欄位的 Widget 具有 required HTML 屬性。將 Form.use_required_attribute 屬性設定為 False 以停用它。表單集中的表單不包含 required 屬性，因為在新增和刪除表單集時，瀏覽器驗證可能不正確。

`label`¶

Field.label¶

label 引數可讓您指定此欄位的「人性化」標籤。當 Field 顯示在 Form 中時會使用此標籤。

如將表單輸出為 HTML 中所述，Field 的預設標籤是從欄位名稱產生的，方法是將所有底線轉換為空格並將第一個字母大寫。如果預設行為無法產生適當的標籤，請指定 label。

這是一個完整的 Form 範例，它為其兩個欄位實作了 label。我們已指定 auto_id=False 以簡化輸出

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(label="Your name")
...     url = forms.URLField(label="Your website", required=False)
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>

`label_suffix`¶

Field.label_suffix¶

label_suffix 引數可讓您在每個欄位的基礎上覆寫表單的 label_suffix。

>>> class ContactForm(forms.Form):
...     age = forms.IntegerField()
...     nationality = forms.CharField()
...     captcha_answer = forms.IntegerField(label="2 + 2", label_suffix=" =")
...
>>> f = ContactForm(label_suffix="?")
>>> print(f)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>

`initial`¶

Field.initial¶

initial 引數可讓您指定在未繫結的 Form 中呈現此 Field 時要使用的初始值。

若要指定動態初始資料，請參閱 Form.initial 參數。

此引數的用例是當您想要顯示一個「空的」表單，其中欄位會初始化為特定值時。例如

>>> from django import forms
>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>

您可能會想，為什麼不直接在顯示表單時傳遞初始值的字典作為資料？嗯，如果您這樣做，您將觸發驗證，並且 HTML 輸出將包含任何驗證錯誤。

>>> class CommentForm(forms.Form):
...     name = forms.CharField()
...     url = forms.URLField()
...     comment = forms.CharField()
...
>>> default_data = {"name": "Your name", "url": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
  <input type="text" name="name" value="Your name" required>
</div>
<div>Url:
  <ul class="errorlist"><li>Enter a valid URL.</li></ul>
  <input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
  <ul class="errorlist"><li>This field is required.</li></ul>
  <input type="text" name="comment" required aria-invalid="true">
</div>

這就是為什麼 initial 值僅顯示於未繫結的表單。對於繫結的表單，HTML 輸出將使用繫結的資料。

另請注意，如果未提供特定欄位的值，則 initial 值不會在驗證中用作「後備」資料。initial 值僅用於初始表單顯示。

>>> class CommentForm(forms.Form):
...     name = forms.CharField(initial="Your name")
...     url = forms.URLField(initial="https://")
...     comment = forms.CharField()
...
>>> data = {"name": "", "url": "", "comment": "Foo"}
>>> f = CommentForm(data)
>>> f.is_valid()
False
# The form does *not* fallback to using the initial values.
>>> f.errors
{'url': ['This field is required.'], 'name': ['This field is required.']}

除了常數之外，您也可以傳遞任何可呼叫的對象。

>>> import datetime
>>> class DateForm(forms.Form):
...     day = forms.DateField(initial=datetime.date.today)
...
>>> print(DateForm())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>

該可呼叫對象僅在顯示未繫結的表單時評估，而不是在定義時評估。

`help_text`¶

Field.help_text¶

help_text 引數可讓您指定此 Field 的描述文字。如果您提供 help_text，則當 Field 由其中一個便利的 Form 方法（例如，as_ul()）呈現時，它會顯示在 Field 旁邊。

與模型欄位的 help_text 類似，此值不會在自動產生的表單中進行 HTML 跳脫。

這是一個完整的 Form 範例，它為其兩個欄位實作了 help_text。我們已指定 auto_id=False 以簡化輸出

>>> from django import forms
>>> class HelpTextContactForm(forms.Form):
...     subject = forms.CharField(max_length=100, help_text="100 characters max.")
...     message = forms.CharField()
...     sender = forms.EmailField(help_text="A valid email address, please.")
...     cc_myself = forms.BooleanField(required=False)
...
>>> f = HelpTextContactForm(auto_id=False)
>>> print(f)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
<div>Cc myself:<input type="checkbox" name="cc_myself"></div>

當欄位具有說明文字時，它會使用 aria-describedby HTML 屬性與其輸入相關聯。如果 Widget 在 <fieldset> 中呈現，則會將 aria-describedby 新增至此元素，否則會將其新增至 Widget 的 <input>。

>>> from django import forms
>>> class UserForm(forms.Form):
...     username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>

在新增自訂 aria-describedby 屬性時，請確保也包含 help_text 元素的 id（如果使用），並以所需的順序排列。對於螢幕閱讀器使用者，說明將按照它們在 aria-describedby 中出現的順序讀取。

>>> class UserForm(forms.Form):
...     username = forms.CharField(
...         max_length=255,
...         help_text="e.g., user@example.com",
...         widget=forms.TextInput(
...             attrs={"aria-describedby": "custom-description id_username_helptext"},
...         ),
...     )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>

在 Django 5.0 中變更

新增了 aria-describedby 以將 help_text 與其輸入相關聯。

在 Django 5.1 中變更

新增了 <fieldset> 的 aria-describedby 支援。

`error_messages`¶

Field.error_messages¶

error_messages 引數可讓您覆寫欄位將引發的預設訊息。傳遞一個字典，其中鍵與您要覆寫的錯誤訊息相符。例如，這是預設的錯誤訊息

>>> from django import forms
>>> generic = forms.CharField()
>>> generic.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['This field is required.']

這是自訂的錯誤訊息

>>> name = forms.CharField(error_messages={"required": "Please enter your name"})
>>> name.clean("")
Traceback (most recent call last):
  ...
ValidationError: ['Please enter your name']

在下方的「內建欄位類別」章節中，每個 Field 都定義了它所使用的錯誤訊息鍵。

`validators`¶

Field.validators¶

validators 引數允許你為此欄位提供驗證函式清單。

更多資訊請參閱驗證器文件。

`localize`¶

Field.localize¶

localize 引數啟用表單資料輸入的本地化，以及呈現的輸出。

更多資訊請參閱格式本地化文件。

`disabled`¶

Field.disabled¶

當 disabled 布林引數設定為 True 時，會使用 disabled HTML 屬性停用表單欄位，使其無法讓使用者編輯。即使使用者竄改提交至伺服器的欄位值，也會被忽略，而採用表單初始資料中的值。

`template_name`¶

Field.template_name¶

Django 5.0 新增。

當欄位使用 as_field_group() 呈現時，template_name 引數允許使用自訂範本。預設情況下，此值設定為 "django/forms/field.html"。可以透過覆寫此屬性來針對每個欄位變更，或透過覆寫預設範本來更廣泛地變更，另請參閱覆寫內建欄位範本。

檢查欄位資料是否已變更¶

`has_changed()`¶

Field.has_changed()[來源]¶

has_changed() 方法用於判斷欄位值是否與初始值不同。傳回 True 或 False。

更多資訊請參閱 Form.has_changed() 文件。

內建 `Field` 類別¶

自然地，forms 函式庫提供了一組 Field 類別，代表常見的驗證需求。此章節說明每個內建欄位。

對於每個欄位，我們描述當你未指定 widget 時所使用的預設 widget。我們也指定當你提供空值時傳回的值（請參閱上方關於 required 的章節，以了解其含義）。

`BooleanField`¶

class BooleanField(**kwargs)[來源]¶

預設 widget：CheckboxInput
空值：False
正規化為：Python True 或 False 值。
如果欄位具有 required=True，則驗證值是否為 True（例如，核取方塊已勾選）。
錯誤訊息鍵：required

注意

由於所有 Field 子類別預設都具有 required=True，因此此處的驗證條件非常重要。如果你想在表單中包含一個可以是 True 或 False 的布林值（例如，已勾選或未勾選的核取方塊），則在建立 BooleanField 時，必須記得傳入 required=False。

`CharField`¶

class CharField(**kwargs)[來源]¶

預設 widget：TextInput
空值：你所提供的 empty_value。
正規化為：一個字串。
如果提供了 max_length 和 min_length，則使用 MaxLengthValidator 和 MinLengthValidator。否則，所有輸入都有效。
錯誤訊息鍵：required、max_length、min_length

具有以下用於驗證的可選引數

max_length¶

min_length¶: 如果提供這些引數，則確保字串最多或至少為給定的長度。

strip¶: 如果 True（預設），則值將會移除開頭和結尾的空白。

empty_value¶: 用於表示「空」的值。預設為空字串。

`ChoiceField`¶

class ChoiceField(**kwargs)[來源]¶

預設 widget：Select
空值：''（空字串）
正規化為：一個字串。
驗證給定的值是否存在於選項清單中。
錯誤訊息鍵：required、invalid_choice

invalid_choice 錯誤訊息可能包含 %(value)s，它將被替換為所選的選項。

採用一個額外引數

choices[來源]¶: 可使用 2 元組的可迭代物件作為此欄位的選項、列舉型別，或是一個回傳此類可迭代物件的可呼叫物件。此參數接受與模型欄位中的 choices 參數相同的格式。請參閱模型欄位關於選項的參考文件以取得更多詳細資訊。如果參數是一個可呼叫物件，則會在每次初始化欄位的表單時以及在渲染期間進行評估。預設值為空列表。

選項類型

此欄位會將選項正規化為字串，因此如果需要其他資料類型（例如整數或布林值）的選項，請考慮改用 TypedChoiceField。

在 Django 5.0 中變更

已新增對映射的支援，以及在 choices 中直接使用列舉類型。

`DateField`¶

class DateField(**kwargs)[原始碼]¶

預設小工具：DateInput
空值：None
正規化為：Python 的 datetime.date 物件。
驗證給定的值是 datetime.date、 datetime.datetime 或以特定日期格式格式化的字串。
錯誤訊息鍵：required、 invalid

接受一個可選參數

input_formats¶: 一個格式的可迭代物件，用於嘗試將字串轉換為有效的 datetime.date 物件。

如果未提供 input_formats 參數，則預設的輸入格式取自活動地區設定格式的 DATE_INPUT_FORMATS 鍵，如果停用本地化則取自 DATE_INPUT_FORMATS。另請參閱格式本地化。

`DateTimeField`¶

class DateTimeField(**kwargs)[原始碼]¶

預設小工具：DateTimeInput
空值：None
正規化為：Python 的 datetime.datetime 物件。
驗證給定的值是 datetime.datetime、datetime.date 或以特定日期時間格式格式化的字串。
錯誤訊息鍵：required、 invalid

接受一個可選參數

input_formats¶: 一個格式的可迭代物件，用於嘗試將字串轉換為有效的 datetime.datetime 物件，此外也包含 ISO 8601 格式。

此欄位始終接受 ISO 8601 格式的日期或 parse_datetime() 可辨識的類似格式的字串。一些範例如下

'2006-10-25 14:30:59'
'2006-10-25T14:30:59'
'2006-10-25 14:30'
'2006-10-25T14:30'
'2006-10-25T14:30Z'
'2006-10-25T14:30+02:00'
'2006-10-25'

如果未提供 input_formats 參數，則預設的輸入格式取自活動地區設定格式的 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS 鍵，如果停用本地化則取自 DATETIME_INPUT_FORMATS 和 DATE_INPUT_FORMATS。另請參閱格式本地化。

`DecimalField`¶

class DecimalField(**kwargs)[原始碼]¶

預設小工具：當 Field.localize 為 False 時為 NumberInput，否則為 TextInput。
空值：None
正規化為：Python 的 decimal。
驗證給定的值是否為十進位值。如果提供 max_value 和 min_value，則使用 MaxValueValidator 和 MinValueValidator。如果提供 step_size，則使用 StepValueValidator。會忽略開頭和結尾的空白。
錯誤訊息鍵：required、invalid、max_value、min_value、max_digits、max_decimal_places、max_whole_digits、step_size。

max_value 和 min_value 錯誤訊息可能包含 %(limit_value)s，該值將被替換為適當的限制值。同樣地，max_digits、max_decimal_places 和 max_whole_digits 錯誤訊息可能包含 %(max)s。

接受五個可選參數

max_value¶

min_value¶: 這些參數控制欄位中允許的值範圍，應以 decimal.Decimal 值給出。

max_digits¶: 值中允許的最大位數（小數點前的位數加上小數點後的位數，並刪除前導零）。

decimal_places¶: 允許的最大小數位數。

step_size¶: 將有效輸入限制為 step_size 的整數倍。如果同時提供 min_value，則會將其作為偏移量添加，以確定步長是否匹配。

`DurationField`¶

class DurationField(**kwargs)[原始碼]¶

預設 widget：TextInput
空值：None
正規化為：Python 的 timedelta。
驗證給定的值是否為可轉換為 timedelta 的字串。該值必須介於 datetime.timedelta.min 和 datetime.timedelta.max 之間。
錯誤訊息鍵：required、invalid、overflow。

接受 parse_duration() 所能理解的任何格式。

`EmailField`¶

class EmailField(**kwargs)[原始碼]¶

預設 widget：EmailInput
空值：您給定的 empty_value。
正規化為：一個字串。
使用 EmailValidator，使用適度複雜的正規表示式來驗證給定的值是否為有效的電子郵件地址。
錯誤訊息鍵：required、 invalid

具有可選參數 max_length、min_length 和 empty_value，其作用與 CharField 相同。max_length 參數預設為 320（請參閱 RFC 3696 第 3 節）。

`FileField`¶

class FileField(**kwargs)[原始碼]¶

預設 widget：ClearableFileInput
空值：None
標準化為：一個 UploadedFile 物件，該物件將檔案內容和檔案名稱包裝成單一物件。
可以驗證非空的檔案資料已綁定到表單。
錯誤訊息鍵：required、invalid、missing、empty、max_length

具有用於驗證的可選參數：max_length 和 allow_empty_file。如果提供這些參數，則可以確保檔案名稱的最大長度為給定的長度，並且即使檔案內容為空，驗證也會成功。

若要深入了解 UploadedFile 物件，請參閱檔案上傳文件。

當您在表單中使用 FileField 時，還必須記住要將檔案資料綁定到表單。

max_length 錯誤是指檔案名稱的長度。在該鍵的錯誤訊息中，%(max)d 將被替換為最大檔案名稱長度，而 %(length)d 將被替換為目前的檔案名稱長度。

`FilePathField`¶

class FilePathField(**kwargs)[原始碼]¶

預設 widget：Select
空值：''（空字串）
正規化為：一個字串。
驗證所選的選項是否存在於選項清單中。
錯誤訊息鍵：required、invalid_choice

此欄位允許從特定目錄中的檔案中進行選擇。它需要五個額外參數；只有 path 是必需的

path¶: 您想要列出其內容的目錄的絕對路徑。這個目錄必須存在。

recursive¶: 如果為 False（預設值），則僅會將 path 的直接內容作為選項提供。如果為 True，則會遞迴進入目錄，並且所有子系都會列為選項。

match¶: 正規表示式模式；只有名稱符合此表達式的檔案才會被允許作為選項。

allow_files¶: 選用。可以是 True 或 False。預設值為 True。指定是否應包含指定位置中的檔案。此參數或 allow_folders 必須為 True。

allow_folders¶: 選用。可以是 True 或 False。預設值為 False。指定是否應包含指定位置中的資料夾。此參數或 allow_files 必須為 True。

`FloatField`¶

class FloatField(**kwargs)[原始碼]¶

預設小工具：當 Field.localize 為 False 時為 NumberInput，否則為 TextInput。
空值：None
標準化為：一個 Python float。
驗證給定的值是否為浮點數。如果提供了 max_value 和 min_value，則使用 MaxValueValidator 和 MinValueValidator。如果提供了 step_size，則使用 StepValueValidator。允許前導和尾隨空格，就像 Python 的 float() 函式一樣。
錯誤訊息鍵：required、invalid、max_value、min_value、step_size。

接受三個可選參數

max_value¶

min_value¶: 這些參數控制欄位中允許的值範圍。

step_size¶: 將有效輸入限制為 step_size 的整數倍。如果同時提供 min_value，則會將其作為偏移量添加，以確定步長是否匹配。

`GenericIPAddressField`¶

class GenericIPAddressField(**kwargs)[原始碼]¶

一個包含 IPv4 或 IPv6 位址的欄位。

預設 widget：TextInput
空值：''（空字串）
標準化為：一個字串。IPv6 位址會以下述方式進行標準化。
驗證給定的值是否為有效的 IP 位址。
錯誤訊息鍵：required、 invalid

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。所有字元都會轉換為小寫。

接受兩個可選參數

protocol¶: 限制有效輸入為指定的協定。可接受的值為 both (預設值)、IPv4 或 IPv6。比對時不區分大小寫。

unpack_ipv4¶: 解開 IPv4 對應的位址，例如 ::ffff:192.0.2.1。如果啟用此選項，該位址將會被解開為 192.0.2.1。預設為停用。只有在 protocol 設定為 'both' 時才能使用。

`ImageField`¶

class ImageField(**kwargs)[原始碼]¶

預設 widget：ClearableFileInput
空值：None
標準化為：一個 UploadedFile 物件，該物件將檔案內容和檔案名稱包裝成單一物件。
驗證檔案資料是否已繫結至表單。也會使用 FileExtensionValidator 來驗證 Pillow 是否支援檔案副檔名。
錯誤訊息鍵：required、invalid、missing、empty、invalid_image

使用 ImageField 需要安裝 pillow，並支援您使用的圖片格式。如果在上傳圖片時遇到 corrupt image 錯誤，通常表示 Pillow 無法理解其格式。要解決此問題，請安裝適當的程式庫並重新安裝 Pillow。

當您在表單上使用 ImageField 時，您也必須記得將檔案資料繫結至表單。

在欄位經過清理和驗證後，UploadedFile 物件將會有一個額外的 image 屬性，其中包含用來檢查檔案是否為有效圖片的 Pillow Image 實例。Pillow 會在驗證圖片後關閉底層的檔案描述符，因此雖然非圖片資料屬性（例如 format、height 和 width）可用，但存取底層圖片資料的方法（例如 getdata() 或 getpixel()）必須在重新開啟檔案後才能使用。例如

>>> from PIL import Image
>>> from django import forms
>>> from django.core.files.uploadedfile import SimpleUploadedFile
>>> class ImageForm(forms.Form):
...     img = forms.ImageField()
...
>>> file_data = {"img": SimpleUploadedFile("test.png", b"file data")}
>>> form = ImageForm({}, file_data)
# Pillow closes the underlying file descriptor.
>>> form.is_valid()
True
>>> image_field = form.cleaned_data["img"]
>>> image_field.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18>
>>> image_field.image.width
191
>>> image_field.image.height
287
>>> image_field.image.format
'PNG'
>>> image_field.image.getdata()
# Raises AttributeError: 'NoneType' object has no attribute 'seek'.
>>> image = Image.open(image_field)
>>> image.getdata()
<ImagingCore object at 0x7f5984f874b0>

此外，如果 Pillow 可以判斷圖片的內容類型，UploadedFile.content_type 將會更新為圖片的內容類型，否則將會設定為 None。

`IntegerField`¶

class IntegerField(**kwargs)[原始碼]¶

預設小工具：當 Field.localize 為 False 時為 NumberInput，否則為 TextInput。
空值：None
正規化為：一個 Python 整數。
驗證給定的值是否為整數。如果提供了 max_value 和 min_value，則會使用 MaxValueValidator 和 MinValueValidator。如果提供了 step_size，則會使用 StepValueValidator。允許前導和尾隨的空白字元，如同 Python 的 int() 函數一樣。
錯誤訊息鍵：required、invalid、max_value、min_value、step_size

max_value、min_value 和 step_size 錯誤訊息可能包含 %(limit_value)s，它將被替換為適當的限制。

接受三個可選參數進行驗證

max_value¶

min_value¶: 這些參數控制欄位中允許的值範圍。

step_size¶: 將有效輸入限制為 step_size 的整數倍。如果同時提供 min_value，則會將其作為偏移量添加，以確定步長是否匹配。

`JSONField`¶

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

一個接受 JSON 編碼資料用於 JSONField 的欄位。

預設小工具：Textarea
空值：None
正規化為：JSON 值的 Python 表示法 (通常為 dict、list 或 None)，取決於 JSONField.decoder。
驗證給定的值是否為有效的 JSON。
錯誤訊息鍵：required、 invalid

接受兩個可選參數

encoder¶

一個 json.JSONEncoder 子類別，用於序列化標準 JSON 序列化程式不支援的資料類型（例如，datetime.datetime 或 UUID）。例如，您可以使用 DjangoJSONEncoder 類別。

預設為 json.JSONEncoder。

decoder¶

一個 json.JSONDecoder 子類別，用於反序列化輸入。您的反序列化可能需要考量到您無法確定輸入類型的事實。例如，您可能會冒著返回一個實際上只是剛好與為 datetime 選擇的格式相同的字串的 datetime 的風險。

可以透過 decoder 來驗證輸入。如果在反序列化期間引發 json.JSONDecodeError，則會引發 ValidationError。

預設為 json.JSONDecoder。

注意

如果您使用 ModelForm，則會使用來自 JSONField 的 encoder 和 decoder。

使用者友善的表單

在大多數情況下，JSONField 並不是特別使用者友善。但是，這是一種格式化來自客戶端小工具的資料以便提交至伺服器的有用方式。

`MultipleChoiceField`¶

class MultipleChoiceField(**kwargs)[原始碼]¶

預設小工具：SelectMultiple
空值：[] (一個空列表)
正規化為：字串列表。
驗證給定的值列表中的每個值是否存在於選項列表中。
錯誤訊息鍵：required、invalid_choice、invalid_list

invalid_choice 錯誤訊息可能包含 %(value)s，它將被替換為所選的選項。

如同 ChoiceField，需額外接收一個必要參數 choices。

`NullBooleanField`¶

class NullBooleanField(**kwargs)[原始碼]¶

預設的 widget：NullBooleanSelect
空值：None
標準化為：Python 的 True、False 或 None 值。
不進行驗證（也就是說，它永遠不會拋出 ValidationError）。

NullBooleanField 可以與 Select 或 RadioSelect 等 widget 一起使用，只需提供 widget 的 choices 即可

NullBooleanField(
    widget=Select(
        choices=[
            ("", "Unknown"),
            (True, "Yes"),
            (False, "No"),
        ]
    )
)

`RegexField`¶

class RegexField(**kwargs)[原始碼]¶

預設 widget：TextInput
空值：您給定的 empty_value。
正規化為：一個字串。
使用 RegexValidator 來驗證給定的值是否符合特定的正規表示式。
錯誤訊息鍵：required、 invalid

接收一個必要參數

regex¶: 一個正規表示式，可以指定為字串或已編譯的正規表示式物件。

也接收 max_length、min_length、strip 和 empty_value，其作用與 CharField 中的相同。

strip¶: 預設為 False。如果啟用，則會在正規表示式驗證之前進行字串的修剪。

`SlugField`¶

class SlugField(**kwargs)[原始碼]¶

預設 widget：TextInput
空值：您給定的 empty_value。
正規化為：一個字串。
使用 validate_slug 或 validate_unicode_slug 來驗證給定的值是否僅包含字母、數字、底線和連字符號。
錯誤訊息：required、invalid

此欄位旨在用於在表單中表示模型的 SlugField。

接收兩個可選參數

allow_unicode¶: 一個布林值，指示欄位除了接受 ASCII 字母外，還接受 Unicode 字母。預設為 False。

empty_value¶: 用於表示「空」的值。預設為空字串。

`TimeField`¶

class TimeField(**kwargs)[原始碼]¶

預設的 widget：TimeInput
空值：None
標準化為：Python 的 datetime.time 物件。
驗證給定的值是否為 datetime.time 或以特定時間格式格式化的字串。
錯誤訊息鍵：required、 invalid

接受一個可選參數

input_formats¶: 一個可迭代的格式，用於嘗試將字串轉換為有效的 datetime.time 物件。

如果未提供 input_formats 參數，則預設的輸入格式取自使用中的語言環境格式 TIME_INPUT_FORMATS 鍵，如果停用本地化，則取自 TIME_INPUT_FORMATS。另請參閱格式本地化。

`TypedChoiceField`¶

class TypedChoiceField(**kwargs)[原始碼]¶

就像 ChoiceField 一樣，除了 TypedChoiceField 接收兩個額外參數 coerce 和 empty_value。

預設 widget：Select
空值：您給定的 empty_value。
標準化為：coerce 參數提供的類型的值。
驗證給定的值是否存在於選項列表中且可以強制轉換。
錯誤訊息鍵：required、invalid_choice

接收額外參數

coerce¶: 一個接收一個參數並傳回強制轉換值的函式。範例包括內建的 int、float、bool 和其他類型。預設為恆等函式。請注意，強制轉換發生在輸入驗證之後，因此有可能強制轉換為 choices 中不存在的值。

empty_value¶: 用於表示「空」的值。預設為空字串；None 是另一個常見的選擇。請注意，此值不會由 coerce 參數中給定的函式強制轉換，因此請據此選擇。

`TypedMultipleChoiceField`¶

class TypedMultipleChoiceField(**kwargs)[原始碼]¶

就像 MultipleChoiceField 一樣，除了 TypedMultipleChoiceField 接收兩個額外參數 coerce 和 empty_value。

預設小工具：SelectMultiple
空值：您給定的 empty_value
標準化為：由 coerce 參數提供的類型的值的列表。
驗證給定的值是否存在於選項列表中且可以強制轉換。
錯誤訊息鍵：required、invalid_choice

invalid_choice 錯誤訊息可能包含 %(value)s，它將被替換為所選的選項。

接收兩個額外參數 coerce 和 empty_value，如同 TypedChoiceField。

`URLField`¶

class URLField(**kwargs)[原始碼]¶

預設小部件：URLInput
空值：您給定的 empty_value。
正規化為：一個字串。
使用 URLValidator 來驗證給定的值是否為有效的 URL。
錯誤訊息鍵：required、 invalid

具有可選參數 max_length、min_length、empty_value，其作用與 CharField 相同，以及另一個參數

assume_scheme¶: Django 5.0 新增。

對於沒有 scheme 的 URL 所假設的 scheme。預設為 "http"。例如，如果 assume_scheme 為 "https"，且提供的值為 "example.com"，則正規化後的值將為 "https://example.com"。

自 5.0 版本起已棄用：assume_scheme 的預設值將在 Django 6.0 中從 "http" 變更為 "https"。設定 FORMS_URLFIELD_ASSUME_HTTPS 過渡設定為 True，即可在 Django 5.x 發行週期中選擇使用 "https"。

`UUIDField`¶

class UUIDField(**kwargs)[原始碼]¶

預設 widget：TextInput
空值：None
正規化為：一個 UUID 物件。
錯誤訊息鍵：required、 invalid

此欄位將接受任何可作為 UUID 建構函數的 hex 引數的字串格式。

稍微複雜的內建 `Field` 類別¶

`ComboField`¶

class ComboField(**kwargs)[原始碼]¶

預設 widget：TextInput
空值：''（空字串）
正規化為：一個字串。
針對作為 ComboField 引數指定的每個欄位驗證給定的值。
錯誤訊息鍵：required、 invalid

採用一個額外的必要引數

fields¶

應該用來驗證欄位值的欄位清單（按照提供的順序）。

>>> from django.forms import ComboField
>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])
>>> f.clean("test@example.com")
'test@example.com'
>>> f.clean("longemailaddress@example.com")
Traceback (most recent call last):
...
ValidationError: ['Ensure this value has at most 20 characters (it has 28).']

`MultiValueField`¶

class MultiValueField(fields=(), **kwargs)[原始碼]¶

預設 widget：TextInput
空值：''（空字串）
正規化為：子類別的 compress 方法所傳回的型別。
針對作為 MultiValueField 引數指定的每個欄位驗證給定的值。
錯誤訊息鍵：required、invalid、incomplete

彙總多個欄位的邏輯，這些欄位一起產生單一值。

此欄位為抽象欄位，必須被子類別化。與單一值欄位相反，MultiValueField 的子類別不得實作 clean()，而應實作 compress()。

採用一個額外的必要引數

fields¶: 欄位的元組，其值會被清理，然後合併為單一值。欄位的每個值都會由 fields 中對應的欄位清理 – 第一個值由第一個欄位清理，第二個值由第二個欄位清理，依此類推。清理所有欄位後，清理過的值清單會由 compress() 合併為單一值。

也會採用一些可選參數

require_all_fields¶

預設為 True，在此情況下，如果沒有為任何欄位提供值，則會引發 required 驗證錯誤。

當設定為 False 時，可以將 Field.required 屬性設定為 False，使個別欄位成為可選欄位。如果沒有為必要欄位提供值，則會引發 incomplete 驗證錯誤。

可以在 MultiValueField 子類別上定義預設的 incomplete 錯誤訊息，或者可以在每個個別欄位上定義不同的訊息。例如

from django.core.validators import RegexValidator


class PhoneField(MultiValueField):
    def __init__(self, **kwargs):
        # Define one message for all fields.
        error_messages = {
            "incomplete": "Enter a country calling code and a phone number.",
        }
        # Or define a different message for each field.
        fields = (
            CharField(
                error_messages={"incomplete": "Enter a country calling code."},
                validators=[
                    RegexValidator(r"^[0-9]+$", "Enter a valid country calling code."),
                ],
            ),
            CharField(
                error_messages={"incomplete": "Enter a phone number."},
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid phone number.")],
            ),
            CharField(
                validators=[RegexValidator(r"^[0-9]+$", "Enter a valid extension.")],
                required=False,
            ),
        )
        super().__init__(
            error_messages=error_messages,
            fields=fields,
            require_all_fields=False,
            **kwargs
        )

widget¶: 必須是 django.forms.MultiWidget 的子類別。預設值為 TextInput，在此情況下可能不太有用。

compress(data_list)[原始碼]¶

接受有效值清單，並傳回這些值的「壓縮」版本 – 以單一值表示。例如，SplitDateTimeField 是一個子類別，它將時間欄位和日期欄位合併為 datetime 物件。

此方法必須在子類別中實作。

`SplitDateTimeField`¶

class SplitDateTimeField(**kwargs)[原始碼]¶

預設小部件：SplitDateTimeWidget
空值：None
正規化為：Python 的 datetime.datetime 物件。
驗證給定的值是否為 datetime.datetime 或以特定日期時間格式格式化的字串。
錯誤訊息鍵：required、invalid、invalid_date、invalid_time

接受兩個可選參數

input_date_formats¶: 用於嘗試將字串轉換為有效 datetime.date 物件的格式列表。

如果沒有提供 input_date_formats 參數，則會使用 DateField 的預設輸入格式。

input_time_formats¶: 用於嘗試將字串轉換為有效 datetime.time 物件的格式列表。

如果沒有提供 input_time_formats 參數，則會使用 TimeField 的預設輸入格式。

處理關聯的欄位¶

有兩個欄位可用於表示模型之間的關聯：ModelChoiceField 和 ModelMultipleChoiceField。這兩個欄位都需要一個單一的 queryset 參數，該參數用於建立欄位的選項。在表單驗證時，這些欄位會將一個模型物件（在 ModelChoiceField 的情況下）或多個模型物件（在 ModelMultipleChoiceField 的情況下）放入表單的 cleaned_data 字典中。

對於更複雜的用法，您可以在宣告表單欄位時指定 queryset=None，然後在表單的 __init__() 方法中填充 queryset。

class FooMultipleChoiceForm(forms.Form):
    foo_select = forms.ModelMultipleChoiceField(queryset=None)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.fields["foo_select"].queryset = ...

ModelChoiceField 和 ModelMultipleChoiceField 都具有 iterator 屬性，該屬性指定用於在產生選項時迭代查詢集的類別。請參閱迭代關聯選項以取得詳細資訊。

`ModelChoiceField`¶

class ModelChoiceField(**kwargs)[原始碼]¶

預設 widget：Select
空值：None
正規化為：一個模型實例。
驗證給定的 ID 是否存在於查詢集中。
錯誤訊息鍵：required、invalid_choice

invalid_choice 錯誤訊息可能包含 %(value)s，它將被替換為所選的選項。

允許選擇單一模型物件，適用於表示外鍵。請注意，當項目數量增加時，ModelChoiceField 的預設小部件會變得不切實際。您應該避免將其用於超過 100 個項目。

需要單一參數

queryset¶: 從中衍生欄位選項的模型物件 QuerySet，並用於驗證使用者的選擇。它會在表單呈現時進行評估。

ModelChoiceField 也接受幾個可選參數

empty_label¶

預設情況下，ModelChoiceField 使用的 <select> 小部件會在列表頂端有一個空的選項。您可以使用 empty_label 屬性變更此標籤的文字（預設為 "---------"），或者您可以透過將 empty_label 設定為 None 來完全停用空標籤。

# A custom empty label
field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")

# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)

請注意，如果 ModelChoiceField 是必需的且具有預設初始值，或者 widget 設定為 RadioSelect 且 blank 參數為 False，則不會建立空選項（無論 empty_label 的值為何）。

to_field_name¶

此可選參數用於指定要用作欄位小部件中選項值的欄位。請確保它是模型的唯一欄位，否則選定的值可能會與多個物件匹配。預設情況下，它設定為 None，在這種情況下，將使用每個物件的主鍵。例如

# No custom to_field_name
field1 = forms.ModelChoiceField(queryset=...)

將產生

<select id="id_field1" name="field1">
<option value="obj1.pk">Object1</option>
<option value="obj2.pk">Object2</option>
...
</select>

和

# to_field_name provided
field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")

將產生

<select id="id_field2" name="field2">
<option value="obj1.name">Object1</option>
<option value="obj2.name">Object2</option>
...
</select>

blank¶: 當使用 RadioSelect 小部件時，此可選布林參數會決定是否建立空選項。預設情況下，blank 為 False，在這種情況下不會建立空選項。

ModelChoiceField 也具有屬性

iterator¶: 用於從 queryset 產生欄位選項的迭代器類別。預設情況下為 ModelChoiceIterator。

將呼叫模型的 __str__() 方法來產生物件的字串表示，以便在欄位的選項中使用。若要提供自訂表示，請子類別化 ModelChoiceField 並覆寫 label_from_instance。此方法將接收模型物件，並應傳回適合表示它的字串。例如

from django.forms import ModelChoiceField


class MyModelChoiceField(ModelChoiceField):
    def label_from_instance(self, obj):
        return "My Object #%i" % obj.id

`ModelMultipleChoiceField`¶

class ModelMultipleChoiceField(**kwargs)[原始碼]¶

預設小工具：SelectMultiple
空值：一個空的 QuerySet（self.queryset.none()）
正規化為：一個模型實例的 QuerySet。
驗證給定值清單中的每個 ID 是否存在於查詢集中。
錯誤訊息鍵：required、invalid_list、invalid_choice、invalid_pk_value

invalid_choice 訊息可能包含 %(value)s，而 invalid_pk_value 訊息可能包含 %(pk)s，這些將會被適當的值取代。

允許選擇一個或多個模型物件，適用於表示多對多關係。與 ModelChoiceField 一樣，您可以使用 label_from_instance 自訂物件表示。

需要單一參數

queryset¶: 與 ModelChoiceField.queryset 相同。

接受一個可選參數

to_field_name¶: 與 ModelChoiceField.to_field_name 相同。

ModelMultipleChoiceField 也具有屬性

iterator¶: 與 ModelChoiceField.iterator 相同。

迭代關聯選項¶

預設情況下，ModelChoiceField 和 ModelMultipleChoiceField 使用 ModelChoiceIterator 來產生它們的欄位 choices。

當進行迭代時，ModelChoiceIterator 會產生包含 ModelChoiceIteratorValue 實例的 2 元組選項，作為每個選項的第一個 value 元素。ModelChoiceIteratorValue 包裝了選項值，同時保留了對來源模型實例的引用，這可以用於自定義的 widget 實作，例如，在 <option> 元素中新增 data-* 屬性。

例如，考慮以下模型

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(decimal_places=2, max_digits=6)

    def __str__(self):
        return self.name


class Pizza(models.Model):
    topping = models.ForeignKey(Topping, on_delete=models.CASCADE)

你可以使用 Select widget 的子類別來包含 Topping.price 的值作為每個 <option> 元素的 HTML 屬性 data-price。

from django import forms


class ToppingSelect(forms.Select):
    def create_option(
        self, name, value, label, selected, index, subindex=None, attrs=None
    ):
        option = super().create_option(
            name, value, label, selected, index, subindex, attrs
        )
        if value:
            option["attrs"]["data-price"] = value.instance.price
        return option


class PizzaForm(forms.ModelForm):
    class Meta:
        model = Pizza
        fields = ["topping"]
        widgets = {"topping": ToppingSelect}

這將會將 Pizza.topping 的選取器渲染為：

<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>

對於更進階的使用，你可以將 ModelChoiceIterator 子類化，以便自定義產生的 2 元組選項。

`ModelChoiceIterator`¶

class ModelChoiceIterator(field)[原始碼]¶

這是預設指定給 ModelChoiceField 和 ModelMultipleChoiceField 的 iterator 屬性的類別。它是一個可迭代的物件，會從查詢集中產生 2 元組的選項。

需要單一參數

field¶: 要迭代並產生選項的 ModelChoiceField 或 ModelMultipleChoiceField 的實例。

ModelChoiceIterator 有以下方法：

__iter__()[原始碼]¶: 產生 2 元組選項，格式為 (value, label)，與 ChoiceField.choices 使用的格式相同。第一個 value 元素是一個 ModelChoiceIteratorValue 實例。

`ModelChoiceIteratorValue`¶

class ModelChoiceIteratorValue(value, instance)[原始碼]¶

需要兩個引數：

value¶: 選項的值。此值用於渲染 HTML <option> 元素的 value 屬性。

instance¶: 來自查詢集的模型實例。實例可以在自定義的 ChoiceWidget.create_option() 實作中存取，以調整渲染的 HTML。

ModelChoiceIteratorValue 有以下方法：

__str__()[原始碼]¶: 返回 value 作為要在 HTML 中渲染的字串。

建立自定義欄位¶

如果內建的 Field 類別不符合你的需求，你可以建立自定義的 Field 類別。要執行此操作，請建立 django.forms.Field 的子類別。它唯一的要求是實作 clean() 方法，並且其 __init__() 方法接受上述的核心引數（required、label、initial、widget、help_text）。

你也可以透過覆寫 get_bound_field() 來客製化欄位的存取方式。

表單 API

模型表單函式

返回頂部

文件

表單欄位¶

核心欄位引數¶

required¶

label¶

label_suffix¶

initial¶

widget¶

help_text¶

error_messages¶

validators¶

localize¶

disabled¶

template_name¶

檢查欄位資料是否已變更¶

has_changed()¶

內建 Field 類別¶

BooleanField¶

CharField¶

ChoiceField¶

DateField¶

DateTimeField¶

DecimalField¶

DurationField¶

EmailField¶

FileField¶

FilePathField¶

FloatField¶

GenericIPAddressField¶

ImageField¶

IntegerField¶

JSONField¶

MultipleChoiceField¶

NullBooleanField¶

RegexField¶

SlugField¶

TimeField¶

TypedChoiceField¶

TypedMultipleChoiceField¶

URLField¶

UUIDField¶

稍微複雜的內建 Field 類別¶

ComboField¶

MultiValueField¶

SplitDateTimeField¶

處理關聯的欄位¶

ModelChoiceField¶

ModelMultipleChoiceField¶

迭代關聯選項¶

ModelChoiceIterator¶

ModelChoiceIteratorValue¶

建立自定義欄位¶

額外資訊

支持 Django！

目錄

瀏覽

您在這裡

取得協助

下載

`required`¶

`label`¶

`label_suffix`¶

`initial`¶

`widget`¶

`help_text`¶

`error_messages`¶

`validators`¶

`localize`¶

`disabled`¶

`template_name`¶

`has_changed()`¶

內建 `Field` 類別¶

`BooleanField`¶

`CharField`¶

`ChoiceField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`DurationField`¶

`EmailField`¶

`FileField`¶

`FilePathField`¶

`FloatField`¶

`GenericIPAddressField`¶

`ImageField`¶

`IntegerField`¶

`JSONField`¶

`MultipleChoiceField`¶

`NullBooleanField`¶

`RegexField`¶

`SlugField`¶

`TimeField`¶

`TypedChoiceField`¶

`TypedMultipleChoiceField`¶

`URLField`¶

`UUIDField`¶

稍微複雜的內建 `Field` 類別¶

`ComboField`¶

`MultiValueField`¶

`SplitDateTimeField`¶

`ModelChoiceField`¶

`ModelMultipleChoiceField`¶

`ModelChoiceIterator`¶

`ModelChoiceIteratorValue`¶