التابع `‎‎$.ajaxPrefilter()‎`‎ في jQuery

`jQuery.ajaxPrefilter( [dataTypes ], handler )‎`

القيم المعادة

الوصف

يعالج هذا التابع إعدادات Ajax المخصَّصة أو يعدِّل إعدادات موجودة قبل أن يرسل كل طلب وقبل أن يعالج باستعمال الدالة ‎$.ajax()‎.

`jQuery.ajaxPrefilter( [dataTypes ], handler )‎`

أُضيف مع الإصدار: 1.5.

`dataTypes`

سلسلة نصية اختياريَّة تحتوي على نوع بيانات (dataType) واحد أو عدَّة أنواع مفصولة بفراغ.

`handler`

دالة من الشكل Function( Object options, Object originalOptions, jqXHR jqXHR )‎ وتستعمل لتعيين قيم افتراضيَّة لطلبات Ajax المستقبليَّة.

تبدو عملية الترشيح المسبقة الاعتيادية باستعمال ‎$.ajaxPrefilter()‎ بالشكل:

$.ajaxPrefilter(function( options, originalOptions, jqXHR ) {
 // jqXHR وتخزينها في الكائن ،option إلى الإعدادات originalOption تعديل الإعدادات الأساسية
});

إذ يكون:

options: إعدادات الطلب.
originalOptions: الإعدادات التي مُرِّرت إلى الدالة ‎$.ajax()‎ دون أي تعديل أو تغيير إلى قيم افتراضية باستعمال ajaxSettings.
jqXHR: الكائن jqXHR للطلب.

تبرز فائدة استعمال المرشحات المسبقة عند الحاجة إلى معالجة إعدادات مخصَّصة. إن كان لدينا مثلًا الشيفرة التالية، فسيؤدي استدعاء ‎$.ajax()‎ إلى مقاطعة الطلب ذي العنوان URL نفسه شرط أن تٌعيَّن قيمة الضبط abortOnRetry المخصَّص إلى القيمة true:

var currentRequests = {};
 
$.ajaxPrefilter(function( options, originalOptions, jqXHR ) {
  if ( options.abortOnRetry ) {
    if ( currentRequests[ options.url ] ) {
      currentRequests[ options.url ].abort();
    }
    currentRequests[ options.url ] = jqXHR;
  }
});

يمكن أيضًا استعمال المرشحات المسبقة لتعديل قيمة ضبط حالي. على سبيل المثال، تستعمل الشيفرة التالية وسطاء (proxies) لإرسال الطلبات العابرة للنطاقات (cross-domain requests) عبر https://mydomain.net/proxy/‎:

$.ajaxPrefilter(function( options ) {
  if ( options.crossDomain ) {
    options.url = "https://mydomain.net/proxy/" + encodeURIComponent( options.url );
    options.crossDomain = false;
  }
});

إن أعطي الوسيط dataType، فستُطبَّق المرشِّحات المسبقة على الطلبات ذات النوع dataType المعطى فقط. على سبيل المثال، ستتطبَّق المرشحات المسبقة في الشيفرة التالية على الطلبات ذات النوع "script" والنوع "JSON" فقط:

$.ajaxPrefilter( "json script", function( options, originalOptions, jqXHR ) {
 // jqXHR وتخزينها في الكائن ،option إلى الإعدادات originalOption تعديل الإعدادات الأساسية
});

يستطيع التابع ‎$.ajaxPrefilter(‎)‎ أيضًا أن يعيد تحويل الطلب إلى نوع dataType آخر عبر إعادة هذا النوع. في الشيفرة التالية مثلًا، يحوَّل نوع الطلب إلى "script" إن احتوى العنوان URL على خاصِّيَّات محدَّدة مُعرَّفة في الدالة isActuallyScript()‎ المخصَّصة:

$.ajaxPrefilter(function( options ) {
  if ( isActuallyScript( options.url ) ) {
    return "script";
  }
});

لا تضمن هذه العمليَّة أن يكون نوع الطلب "script" فقط بل تضمن أيضًا أنَّ جميع المرشحات المسبقة المرتبطة بالطلب ذي النوع "script" ستُطبَّق عليه.

مصادر

صفحة التابع ‎jQuery.ajaxPrefilter في توثيق jQuery الرسمي.