iodine

ไอโอดีน

Iodine.js เป็นไลบรารีการตรวจสอบฝั่งไคลเอ็นต์ขนาดเล็ก ไม่มีการพึ่งพาและสามารถนำมาใช้แบบแยกหรือเป็นส่วนหนึ่งของกรอบงานได้ ไอโอดีนยังรองรับกฎแบบลูกโซ่ ซึ่งช่วยให้คุณตรวจสอบได้ว่าข้อมูลชิ้นหนึ่งเป็นไปตามเกณฑ์หลายข้อหรือไม่

กำลังอัปเกรด

ไอโอดีนเวอร์ชัน 8+ เกี่ยวข้องกับการเขียนใหม่ครั้งใหญ่โดยมีการเปลี่ยนแปลงครั้งใหญ่มากมาย ดังนั้นจึงขอแนะนำให้โปรเจ็กต์ที่มีอยู่ยังคงใช้เวอร์ชัน 7 (หรือต่ำกว่า) ต่อไป ในขณะที่เวอร์ชัน 8 (หรือสูงกว่า) ควรสงวนไว้สำหรับโปรเจ็กต์ใหม่

การติดตั้ง

วิธีที่ง่ายที่สุดในการดึงไอโอดีนเข้าสู่โปรเจ็กต์ของคุณคือผ่าน CDN (อย่าลืมอัปเดตหมายเลขบิลด์):

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

คุณยังสามารถดึงไอโอดีนเข้าสู่โปรเจ็กต์ของคุณผ่าน NPM:

 npm i @ caneara / iodine 

การใช้งาน

ไอโอดีนจะถูกเพิ่มเข้าไปในเนมสเปซของ window โดยอัตโนมัติ ทำให้สามารถใช้ได้ทุกที่ นี่เป็นวิธีที่แนะนำในการใช้ไอโอดีน หากโปรเจ็กต์ของคุณไม่เกี่ยวข้องกับการคอมไพล์หรือนำเข้า แม้ว่าโปรเจ็กต์ของคุณเกี่ยวข้องกับการคอมไพล์ แต่มักจะง่ายกว่าถ้าใช้อินสแตนซ์ที่เพิ่มในเนมสเปซ window

หรือคุณสามารถนำเข้าไอโอดีนได้ดังนี้:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

การตรวจสอบขั้นพื้นฐาน

ไอโอดีนมีกฎการตรวจสอบมากมายที่คุณสามารถเข้าถึงได้ผ่านวิธีการที่เกี่ยวข้อง ซึ่งช่วยให้ตรวจสอบได้ง่ายและรวดเร็วว่ารายการนั้นเป็นจำนวนเต็มหรือวันที่

กฎของไอโอดีนนำหน้าด้วย assert ดังนั้น เพื่อตรวจสอบว่ารายการนั้นเป็น integer หรือไม่ คุณจะต้องใช้โค้ดต่อไปนี้:

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

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

ดูรายการกฎการตรวจสอบความถูกต้องของไอโอดีนทั้งหมดด้านล่าง

การตรวจสอบขั้นสูง

แม้ว่าการตรวจสอบว่ารายการสอดคล้องกับกฎการตรวจสอบแต่ละรายการจะมีประโยชน์หรือไม่ แต่คุณมักจะต้องการตรวจสอบว่ารายการนั้นเป็นไปตามกฎหลายข้อหรือไม่ ตัวอย่างเช่น อาจจำเป็นต้องมีที่อยู่อีเมล ต้องเป็นสตริง และต้องเป็นไปตามนิพจน์ทั่วไปของที่อยู่อีเมล

เพื่อตอบสนองความต้องการเหล่านี้ ไอโอดีนเสนอ 'การตรวจสอบสินค้ารายการเดียว' และ 'การตรวจสอบสินค้าหลายรายการ'...

การตรวจสอบรายการเดียว

วิธีนี้เป็นวิธีที่แนะนำหากคุณมีหนึ่งรายการที่คุณต้องทดสอบกับกฎหลายข้อ (เช่นตัวอย่างที่อยู่อีเมลที่อธิบายไว้ข้างต้น) หากต้องการดำเนินการ 'ตรวจสอบรายการเดียว' ให้เรียกใช้วิธี 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' ] ) ; 

ค่าที่ไม่บังคับ

สำหรับการตรวจสอบขั้นสูง คุณอาจต้องการอนุญาตให้ใช้ค่าที่ไม่บังคับ ไอโอดีนสนับสนุนสิ่งนี้ด้วยกฎ 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' ] ) ;

