表單欄位

Field.clean(value)
雖然欄位類主要使用在表單類中，但你也可以直接例項化它們來使用，以便更好地瞭解它們是如何工作的。每個欄位例項都有一個clean()方法， 它接受一個引數，然後返回“清潔的”資料或者丟擲一個django.forms.ValidationError異常：

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

欄位的核心引數

每個欄位類的建構函式至少接受這些引數。有些欄位類接受額外的、欄位特有的引數，但以下引數應該總是能接受：

Field.required
預設情況下，每個欄位 類都假設必需有值，所以如果你傳遞一個空的值 —— 不管是None 還是空字串(“”) —— clean() 將引發一個ValidationError 異常。

Field.label
正如在前面“輸出表單為HTML”中解釋的，欄位預設label 是通過將欄位名中所有的下劃線轉換成空格並大寫第一個字母生成的。如果預設的標籤不合適，可以指定label。

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

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.as_p())
<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" /></p>
<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" /></p>
<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" /></p>

Field.initial
initial 引數讓你指定渲染未繫結的表單中的欄位時使用的初始值。

Field.widget
widget 引數讓你指定渲染表單時使用的Widget 類。更多資訊參見Widgets。

Field.help_text
help_text 引數讓你指定欄位的描述文字。如果提供help_text，在通過表單的便捷方法（例如，as_ul()）渲染欄位時，它將緊接著欄位顯示。

Field.error_messages
error_messages 引數讓你覆蓋欄位引發的異常中的預設資訊。傳遞的是一個字典，其鍵為你想覆蓋的錯誤資訊。

Field.validators
validators 引數讓你可以為欄位提供一個驗證函式的列表。

Field.localize
localize 引數啟用表單資料的本地化，包括輸入和輸出。

是否已經改變

Field.has_changed()
has_changed() 方法用於決定欄位的值是否從初始值發生了改變。返回True 或False。

內建欄位

class BooleanField(**kwargs)

• 預設的Widget：CheckboxInput
• 空值：False
• 規範化為：Python 的True 或 False。
• 如果欄位帶有required=True，驗證值是否為True（例如複選框被勾上）。
• 錯誤資訊的鍵：required

class CharField(**kwargs)

• 預設的Widget：TextInput
• 空值：’ ‘（一個空字串）
• 規範化為：一個Unicode 物件。
• 如果提供，驗證max_length 或min_length。 否則，所有的輸入都是合法的。
• 錯誤資訊的鍵：required, max_length, min_length

可選引數：max_length, min_length

class ChoiceField(**kwargs)

• 預設的Widget：Select
• 空值：”（一個空字串）
• 規範化為：一個Unicode 物件。
• 驗證給定的值在選項列表中存在。
• 錯誤資訊的鍵：required, invalid_choice

可選引數：choices

class TypedChoiceField(**kwargs)

• 預設的Widget：Select
• 空值：empty_value
• 規範化為：coerce 引數型別的值。
• 驗證給定的值在選項列表中存在並且可以被強制轉換。
• 錯誤資訊的鍵：required, invalid_choice

可選引數：coerce，empty_value

class DateField(**kwargs)

• 預設的Widget：DateInput
• 空值：None
• 規範化為：一個Python datetime.date 物件。
• 驗證給出的值是一個datetime.date、datetime.datetime 或指定日期格式的字串。
• 錯誤資訊的鍵：required, invalid

可選引數：input_formats

class DateTimeField(**kwargs)

• 預設的Widget：DateTimeInput
• 空值：None
• 規範化為：一個Python datetime.datetime 物件。
• 驗證給出的值是一個datetime.date、datetime.datetime 或指定日期格式的字串。
• 錯誤資訊的鍵：required, invalid

可選引數：input_formats

class DecimalField(**kwargs)

• 預設的Widget：當Field.localize 是False 時為NumberInput，否則為TextInput。
• 空值：None
• 規範化為：一個Python decimal。
• 驗證給定的值為一個十進位制數。忽略前導和尾隨的空白。
• 錯誤資訊的鍵：required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits

四個可選的引數：max_value,min_value,max_digits,decimal_places

class DurationField(**kwargs)

• 預設的Widget：TextInput
• 空值：None
• 規範化為：一個Python timedelta。
• 驗證給出的值是一個字串，而可以給轉換為timedelta。
• 錯誤資訊的鍵：required, invalid.

class EmailField(**kwargs)

• 預設的Widget：EmailInput
• 空值：”（一個空字串）
• 規範化為：一個Unicode 物件。
• 驗證給出的值是一個合法的郵件地址，使用一個適度複雜的正則表示式。
• 錯誤資訊的鍵：required, invalid

class FileField(**kwargs)

• 預設的Widget：ClearableFileInput
• 空值：None
• 規範化為：一個UploadedFile 物件，它封裝檔案內容和檔名為一個單獨的物件。
• 可以驗證非空的檔案資料已經繫結到表單。
• 錯誤資訊的鍵：required, invalid, missing, empty, max_length

class FilePathField(**kwargs)

• 預設的Widget：Select
• 空值：None
• 規範化為：一個Unicode 物件。
• 驗證選擇的選項在選項列表中存在。
• 錯誤資訊的鍵：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。

class FloatField(**kwargs)

• 預設的Widget：當 Field.localize 是False 時為NumberInput，否則為TextInput。
• 空值：None
• 規範化為：一個Float 物件。
• 驗證給出的值是一個浮點數。和Python 的float() 函式一樣，允許前導和尾隨的空白符。
• 錯誤資訊的鍵：required, invalid, max_value, min_value

