zl fetch

zlFetch

zlFetch عبارة عن أداة ملتفة حول الجلب توفر لك طريقة ملائمة لتقديم الطلبات.

مميزاته هي كما يلي:

• تحسينات نوعية الحياة عبر وظيفة fetch الأصلية

  • استخدم الاستجابة على الفور دون استخدام response.json() أو response.text() أو response.blob()
  • معالجة الأخطاء بطريقة تشبه الوعد - يتم توجيه جميع الأخطاء 400 و500 إلى كتلة catch تلقائيًا.
  • معالجة سهلة للأخطاء عند استخدام await — يمكن إرجاع الأخطاء حتى لا تضطر إلى كتابة كتلة try/catch .

• تحسينات إضافية على وظيفة fetch الأصلية

  • يتم تعيين رؤوس Content-Type تلقائيًا بناءً على محتوى body .
  • احصل على كل ما تحتاجه بشأن استجابتك - headers body status والمزيد.
  • قم بتصحيح طلبك دون النظر إلى لوحة الشبكة
  • اختصار لأساليب GET و POST و PUT و PATCH و DELETE
  • مساعد لإنشاء سلاسل الاستعلام حتى لا تضطر إلى العبث بمعلمات الاستعلام.
  • يُنشئ رؤوس التفويض باستخدام خاصية auth .
  • قم بإنشاء مثيلات للاحتفاظ بعنوان URL والخيارات حتى لا تضطر إلى تكرار نفسك.

ملحوظة: zlFetch هي مكتبة ESM منذ v4.0.0 .

تثبيت zlFetch

من خلال npm (مستحسن)

 # Installing through npm
npm install zl-fetch --save

ثم يمكنك استخدامه عن طريق استيراده في ملف JavaScript الخاص بك.

 import zlFetch from 'zl-fetch'

باستخدام zlFetch بدون npm :

يمكنك استيراد zlFetch مباشرة إلى JavaScript من خلال CDN.

للقيام بذلك، تحتاج أولاً إلى ضبط نوع script الخاص بك على module ، ثم استيراد zlFetch .

 < script type =" module " >
  import zlFetch from 'https://cdn.jsdelivr.net/npm/[email protected]/src/index.js'
</ script > 

بداية سريعة

يمكنك استخدام zlFetch تمامًا مثل وظيفة fetch العادية. والفرق الوحيد هو أنك لست مضطرًا إلى كتابة طريقة response.json أو response.text بعد الآن!

يقوم zlFetch بمعالجتها نيابةً عنك تلقائيًا حتى تتمكن من الانتقال مباشرةً إلى استخدام استجابتك.

 zlFetch ( 'url' )
  . then ( response => console . log ( response ) )
  . catch ( error => console . log ( error ) )

الطرق المختصرة لـ GET وPOST وPUT وPATCH وDELETE

يحتوي zlFetch على أساليب مختصرة لطرق REST الشائعة هذه حتى تتمكن من استخدامها بسرعة.

 zlFetch . get ( /* some-url */ )
zlFetch . post ( /* some-url */ )
zlFetch . put ( /* some-url */ )
zlFetch . patch ( /* some-url */ )
zlFetch . delete ( /* some-url */ )

أنواع الاستجابة المدعومة

يدعم zlFetch أنواع الاستجابة json ، و text ، و blob لذلك لا يتعين عليك كتابة response.json() ، أو response.text() ، أو response.blob() .

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

يحتوي الرد على جميع البيانات التي قد تحتاجها

يرسل لك zlFetch كافة البيانات التي تحتاجها في كائن response . وهذا يشمل ما يلي:

• headers : رؤوس الاستجابة
• body : جسم الاستجابة
• status : حالة الاستجابة
• نص statusText : نص حالة الاستجابة
• response : الرد الأصلي من Fetch

نقوم بذلك حتى لا تضطر إلى البحث عن headers أو status أو statusText أو حتى بقية كائن response بنفسك.

تصحيح الطلب

