驗證器

撰寫驗證器

驗證器是一個可呼叫的物件，它接受一個值，如果該值不符合某些條件，則會引發 ValidationError。驗證器可用於在不同類型的欄位之間重複使用驗證邏輯。

例如，這是一個只允許偶數的驗證器

from django.core.exceptions import ValidationError
from django.utils.translation import gettext_lazy as _


def validate_even(value):
    if value % 2 != 0:
        raise ValidationError(
            _("%(value)s is not an even number"),
            params={"value": value},
        )

您可以透過欄位的 validators 引數將其加入模型欄位

from django.db import models


class MyModel(models.Model):
    even_field = models.IntegerField(validators=[validate_even])

由於值在執行驗證器之前會轉換為 Python，因此您甚至可以在表單中使用相同的驗證器

from django import forms


class MyForm(forms.Form):
    even_field = forms.IntegerField(validators=[validate_even])

您也可以使用具有 __call__() 方法的類別來建立更複雜或可配置的驗證器。例如，RegexValidator 就使用了這種技術。如果在 validators 模型欄位選項中使用基於類別的驗證器，您應該透過新增 deconstruct() 和 __eq__() 方法來確保它可被遷移框架序列化。

驗證器的執行方式

如需有關驗證器如何在表單中執行的詳細資訊，請參閱表單驗證；如需驗證器如何在模型中執行的詳細資訊，請參閱驗證物件。請注意，當您儲存模型時，驗證器不會自動執行，但是如果您正在使用 ModelForm，它會在您表單中包含的任何欄位上執行您的驗證器。如需有關模型驗證如何與表單互動的資訊，請參閱 ModelForm 文件。

內建驗證器

django.core.validators 模組包含一組可呼叫的驗證器，可用於模型和表單欄位。它們在內部使用，但也可用於您自己的欄位。它們可以與自訂的 field.clean() 方法一起使用，也可以取代這些方法。

RegexValidator

class RegexValidator(regex=None, message=None, code=None, inverse_match=None, flags=0)[原始碼]
參數：

  • regex – 如果不是 None，則會覆寫 regex。可以是正規表示式字串或預先編譯的正規表示式。

  • message – 如果不是 None，則會覆寫 message。

  • code – 如果不是 None，則會覆寫 code。

  • inverse_match – 如果不是 None，則會覆寫 inverse_match。

  • flags – 如果不是 None，則會覆寫 flags。在這種情況下，regex 必須是正規表示式字串，否則會引發 TypeError。

RegexValidator 使用 re.search() 在提供的 value 中搜尋指定的正規表示式。預設情況下，如果未找到符合的項目，則會引發具有 message 和 code 的 ValidationError。您可以將 inverse_match 設定為 True 來反轉其行為，在這種情況下，當找到符合的項目時，會引發 ValidationError。

regex

使用 re.search() 在提供的 value 中搜尋的正規表示式模式。這可以是字串或使用 re.compile() 建立的預先編譯的正規表示式。預設為空字串，這會在每個可能的 value 中找到。

message

如果驗證失敗，ValidationError 使用的錯誤訊息。預設為 "輸入有效的值"。

code

如果驗證失敗，ValidationError 使用的錯誤代碼。預設為 "無效"。

inverse_match

regex 的比對模式。預設為 False。

flags

編譯正規表示式字串 regex 時使用的regex 旗標。如果 regex 是一個預先編譯的正規表示式，且 flags 被覆寫，則會引發 TypeError。預設值為 0。

EmailValidator

class EmailValidator(message=None, code=None, allowlist=None)[原始碼]
參數：

  • message – 如果不是 None，則會覆寫 message。

  • code – 如果不是 None，則會覆寫 code。

  • allowlist – 如果不是 None，則會覆寫 allowlist。

EmailValidator 確保值看起來像電子郵件，如果不是，則會引發帶有 message 和 code 的 ValidationError。長度超過 320 個字元的值一律被視為無效。

message

如果驗證失敗，ValidationError 使用的錯誤訊息。預設值為 "Enter a valid email address" (請輸入有效的電子郵件地址)。

code

如果驗證失敗，ValidationError 使用的錯誤代碼。預設為 "無效"。

allowlist

電子郵件網域的允許清單。預設情況下，會使用正規表示式 ( domain_regex 屬性) 來驗證 @ 符號後面的任何內容。但是，如果該字串出現在 allowlist 中，則會略過此驗證。如果未提供，則預設的 allowlist 為 ['localhost']。其他不包含點的網域將無法通過驗證，因此您需要根據需要將它們新增至 allowlist。

DomainNameValidator

Django 5.1 新增。
class DomainNameValidator(accept_idna=True, message=None, code=None)[原始碼]

一個 RegexValidator 子類別，可確保值看起來像網域名稱。長度超過 255 個字元的值一律被視為無效。IP 位址不被接受為有效的網域名稱。

除了其父類別 RegexValidator 的可選引數之外，DomainNameValidator 還接受一個額外的可選屬性

accept_idna

決定是否接受國際化網域名稱，即包含非 ASCII 字元的網域名稱。預設值為 True。

URLValidator

class URLValidator(schemes=None, regex=None, message=None, code=None)[原始碼]

