iodine

碘

Iodine.js 是一個微型客戶端驗證函式庫。它沒有依賴性，可以單獨使用或作為框架的一部分。 Iodine 也支援可連結規則，讓您可以驗證一條（或多條）資料是否符合多個條件。

升級中

Iodine 8+ 版本進行了重大重寫，其中包含許多重大更改。因此，建議現有項目繼續使用版本 7（或更低版本），而版本 8（或更高版本）應保留給較新的項目。

安裝

將 Iodine 引入專案的最簡單方法是透過 CDN（請務必更新內部版本號）：

 < script src =" https://cdn.jsdelivr.net/npm/@caneara/[email protected]/dist/iodine.min.umd.js " defer >  script >

您也可以透過 NPM 將 Iodine 拉入您的專案：

 npm i @ caneara / iodine 

用法

Iodine 會自動加入到window命名空間中，使其可以在任何地方使用。如果您的專案不涉及編譯或導入，這是建議使用 Iodine 的方法。即使您的專案確實涉及編譯，通常也更容易使用新增至window命名空間的實例。

或者，如果您習慣使用匯入，或者您想建立自己的實例，那麼您可以像這樣匯入 Iodine：

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

基本驗證

Iodine 包含一系列驗證規則，您可以透過其關聯方法存取它們。這樣可以快速、輕鬆地檢查某個項目是整數還是日期。

Iodine 的規則以assert為前綴。因此，要檢查某個項目是否為integer ，您可以使用以下程式碼：

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assertInteger ( item_1 ) ; // true
Iodine . assertInteger ( item_2 ) ; // false

請參閱下文，了解 Iodine 包含的驗證規則的完整清單。

進階驗證

雖然檢查項目是否符合單一驗證規則可能很有用，但您通常會想要檢查項目是否符合多個規則。例如，電子郵件地址可能是必需的，必須是字串，並且必須滿足電子郵件地址正規表示式。

為了滿足這些需求，Iodine 提供「單項檢查」和「多項檢查」...

單項檢查

如果您有一個項目需要根據多個規則進行測試（例如上面描述的電子郵件地址範例），則首選此方法。若要執行“單項檢查”，請呼叫主assert方法。此方法有兩個參數。第一個是要檢查的項目。第二個是一array應按順序運行的驗證規則，例如

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assert ( item_1 , [ 'required' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' ] ) ;

如您在範例中看到的，驗證規則是使用strings表示的。若要尋找驗證規則的string表示形式，請查看現有清單。

與單獨的斷言（返回boolean ）不同， assert方法會傳回一個包含報告的object 。當該項目通過所有規則時，您將獲得：

 {
    valid : true ,
    rule  : '' ,
    error : '' ,
} ;

如果專案驗證失敗，報告將包含其未能滿足的第一條規則以及關聯的錯誤訊息：

 {
    valid : false ,
    rule  : 'integer' ,
    error : 'Value must be an integer' ,
} ;

多項檢查

當您需要根據一堆不同的驗證規則檢查多個項目時，例如提交包含多個欄位的表單時，請首選此方法。

與「單項檢查」一樣，您應該呼叫assert方法，但是對於這兩個參數，您將需要提供一個object 。第一個物件應包含要驗證的項目，而第二個物件應包含每個項目的規則，例如

 const items = {
    name     : 5 ,
    email    : '[email protected]' ,
    password : 'abcdefgh' ,
} ;

const rules = {
    name     : [ 'required' , 'string' ] ,
    email    : [ 'required' , 'email' ] ,
    password : [ 'required' ] ,
} ;

Iodine . assert ( items , rules ) ;

與「單項檢查」不同，報告略有不同。它包含一個頂級valid密鑰，可讓您輕鬆檢查是否一切都通過或失敗。然後它包含一個fields鍵，其中包含每個項目的子報告。子報告與「單項檢查」所獲得的內容相同。這是上面顯示的程式碼範例的報告：

 {
    valid  : false ,
    fields : {
        name : {
            valid : false ,
            rule  : 'string' ,
            error : 'Value must be a string' ,
        } ,
        email : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        } ,
        password : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        }
    } ,
} ; 

附加參數

有些規則需要額外的參數，例如

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assertMin ( item_1 , 5 ) ; // true
Iodine . assertMin ( item_2 , 5 ) ; // false