สิ่งสำคัญ : หากคุณต้องการอนุญาตให้ใช้ค่าเสริม จะต้องเป็นกฎข้อแรกในอาร์เรย์

ข้อผิดพลาดที่กำหนดเอง

ไอโอดีนมีชุดข้อความแสดงข้อผิดพลาดเริ่มต้นสำหรับภาษาอังกฤษ อย่างไรก็ตาม คุณสามารถแทนที่ได้อย่างง่ายดายด้วยเมธอด setErrorMessages วิธีการนี้ต้องใช้พารามิเตอร์ตัวเดียว ซึ่งเป็น object ที่มีข้อความ ดูตัวสร้างของไอโอดีนเป็นตัวอย่าง

ไอโอดีนจะแทนที่ตัวยึดตำแหน่ง [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 ) ;

ชื่อฟิลด์เริ่มต้น

เนื่องจาก 'การตรวจสอบรายการเดียว' ไม่รองรับชื่อฟิลด์ ไอโอดีนจึงใช้ค่าเริ่มต้นแทน (ซึ่งก็คือ 'ค่า') หาก 'ค่า' ไม่เหมาะสม คุณสามารถเรียกใช้เมธอด setDefaultFieldName และระบุค่า string อื่นเพื่อใช้แทน เช่น

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

โปรดทราบว่าคุณต้องเรียก setDefaultFieldName ก่อนที่จะเรียก assert

กฎที่มีอยู่

มีกฎการตรวจสอบต่อไปนี้:

กฎ	คีย์สตริง	คำอธิบาย
assertAfter (วันที่/จำนวนเต็ม)	'หลังจาก'	ตรวจสอบว่ารายการนั้นเป็น Date หลังจาก Date หรือการประทับเวลาที่กำหนด
assertAfterOrEqual (วันที่/จำนวนเต็ม)	'หลังจากหรือเท่ากับ'	ตรวจสอบว่ารายการนั้นเป็น Date ที่อยู่หลังหรือเท่ากับ Date หรือการประทับเวลาที่กำหนด
assertArray	'อาร์เรย์'	ตรวจสอบว่ารายการนั้นเป็น array
assertBefore (วันที่/จำนวนเต็ม)	'ก่อน'	ตรวจสอบว่ารายการนั้นเป็น Date ก่อน Date หรือการประทับเวลาที่กำหนด
assertBeforeOrEqual (วันที่/จำนวนเต็ม)	'ก่อนหรือเท่ากับ'	ตรวจสอบว่ารายการนั้นเป็น Date ที่ก่อนหรือเท่ากับ Date หรือการประทับเวลาที่กำหนด
ยืนยันบูลีน	'บูลีน'	ตรวจสอบว่ารายการเป็น true หรือ false
ยืนยันวันที่	'วันที่'	ตรวจสอบว่ารายการนั้นเป็นวัตถุ Date
assertDifferent (ค่า)	'แตกต่าง'	ตรวจสอบว่ารายการแตกต่างจากค่าที่ให้มา (ใช้การเปรียบเทียบแบบหลวม)
assertEnds(ค่า)	'สิ้นสุด'	ตรวจสอบว่ารายการลงท้ายด้วยค่าที่กำหนด
ยืนยันอีเมล	'อีเมล'	ตรวจสอบว่ารายการนั้นเป็นที่อยู่อีเมลที่ถูกต้อง
ยืนยันเป็นเท็จ	'เท็จ'	ตรวจสอบว่ารายการนั้นเป็น false , 'false' , 0 หรือ '0'
ยืนยันใน (อาร์เรย์)	'ใน'	ตรวจสอบว่ารายการอยู่ภายใน array ที่กำหนด
ยืนยันจำนวนเต็ม	'จำนวนเต็ม'	ตรวจสอบว่ารายการนั้นเป็น integer
ยืนยันJson	'เจสัน'	ตรวจสอบว่ารายการนั้นเป็น string อ็อบเจ็กต์ JSON ที่แยกวิเคราะห์ได้
assertMaxLength (จำกัด )	'ความยาวสูงสุด'	ตรวจสอบว่าความยาวอักขระของรายการไม่เกินขีดจำกัดที่กำหนด
assertMinLength (จำกัด )	'ความยาวขั้นต่ำ'	ตรวจสอบว่าความยาวอักขระของรายการไม่ต่ำกว่าขีดจำกัดที่กำหนด
assertMax(จำกัด)	'สูงสุด'	ตรวจสอบว่าค่าตัวเลขของรายการไม่เกินขีดจำกัดที่กำหนด
assertMin (จำกัด )	'นาที'	ตรวจสอบว่าค่าตัวเลขของรายการไม่อยู่ภายใต้ขีดจำกัดที่กำหนด
assertNotIn (อาร์เรย์)	'ไม่อิน'	ตรวจสอบว่ารายการไม่อยู่ใน array ที่กำหนด
ยืนยันตัวเลข	'ตัวเลข'	ตรวจสอบว่ารายการนั้นเป็น number หรือ string ตัวเลข
ยืนยันทางเลือก	'ไม่จำเป็น'	อนุญาตให้ใช้ค่าเผื่อเลือก (สำหรับใช้กับเช็คหลายรายการเท่านั้น)
assertRegexMatch (ประสบการณ์)	'regexMatch'	ตรวจสอบว่ารายการเป็นไปตามนิพจน์ทั่วไปที่กำหนด
ยืนยันจำเป็น	'ที่จำเป็น'	ตรวจสอบว่ารายการไม่เป็น null , undefined หรือ string ว่าง
assertSame(ค่า)	'เดียวกัน'	ตรวจสอบว่ารายการเหมือนกับค่าที่ให้มา (ใช้การเปรียบเทียบแบบหลวมๆ)
assertStartsWith (ค่า)	'เริ่มต้นด้วย'	ตรวจสอบว่ารายการเริ่มต้นด้วยค่าที่กำหนด
assertString	'สตริง'	ตรวจสอบว่ารายการนั้นเป็น string
ยืนยันความจริง	'ความจริง'	ตรวจสอบว่ารายการนั้นเป็น true , 'true' , 1 หรือ '1'
assertUrl	'URL'	ตรวจสอบว่ารายการนั้นเป็น URL ที่ถูกต้อง
ยืนยันUuid	'อุ๊ย'	ตรวจสอบว่ารายการนั้นเป็น UUID