一個 RegexValidator 子類別，可確保值看起來像 URL，如果不是，則會引發錯誤碼 'invalid'。長度超過 max_length 個字元的值一律被視為無效。

迴路位址和保留 IP 空間被視為有效。文字 IPv6 位址 (RFC 3986 第 3.2.2 節) 和 Unicode 網域都支援。

除了其父類別 RegexValidator 的可選引數之外，URLValidator 還接受一個額外的可選屬性

schemes

要驗證的 URL/URI 方案清單。如果未提供，則預設清單為 ['http', 'https', 'ftp', 'ftps']。作為參考，IANA 網站提供了有效 URI 方案的完整清單。

警告

即使提供了 file 方案，以 file:/// 開頭的值也不會通過驗證。有效值必須包含主機。

max_length

可以視為有效的最大值長度。預設值為 2048 個字元。

validate_email

validate_email

沒有任何自訂設定的 EmailValidator 實例。

validate_domain_name

Django 5.1 新增。
validate_domain_name

沒有任何自訂設定的 DomainNameValidator 實例。

validate_slug

validate_slug

一個 RegexValidator 實例，確保值僅由字母、數字、底線或連字符組成。

validate_unicode_slug

validate_unicode_slug

一個 RegexValidator 實例，確保值僅由 Unicode 字母、數字、底線或連字符組成。

validate_ipv4_address

validate_ipv4_address[原始碼]

一個 RegexValidator 實例，確保值看起來像一個 IPv4 位址。

validate_ipv6_address

validate_ipv6_address[原始碼]

使用 django.utils.ipv6 來檢查 IPv6 位址的有效性。

validate_ipv46_address

validate_ipv46_address[原始碼]

同時使用 validate_ipv4_address 和 validate_ipv6_address 來確保值是有效的 IPv4 或 IPv6 位址。

validate_comma_separated_integer_list

validate_comma_separated_integer_list

一個 RegexValidator 實例，確保值是以逗號分隔的整數列表。

int_list_validator

int_list_validator(sep=',', message=None, code='invalid', allow_negative=False)[原始碼]

返回一個 RegexValidator 實例，確保字串由 sep 分隔的整數組成。當 allow_negative 為 True 時，允許負整數。

MaxValueValidator

class MaxValueValidator(limit_value, message=None)[原始碼]

如果 value 大於 limit_value（可能是可呼叫的），則會引發程式碼為 'max_value' 的 ValidationError 異常。

MinValueValidator

class MinValueValidator(limit_value, message=None)[原始碼]

如果 value 小於 limit_value（可能是可呼叫的），則會引發程式碼為 'min_value' 的 ValidationError 異常。

MaxLengthValidator

class MaxLengthValidator(limit_value, message=None)[原始碼]

如果 value 的長度大於 limit_value（可能是可呼叫的），則會引發程式碼為 'max_length' 的 ValidationError 異常。

MinLengthValidator

class MinLengthValidator(limit_value, message=None)[原始碼]

如果 value 的長度小於 limit_value（可能是可呼叫的），則會引發程式碼為 'min_length' 的 ValidationError 異常。

DecimalValidator

class DecimalValidator(max_digits, decimal_places)[原始碼]

引發帶有以下程式碼的 ValidationError 異常

  • 如果位數大於 max_digits，則為 'max_digits'。

  • 如果小數位數大於 decimal_places，則為 'max_decimal_places'。

  • 如果整數位數大於 max_digits 與 decimal_places 之間的差值，則為 'max_whole_digits'。

FileExtensionValidator

class FileExtensionValidator(allowed_extensions, message, code)[原始碼]

如果 value.name ( value 為 File) 的副檔名在 allowed_extensions 中找不到，則會引發程式碼為 'invalid_extension' 的 ValidationError 異常。副檔名會與 allowed_extensions 進行大小寫不敏感的比較。

警告

不要依賴檔案副檔名的驗證來確定檔案的類型。無論它們包含什麼數據，都可以重新命名檔案以具有任何副檔名。

validate_image_file_extension

validate_image_file_extension[原始碼]

使用 Pillow 來確保 value.name ( value 為 File) 具有有效的影像副檔名。

ProhibitNullCharactersValidator

class ProhibitNullCharactersValidator(message=None, code=None)[原始碼]

如果 str(value) 包含一個或多個空字元 ('\x00')，則會引發 ValidationError。

參數：

  • message – 如果不是 None，則會覆寫 message。

  • code – 如果不是 None，則會覆寫 code。

message

如果驗證失敗，ValidationError 使用的錯誤訊息。預設為 "Null characters are not allowed." (不允許空字元)。

code

如果驗證失敗，ValidationError 使用的錯誤代碼。預設為 "null_characters_not_allowed" (不允許空字元)。

StepValueValidator

class StepValueValidator(limit_value, message=None, offset=None)[原始碼]

如果 value 不是 limit_value 的整數倍數（可以是浮點數、整數或十進位值，或是可呼叫的物件），則會引發代碼為 'step_size' 的 ValidationError。當設定 offset 時，驗證會針對 limit_value 加上 offset 進行。例如，對於 StepValueValidator(3, offset=1.4)，有效的值包括 1.4、4.4、7.4、10.4 等。

在 Django 5.0 中變更

新增了 offset 參數。

Django 工具
內建視圖
返回頂部