伽莉蝶忒是一個輕量、簡單且容易上手的 JavaScript 資料表單驗證工具,毋須與 DOM 做綁定,單純作為檢驗資料的工具。
伽莉蝶忒是開發給 Webpack 或是 Node.js 所使用,倘若要用在瀏覽器上的話,瀏覽器則需要支援 ES6 的 import
和 export
。
import { validate } from 'jalidator'
與先前敘述的相同,這是個表單驗證工具,這意味著你需要手動配置規則,令人放心的是因為伽莉蝶忒並不是基於 DOM 的綁定或是 HTML5 的 Attributes。因此你可以將規則獨立成一個檔案或是分開整理,這將令你在未來的管理和擴展上更得心應手。
一個最基本的規則範例如下:
var rules =
{
register:
{
username:
{
minLength: 8,
maxLength: 80,
required : true
},
email:
{
type : email,
required: true
},
// ...
}
}
伽莉蝶忒支援了數個基本的驗證規則,你也可以自訂驗證函式。
required, //(布林值)必填欄位
nullable, //(布林值)可否為 `null` 值
min, //(數值)最小數字
max, //(數值)最大數字
minLength, //(數值)字串最小長度
maxLength, //(數值)字串最長長度
pattern, //(字串)RegExp 表達式
sameAs, //(字串)與欄位重複
type //(字串)特殊驗證種類
- email // 電子郵件地址
- url // 網址類型
- ip // IPv4 或 IPv6 地址
- ipv4 // IPv4 地址
- ipv6 // IPv6 地址
幾個基本規則你應該知道:
-
當
required
與nullable
在一起時,欄位要就是非空值,不然就是null
。 -
sameAs
的用法是對照另一個欄位,假設你設定sameAs
為password
,那麼這將會對比data.password
。
伽莉蝶忒允許你自訂單個或是多個自訂驗證器,當你只有一個驗證器的時候,你只需要傳入驗證函式給 custom
即可,順帶注意的是,自訂驗證器將會有一個 val
的參數,你可以透過這個參數在自訂驗證器中使用欲驗證的資料。
username:
{
custom: (val) => val === "Wow"
}
倘若你有多個驗證器,你可以傳入陣列,請注意,這些驗證器都必須通過才算合格。
username:
{
custom:
[
(val) => val < 20,
(val) => val > 10
]
}
驗證對伽莉蝶忒來說不是難事,一但規則設定好之後你就可以直接透過 validate
並傳入一個規則像這樣使用:
validation = validate(rule.login, {username: 'Yami', password: 'yami888'})
像你看到的一樣,第一個參數是欲使用的規則,第二個則是資料物件,更有趣的在稍後的回傳內容,這個稍後會提及到。
有些時候你會先在網頁佈局上透過像是 v-show="validation.password.invalid"
來在稍後表單錯誤時呈現錯誤訊息,但是因為表單還尚未驗證,所以也就沒有錯誤訊息可言,當然,也就沒有所謂的 validation.password
因為一切都還沒有被執行,預料到某些框架(如:Vue.js)有可能會為此抱怨 Cannot read property 'invalid' of ...
,為此,你可以事先初始化一個鷹架(意即:空的驗證資料),這個空的資料跟稍後驗證所回傳的資料近乎一模一樣,不過不會顯示任何錯誤罷了,但卻可以對付並解決錯誤問題。
這做法很簡單,第二個參數設為 false
,第三個參數設為 true
即可。
validation = validate(rule.login, false, true)
伽莉蝶忒所回傳的資訊十分完整,除了驗證結果,還有驗證規則(方便你在網頁上顯示規則,如字數應小於多少⋯⋯等),該資訊是一個物件,先舉例,稍後將會詳細說明其個別用途。
validation = validate(rule.login, {username: 'Yami', password: 'yami888'})
console.log(validation)
則會回傳一個這樣的物件,要注意的是驗證結果在錯誤的時候會是 true
,舉例來說:倘若 username
欄位是空的,那麼 username.required
則會是 true
。如果你覺得這樣過於麻煩,你可以直接使用 username.valid
,這會在 username
合格的時候返回 true
,反之,另一個 username.invalid
會在不合格的時候返回 true
。
{
// 總體的驗證結果
valid : true,
invalid : false,
// 資料 username 的驗證結果
username:
{
valid : true,
invalid : false,
info : { ... } // username 的規則
breakpoint: { ... } // 中繼點,稍後說明
min : false,
max : false,
minLength : false,
maxLength : false,
pattern : false,
required : false,
type : false,
sameAs : false
},
// 資料 password 的驗證結果
password:
{
// ...
你可以看到上述範例中有個 username.info
,每個驗證結果都會有一個 info
物件,這會帶有你先前在規則中設置的資料,方便你能夠用在其他地方,舉例來說:
username:
{
info:
{
minLength: 8,
maxLength: 80,
required : true
}
// ...
}
然後你就可以像這樣在網頁上呼叫你的規則出來使用:
span(v-show="validation.username.invalid")
| 帳號最短是 {{ validation.username.info.minLength }} 個字,
| 最長 {{ validation.username.info.maxLength }} 個字。
你就不必手動在網頁上重新打一次規則,因為你可以直接引用你先前配置的規則,你可能會好奇,你還沒有驗證表單,這些資料要從哪裡來?還記得我們提到的「鷹架」嗎?不妨往回看看?
在剛才的範例中你可以看到 username.breakpoint
,中繼點中包含的內容跟回傳內容是一樣地:
{
valid : true,
invalid : false,
min : false,
max : false,
minLength : false,
maxLength : false,
pattern : false,
required : false,
type : false,
sameAs : false
}
那麼中繼點到底是做什麼的呢?中繼點只會出現在第一個錯誤欄位,而其他的錯誤欄位中繼點將會是一個空白的 {}
物件,如果你還不明白,在這裡稍微說明,假設我們有三個錯誤的欄位(意即:皆無通過驗證),中繼點只會出現在最先錯誤的欄位。
error <-- 這裡會有中繼點
error <-- 這裡的中繼點是空物件:{}
error <-- 這裡的中繼點是空物件:{}
但是如果第一個欄位是成功的,那麼中繼點則會順移到下一個錯誤的欄位。
success
error <-- 這裡會有中繼點
error <-- 這裡的中繼點是空物件:{}
這個用途是在有些時候你會希望循序的個別處理錯誤,而不希望錯誤一次全部跳出來,通常來說你可以使用 if ... elseif
來處理這個問題,但像是 Vue.js 目前還沒有 elseif
的功能,導致你需要這樣:
span(v-show="validation.username.invalid")
| 帳號錯誤
span(v-show="validation.username.valid && validation.password.invalid")
| 密碼錯誤
倘若你使用中繼點,就可以像這樣縮短條件式:
span(v-show="validation.username.breakpoint.invalid")
| 帳號錯誤
span(v-show="validation.password.breakpoint.invalid")
| 密碼錯誤
這部分是開發者的筆記,使用者可以自行略過。
username :
{
type: 'email',
min: 2,
max: 30,
minLength: 30,
maxLength: 50,
pattern: '/xx/',
custom: (val) =>
{
},
custom: [() => {}, () => {}],
sameAs: 'password',
date:
{
// leap year
direction: 'future',
month: 'month',
day: 'day'
},
}
required: '!username'
required: 'password'