對於進階驗證，您可以透過將參數附加到帶有分號分隔符號的規則來提供參數，例如

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assert ( item_1 , [ 'required' , 'integer' , 'min:5' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' , 'min:5' ] ) ;

或者，如果您願意，可以將規則作為object提供，而不是用分號分隔的string ：

 Iodine . assert ( 8 , [ 'required' , 'integer' , { rule : 'min' , param : 7 } , 'max:10' ] ) ; 

可選值

對於進階驗證，您可能想要允許可選值。 Iodine 透過optional規則支持這一點：

 let item_1 = 7 ;
let item_2 = null ;
let item_3 = 'string' ;

Iodine . assert ( item_1 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_3 , [ 'optional' , 'integer' ] ) ;

重要提示：如果您希望允許可選值，那麼它必須是數組中的第一個規則。

自訂錯誤

Iodine 包含一組預設的英文錯誤訊息。但是，您可以透過setErrorMessages方法輕鬆替換它們。此方法需要一個參數，該參數是包含訊息的object 。有關範例，請參閱 Iodine 的建構子。

發生錯誤時，Iodine 會自動取代[FIELD]和[PARAM]佔位符。因此，您應該在新錯誤訊息中的適當位置插入這些佔位符，例如

 Iodine . setErrorMessages ( { same : `[FIELD] must be '[PARAM]'` } ) ;   // English
Iodine . setErrorMessages ( { same : `[FIELD] doit être '[PARAM]'` } ) ; // French

單一錯誤

在許多情況下，您不需要替換所有錯誤訊息。相反，您會想要更新一個或添加一個新的。為此，您應該呼叫setErrorMessage例如

 Iodine . setErrorMessage ( 'passwordConfirmation' , 'Does not match password' ) ;

按字段的自訂錯誤

有時，可能需要為欄位定義特定的錯誤訊息，或需要與所使用的變數名稱不同的欄位標籤。

要實現此目的，請將物件傳遞給包含規則作為屬性和自訂錯誤訊息作為值的assert方法，例如

 Iodine . assert ( value , [ 'required' ] , { 'required' : 'The "Label" must be present.' } ) ;

您也可以對多個欄位使用相同的方法，例如

 let items = {
    name : '' ,
} ;

let rules = {
    name : [ 'required' ]
} ;

let errors = {
    name : {
        required : 'The "Label" must be present.'
    }
} ;

Iodine . assert ( items , rules , errors ) ;

預設欄位名稱

由於「單一項目檢查」不支援欄位名稱，因此 Iodine 使用預設值（即「值」）。如果「Value」不合適，那麼您可以呼叫setDefaultFieldName方法並提供替代string值來代替，例如

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

請注意，您必須在呼叫assert之前呼叫setDefaultFieldName 。

可用規則

可以使用以下驗證規則：

規則	字串鍵	描述
斷言之後（日期/整數）	'後'	驗證該項目是否為給定Date或時間戳記之後的Date
斷言AfterOrEqual（日期/整數）	'之後或等於'	驗證該項目是否是晚於或等於給定Date或時間戳記的Date
斷言數組	'大批'	驗證該項目是array
斷言之前（日期/整數）	'前'	驗證該項目是否為給定Date或時間戳記之前的Date
斷言BeforeOrEqual（日期/整數）	'之前或等於'	驗證該項目的Date是否早於或等於給定Date或時間戳
斷言布林值	'布林值'	驗證該項目是true false
斷言日期	'日期'	驗證該項目是否為Date對象
斷言不同（值）	'不同的'	驗證該項目與提供的值不同（使用鬆散比較）
斷言結束（值）	‘結束’	驗證該項目是否以給定值結尾
斷言電子郵件	'電子郵件'	驗證該項目是否為有效的電子郵件地址
斷言錯誤	‘虛假’	驗證該項是否為false 、 'false' 、 0或'0'
斷言（數組）	'在'	驗證該項目是否在給定array內
斷言整數	‘整數’	驗證該項是否為integer
斷言Json	'json'	驗證該專案是可解析的 JSON 物件string
斷言最大長度（限制）	'最大長度'	驗證項目的字元長度不超過給定的限制
斷言最小長度（限制）	'最小長度'	驗證項目的字元長度是否低於給定的限制
斷言最大（限制）	'最大限度'	驗證該項目的數值不超過給定的限制
斷言最小（限制）	'分鐘'	驗證該項目的數值不低於給定的限制
斷言NotIn（數組）	'不在'	驗證該項目不在給定array內
斷言數字	'數'	驗證該項目是number還是數字string
斷言可選	'選修的'	允許可選值（僅用於多重檢查）
斷言正規表示式符合(exp)	'正規表示式匹配'	驗證該項目是否滿足給定的正規表示式
斷言必用	'必需的'	驗證該項目不為null 、 undefined或空string
斷言相同（值）	'相同的'	驗證該項目與提供的值相同（使用鬆散比較）
斷言啟動（值）	'開始於'	驗證該項目是否以給定值開頭
斷言字串	'細繩'	驗證該項目是一個string
斷言真相	“真實”	驗證該項是否為true 、 'true' 、 1或'1'
斷言網址	'網址'	驗證該項目是否為有效的 URL
斷言Uuid	'uuid'	驗證該項目是否為UUID

檢查測試以取得如何使用每個規則的範例。

自訂規則

Iodine 允許您透過rule方法新增自己的自訂驗證規則。此方法接受兩個參數。第一個是規則的名稱。第二個是 Iodine 在呼叫規則時應該執行的closure ，例如

 Iodine . rule ( 'lowerCase' , ( value ) => value === value . toLowerCase ( ) ) ;

重要提示：Iodine 會自動將規則名稱的第一個字母變成大寫，並加上前綴「assert」。因此，您應該避免自己添加前綴，例如

 Iodine . rule ( 'lowerCase' ) ;       // right
Iodine . rule ( 'assertLowerCase' ) ; // wrong

如果您的規則需要接受參數，只需將其作為第二個參數包含在closure中，例如

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;

您也可以為自訂規則新增錯誤訊息，例如

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;
Iodine . setErrorMessage ( 'equals' , "[FIELD] must be equal to '[PARAM]'" ) ; 

非同步規則

先前版本的 Iodine 支援使用async / await非同步自訂規則。此後已將其刪除，以使庫更易於維護。如果您使用非同步規則，那麼首選策略是先執行非同步邏輯，儲存結果，然後讓 Iodine 驗證它。

貢獻

感謝您考慮為 Iodine 做出貢獻。歡迎您提交包含附加規則的 PR，但是要被接受，它們必須解釋它們的作用、對他人有用，並包含適當的測試以確認它們正確工作。

拉取專案後，安裝依賴項：

npm install

運行測試

npm run test 

執照

麻省理工學院許可證 (MIT)。請參閱許可證文件以獲取更多資訊。