ตรวจสอบการทดสอบเพื่อดูตัวอย่างวิธีใช้กฎแต่ละข้อ

กฎที่กำหนดเอง

ไอโอดีนช่วยให้คุณเพิ่มกฎการตรวจสอบที่คุณกำหนดเองผ่านวิธี rule วิธีนี้ยอมรับพารามิเตอร์สองตัว ประการแรกคือชื่อของกฎ ประการที่สอง คือ closure ที่ไอโอดีนควรดำเนินการเมื่อเรียกใช้กฎ เช่น

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

สิ่งสำคัญ : ไอโอดีนจะสร้างอักษรตัวแรกของชื่อกฎให้เป็นตัวพิมพ์ใหญ่โดยอัตโนมัติ และนำหน้าด้วย '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]'" ) ; 

กฎแบบอะซิงโครนัส

ไอโอดีนเวอร์ชันก่อนหน้ารองรับกฎแบบกำหนดเองแบบอะซิงโครนัสโดยใช้ async / await ตั้งแต่นั้นมาสิ่งนี้ได้ถูกลบออกเพื่อทำให้ห้องสมุดง่ายต่อการบำรุงรักษา หากคุณใช้กฎอะซิงโครนัส กลยุทธ์ที่ต้องการคือดำเนินการตรรกะอะซิงโครนัสก่อน เก็บผลลัพธ์ จากนั้นให้ไอโอดีนตรวจสอบความถูกต้อง

มีส่วนร่วม

ขอขอบคุณที่พิจารณาการมีส่วนร่วมกับไอโอดีน คุณสามารถส่ง PR ที่มีกฎเพิ่มเติมได้ อย่างไรก็ตาม เพื่อให้ได้รับการยอมรับ กฎเหล่านั้นจะต้องอธิบายสิ่งที่พวกเขาทำ เป็นประโยชน์ต่อผู้อื่น และรวมการทดสอบที่เหมาะสมเพื่อยืนยันว่าทำงานได้อย่างถูกต้อง

หลังจากดึงโปรเจ็กต์แล้ว ให้ติดตั้งการขึ้นต่อกัน:

npm install

เพื่อดำเนินการทดสอบ

npm run test 

ใบอนุญาต

ใบอนุญาตเอ็มไอที (MIT) โปรดดูไฟล์ใบอนุญาตสำหรับข้อมูลเพิ่มเติม