class ImageField(**kwargs)

• 預設的Widget：ClearableFileInput
• 空值：None
• 規範化為: An UploadedFile object that wraps the file content and file name into a single object.
• 驗證檔案資料已繫結到表單，並且該檔案具有Pillow理解的影象格式。
• 錯誤資訊的鍵：required, invalid, missing, empty, invalid_image

class IntegerField(**kwargs)

• 預設的Widget：當Field.localize 是False 時為NumberInput，否則為TextInput。
• 空值：None
• 規範化為：一個Python 整數或長整數。
• 驗證給定值是一個整數。允許前導和尾隨空格，如Python的int()函式。
• 錯誤資訊的鍵：required, invalid, max_value, min_value

可選引數：max_value，min_value

class GenericIPAddressField(**kwargs)
包含IPv4或IPv6地址的欄位。

• 預設的Widget：TextInput
• 空值：”（一個空字串）
• 規範化為：一個Unicode 物件。 IPv6地址如下所述進行歸一化。
• 驗證給定值是有效的IP地址。
• 錯誤資訊的鍵：required, invalid

可選引數：protocol，unpack_ipv4

class MultipleChoiceField(**kwargs)

• 預設的Widget：SelectMultiple
• 空值：[]（一個空列表）
• 規範化為：一個Unicode 物件列表。
• 驗證給定值列表中的每個值都存在於選擇列表中。
• 錯誤資訊的鍵：required, invalid_choice, invalid_list

class TypedMultipleChoiceField(**kwargs)
就像MultipleChoiceField，除了TypedMultipleChoiceField需要兩個額外的引數，coerce和empty_value。

• 預設的Widget：SelectMultiple
• 空值：empty_value
• 規範化為：coerce引數提供的型別值列表。
• 驗證給定值存在於選項列表中並且可以強制。
• 錯誤資訊的鍵：required, invalid_choice

class NullBooleanField(**kwargs)

• 預設的Widget：NullBooleanSelect
• 空值：None
• 規範化為：一個Python True, False 或None 值。
• 不驗證任何內容（即，它從不引發ValidationError）。

class RegexField(**kwargs)

• 預設的Widget：TextInput
• 空值：”（一個空字串）
• 規範化為：一個Unicode物件
• 驗證給定值與某個正則表示式匹配。
• 錯誤資訊的鍵：required, invalid

class SlugField(**kwargs)

• 預設的Widget：TextInput
• 空值：None
• 規範化為：一個Python 的datetime.time 物件。
• 驗證給定值是datetime.time或以特定時間格式格式化的字串。
• 錯誤資訊的鍵：required, invalid

class TimeField(**kwargs)

• 預設的Widget：TextInput
• 空值：None
• 規範化為：一個Python 的datetime.time 物件。
• 驗證給定值是datetime.time或以特定時間格式格式化的字串。
• 錯誤資訊的鍵：required, invalid

class URLField(**kwargs)

• 預設的Widget：URLInput
• 空值：”（一個空字串）
• 規範化為：一個Unicode 物件。
• 驗證給定值是有效的URL。
• 錯誤資訊的鍵：required, invalid

class UUIDField(**kwargs)

• 預設的Widget：TextInput
• 空值：”（一個空字串）
• 規範化為：一個UUID 物件。
• 錯誤資訊的鍵：required, invalid

複雜點的內建Field類

class ComboField(**kwargs)

• 預設的Widget：TextInput
• 空值：”（一個空字串）
• 規範化為：一個Unicode 物件。
• 根據指定為ComboField的引數的每個欄位驗證給定值。
• 錯誤資訊的鍵：required, invalid

class MultiValueField(fields=(), **kwargs)

• 預設的Widget：TextInput
• 空值：”（一個空字串）
• 規範化為：子類的compress方法返回的型別。
• 針對指定為MultiValueField的引數的每個欄位驗證給定值。
• 錯誤資訊的鍵：required, invalid, incomplete

class SplitDateTimeField(**kwargs)

• 預設的Widget：SplitDateTimeWidget
• 空值：None
• 規範化為：一個Python datetime.datetime 物件。
• 驗證給定的值是datetime.datetime或以特定日期時間格式格式化的字串。
• 錯誤資訊的鍵：required, invalid, invalid_date, invalid_time

處理關係的欄位

兩個欄位可用於表示模型之間的關係：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(FooMultipleChoiceForm, self).__init__(*args, **kwargs)
        self.fields['foo_select'].queryset = ...

class ModelChoiceField(**kwargs)

• 預設的Widget：Select
• 空值：None
• 規範化為：一個模型例項。
• 驗證給定的id存在於查詢集中。
• 錯誤資訊的鍵：required, invalid_choice

class ModelMultipleChoiceField(**kwargs)

• 預設的Widget：SelectMultiple
• 空值：QuerySet (self.queryset.none())
• 規範化為： 模型例項的一個QuerySet。
• 驗證在給定的值列表中的每個id存在於查詢集中。
• 錯誤資訊的鍵：required, list, invalid_choice, invalid_pk_value

建立自定義的欄位

如果內建的欄位不能滿足你的需求，你可以很容易地建立自定義的欄位。你需要建立django.forms.Field 的一個子類。它只要求實現一個clean() 方法和接收上面核心引數的init() 方法(required, label, initial, widget, help_text)。