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 .

وبدلاً من ذلك، إذا كنت مرتاحًا لاستخدام عمليات الاستيراد، أو كنت ترغب في إنشاء مثيل خاص بك، فيمكنك استيراد Iodine على النحو التالي:

 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

انظر أدناه للحصول على قائمة كاملة بقواعد التحقق من صحة اليود.

التحقق المتقدم

في حين أن التحقق مما إذا كان العنصر يتوافق مع قاعدة التحقق الفردية قد يكون مفيدًا، فسوف تحتاج غالبًا إلى التحقق مما إذا كان العنصر يتوافق مع قواعد متعددة. على سبيل المثال، قد يكون عنوان البريد الإلكتروني مطلوبًا، ويجب أن يكون سلسلة، ويجب أن يفي بالتعبير العادي لعنوان البريد الإلكتروني.

لتلبية هذه الاحتياجات، يقدم 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' ] ) ; 

القيم الاختيارية

للتحقق المتقدم، قد ترغب في السماح بالقيم الاختيارية. يدعم اليود هذا بالقاعدة 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 ) ;

اسم الحقل الافتراضي

نظرًا لأن "التحقق من العناصر الفردية" لا يدعم أسماء الحقول، فإن Iodine يستخدم الاسم الافتراضي بدلاً من ذلك (وهو "القيمة"). إذا لم تكن "القيمة" مناسبة، فيمكنك استدعاء الأسلوب setDefaultFieldName وتوفير قيمة string بديلة لاستخدامها بدلاً من ذلك، على سبيل المثال

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

لاحظ أنه يجب عليك استدعاء setDefaultFieldName قبل استدعاء assert .

القواعد المتاحة

تتوفر قواعد التحقق التالية:

قاعدة	مفتاح السلسلة	وصف
تأكيدAfter(تاريخ/عدد صحيح)	'بعد'	تأكد من أن العنصر هو Date بعد Date أو طابع زمني محدد
تأكيدAfterOrEqual(تاريخ/عدد صحيح)	"بعد أو يساوي"	تأكد من أن العنصر هو Date بعد أو يساوي Date أو طابعًا زمنيًا محددًا
تأكيدArray	"مصفوفة"	تحقق من أن العنصر عبارة عن array
تأكيدقبل(تاريخ/عدد صحيح)	'قبل'	تأكد من أن العنصر هو Date يسبق Date أو طابعًا زمنيًا محددًا
تأكيدBeforeOrEqual(تاريخ/عدد صحيح)	"قبل أو يساوي"	تأكد من أن العنصر هو Date يسبق أو يساوي Date أو طابعًا زمنيًا محددًا
assertBoolean	"منطقي"	التحقق من true العنصر أو false
تأكيد التاريخ	'تاريخ'	تأكد من أن العنصر هو كائن Date
تأكيد مختلف (القيمة)	'مختلف'	تأكد من أن العنصر مختلف عن القيمة المقدمة (يستخدم مقارنة فضفاضة)
تأكيد النهاية (القيمة)	"ينتهي"	تحقق من أن العنصر ينتهي بالقيمة المحددة
تأكيد البريد الإلكتروني	'بريد إلكتروني'	تأكد من أن العنصر هو عنوان بريد إلكتروني صالح
تأكيدFalsy	"كاذب"	تحقق من أن العنصر إما false أو 'false' أو 0 أو '0'
تأكيد في (صفيف)	'في'	تحقق من أن العنصر موجود ضمن array المحددة
assertInteger	'عدد صحيح'	تأكد من أن العنصر integer
asseJson	"جسون"	تأكد من أن العنصر عبارة عن string كائنات JSON قابلة للتحليل
تأكيد ماكس طول (الحد)	"الطول الأقصى"	تأكد من أن طول حرف العنصر لا يتجاوز الحد المحدد
تأكيدMinLength(الحد)	"الطول الأدنى"	تأكد من أن طول حرف العنصر ليس أقل من الحد المحدد
تأكيد ماكس (الحد)	'الأعلى'	التأكد من أن القيمة الرقمية للصنف لا تتجاوز الحد المحدد
تأكيدمين (الحد)	"دقيقة"	تأكد من أن القيمة الرقمية للعنصر ليست أقل من الحد المحدد
تأكيد ليس في (صفيف)	"ليس في"	تأكد من أن العنصر ليس ضمن array المحددة
assertNumeric	"رقمي"	تأكد من أن العنصر number أو string رقمية
تأكيداختياري	'خياري'	السماح بالقيم الاختيارية (فقط للاستخدام مع عمليات التحقق المتعددة)
AssurRegexMatch(exp)	"تطابق عادي"	تحقق من أن العنصر يلبي التعبير العادي المحدد
تأكيد مطلوب	'مطلوب'	تأكد من أن العنصر ليس null أو undefined أو string فارغة
تأكيد نفسه (القيمة)	'نفس'	تأكد من أن العنصر هو نفس القيمة المقدمة (يستخدم مقارنة فضفاضة)
تأكيدStartsWith(القيمة)	"يبدأ مع"	تحقق من أن العنصر يبدأ بالقيمة المحددة
تأكيد سلسلة	'خيط'	تأكد من أن العنصر عبارة عن string
assertTruthy	"صادق"	تحقق من أن العنصر إما true أو 'true' أو 1 أو '1'
AssureUrl	"عنوان URL"	تأكد من أن العنصر هو عنوان URL صالح
assurerUuid	"uuid"	تحقق من أن العنصر هو UUID

افحص الاختبارات للحصول على أمثلة حول كيفية استخدام كل قاعدة.

القواعد المخصصة

يتيح لك اليود إضافة قواعد التحقق المخصصة الخاصة بك من خلال طريقة rule . تقبل هذه الطريقة معلمتين. الأول هو اسم القاعدة. والثاني هو closure الذي يجب أن ينفذه اليود عند استدعاء القاعدة على سبيل المثال

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

هام : سوف يقوم اليود تلقائيًا بكتابة الحرف الأول من اسم القاعدة بأحرف كبيرة ويبدأه بكلمة "تأكيد". لذلك يجب عليك تجنب إضافة البادئة بنفسك، على سبيل المثال

 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 بالتحقق من صحتها.

المساهمة

شكرًا لك على التفكير في المساهمة في اليود. نرحب بتقديم تقرير العلاقات العامة الذي يحتوي على قواعد إضافية، ولكن لكي يتم قبوله، يجب أن يوضح ما يفعله، وأن يكون مفيدًا للآخرين، ويتضمن اختبارًا مناسبًا للتأكد من أنه يعمل بشكل صحيح.

بعد سحب المشروع، لتثبيت التبعيات:

npm install

لتشغيل الاختبارات

npm run test 

رخصة

رخصة معهد ماساتشوستس للتكنولوجيا (MIT). يرجى الاطلاع على ملف الترخيص لمزيد من المعلومات.