الجديد في v4.0.0 : يمكنك تصحيح أخطاء كائن الطلب عن طريق إضافة خيار debug . سيكشف هذا عن كائن debug الذي يحتوي على الطلب الذي يتم إنشاؤه.

• url
• method
• headers
• body

 zlFetch ( 'url' , { debug : true } )
  . then ( { debug } = > console . log ( debug ) )

معالجة الأخطاء

يقوم zlFetch بتوجيه جميع الأخطاء 400 و500 إلى طريقة catch . تحتوي الأخطاء على نفس المعلومات الموجودة في الرد.

• headers : رؤوس الاستجابة
• body : جسم الاستجابة
• status : حالة الاستجابة
• نص statusText : نص حالة الاستجابة
• response : الاستجابة الأصلية من الجلب

وهذا يجعل استخدام zlFetch سهلاً للغاية مع الوعود.

 zlFetch ( 'some-url' ) . catch ( error => {
  /* Handle error */
} )

// The above request can be written in Fetch like this:
fetch ( 'some-url' )
  . then ( response => {
    if ( ! response . ok ) {
      Promise . reject ( response . json )
    }
  } )
  . catch ( error => {
    /* Handle error */
  } )

معالجة سهلة للأخطاء عند استخدام async / await

يتيح لك zlFetch تمرير كافة الأخطاء إلى كائن errors . يمكنك القيام بذلك عن طريق إضافة خيار returnError . يكون هذا مفيدًا عندما تعمل كثيرًا مع async/await .

 const { response , error } = await zlFetch ( 'some-url' , { returnError : true } ) 

ميزات مفيدة

مساعدين سلسلة الاستعلام

يمكنك إضافة query أو queries كخيار وسيقوم zlFetch بإنشاء سلسلة استعلام لك تلقائيًا. استخدم هذا مع طلبات GET .

 zlFetch ( 'some-url' , {
  queries : {
    param1 : 'value1' ,
    param2 : 'to encode' ,
  } ,
} )

// The above request can be written in Fetch like this:
fetch ( 'url?param1=value1&param2=to%20encode' )

إنشاء Content-Type بناءً على محتوى body

يقوم zlFetch بتعيين Content-Type بشكل مناسب اعتمادًا على بيانات body . وهو يدعم ثلاثة أنواع من البيانات:

• هدف
• سلاسل الاستعلام
• بيانات النموذج

إذا قمت بتمرير object ، فسيقوم zlFetch بتعيين Content-Type على application/json . سوف يقوم أيضًا JSON.stringify جسمك حتى لا تضطر إلى القيام بذلك بنفسك.

 zlFetch . post ( 'some-url' , {
  body : { message : 'Good game' } ,
} )

// The above request is equivalent to this
fetch ( 'some-url' , {
  method : 'post' ,
  headers : { 'Content-Type' : 'application/json' } ,
  body : JSON . stringify ( { message : 'Good game' } ) ,
} )

يحتوي zlFetch على مساعد toObject الذي يتيح لك تحويل بيانات النموذج إلى كائن. وهذا يجعل من السهل جدًا استخدام zlFetch باستخدام النماذج.

 import { toObject } from 'zl-fetch'
const data = new FormData ( form . elements )

zlFetch ( 'some-url' , {
  body : toObject ( data ) ,
} )

إذا قمت بتمرير سلسلة، فسيقوم zlFetch بتعيين Content-Type على application/x-www-form-urlencoded .

يحتوي zlFetch أيضًا على أسلوب toQueryString الذي يمكنه مساعدتك في تحويل الكائنات إلى سلاسل استعلام حتى تتمكن من استخدام هذا الخيار بسهولة.

 import { toQueryString } from 'zl-fetch'

zlFetch . post ( 'some-url' , {
  body : toQueryString ( { message : 'Good game' } ) ,
} )

// The above request is equivalent to this
fetch ( 'some-url' , {
  method : 'post' ,
  headers : { 'Content-Type' : 'application/x-www-form-urlencoded' } ,
  body : 'message=Good%20game' ,
} )

إذا قمت بتمرير بيانات النموذج، فسيسمح zlFetch لوظيفة fetch الأصلية بالتعامل مع Content-Type . بشكل عام، سيستخدم هذا multipart/form-data مع الخيارات الافتراضية. إذا كنت تستخدم هذا، فتأكد من أن خادمك يمكنه تلقي multipart/form-data !

 import { toObject } from 'zl-fetch'
const data = new FormData ( form . elements )

zlFetch ( 'some-url' , { body : data } )

// The above request is equivalent to this
fetch ( 'some-url' , { body : data } )

// Your server should be able to receive multipart/form-data if you do this. If you're using Express, you can a middleware like multer to make this possible:
import multer from 'multer'
const upload = multer ( )
app . use ( upload . array ( ) )

تغيير جذري في v5.0.0 : إذا قمت بتمرير رأس Content-Type ، فلن يقوم zlFetch بتعيين تنسيق محتوى جسمك بعد الآن. نتوقع منك أن تكون قادرًا على إدخال نوع البيانات الصحيح. (كان علينا القيام بذلك لدعم واجهة برمجة التطبيقات الجديدة المذكورة أعلاه).

مساعدين رأس التفويض

إذا قمت بتزويد zlFetch بخاصية auth ، فسيتم إنشاء رأس تفويض لك.

إذا قمت بتمرير string (عادةً للرموز المميزة)، فسيتم إنشاء Bearer Auth.

 zlFetch ( 'some-url' , { auth : 'token12345' } )

// The above request can be written in Fetch like this:
fetch ( 'some-url' , {
  headers : { Authorization : `Bearer token12345` } ,
} )

إذا قمت بتمرير object ، فسيقوم zlFetch بإنشاء مصادقة أساسية لك.

 zlFetch ( 'some-url' , {
  auth : {
    username : 'username'
    password : '12345678'
  }
} )

// The above request can be written in Fetch like this:
fetch ( 'some-url' , {
  headers : { Authorization : `Basic ${ btoa ( 'username:12345678' ) } ` }
} ) ;

إنشاء مثيل zlFetch

يمكنك إنشاء مثيل لـ zlFetch بخيارات محددة مسبقًا. يعد هذا مفيدًا للغاية إذا كنت بحاجة إلى إرسال طلبات تحتوي على options أو url مماثلة.

• مطلوب url
• options اختيارية

 import { createZLFetch } from 'zl-fetch'

// Creating the instance
const api = zlFetch ( baseUrl , options )

جميع الحالات لها طرق مختصرة أيضًا.

 // Shorthand methods
const response = api . get ( /* ... */ )
const response = api . post ( /* ... */ )
const response = api . put ( /* ... */ )
const response = api . patch ( /* ... */ )
const response = api . delete ( /* ... */ )

الجديد في v5.0.0

يمكنك الآن استخدام مثيل zlFetch دون تمرير عنوان URL. يعد هذا مفيدًا إذا قمت بإنشاء مثيل بنقاط النهاية الصحيحة.

 import { createZLFetch } from 'zl-fetch'

// Creating the instance
const api = zlFetch ( baseUrl , options )

جميع الحالات لها طرق مختصرة أيضًا.

 // Shorthand methods
const response = api . get ( ) // Without URL, without options
const response = api . get ( 'some-url' ) // With URL, without options
const response = api . post ( 'some-url' , { body : 'message=good+game' } ) // With URL, with options
const response = api . post ( { body : 'message=good+game' } ) // Without URL, with options

معالج الاستجابة المخصصة

إذا كنت تريد التعامل مع استجابة غير مدعومة بواسطة zlFetch، فيمكنك تمرير customResponseParser: true إلى الخيارات. يؤدي هذا إلى إرجاع الاستجابة من طلب جلب عادي دون أي معالجات إضافية من zlFetch. يمكنك بعد ذلك استخدام response.json() أو الطرق الأخرى التي تراها مناسبة.

 const response = await zlFetch ( 'url' , {
  customResponseParser : true ,
} )
const data = await response . arrayBuffer ( )