التابع jQuery.ajaxTransport() في jQuery
jQuery.ajaxTransport( dataType, handler )
القيم المعادة
يعيد قيمةً من النوع undefined.
الوصف
ينشئ هذا التابع كائنًا يعالج عملية الإرسال الفعلي لبيانات Ajax.
jQuery.ajaxTransport( dataType, handler )
أُضيف مع الإصدار: 1.5.
dataTypes
سلسلة نصية تحدِّد نوع البيانات المراد استعمال هذا التابع معها.
handler
دالةٌ من الشكل Function( Object options, Object originalOptions, jqXHR jqXHR ) تعيد الكائن transport الجديد لاستعماله مع نوع البيانات المحدَّد في الوسيط الأول.
الكائن transport هو كائنٌ يوفر تابعين اثنين هما: التابع send، والتابع abort اللذان تستعملهما الدالة $.ajax() داخليًا لإصدار الطلبات. الكائن transport هو من أفضل الطرائق المتقدِّمة لتحسين $.ajax() ويلجأ إليه في نهاية المطاف عندما لا يكفي استعمال المرشحات المسبقة (prefilters) والمحولات (converters).
لمَّا كان كل طلب يطلب نسخةً خاصةً به من الكائن transport، فلا يمكن تسجيل هذه الكائنات مباشرةً. من أجل ذلك، يجب عليك توفير دالةٍ تعيد الكائن transport.
تُسجَّل المنتجات transport باستعمال $.ajaxTransport(). عملية التسجيل الطبيعية تبدو مثل هذه الشيفرة:
$.ajaxTransport( dataType, function( options, originalOptions, jqXHR ) {
if( /* transportCanHandleRequest */ ) {
return {
send: function( headers, completeCallback ) {
// شيفرة الإرسال
},
abort: function() {
// شيفرة المقاطعة
}
};
}
});
إذ يكون:
options: إعدادات الطلب.originalOptions: الإعدادات التي مرِّرت إلى الدالة $.ajax() دون أي تعديل أو تغيير إلى قيم افتراضيَّة باستعمالajaxSettings.jqXHR: الكائن jqXHR للطلب.headers: كائنٌ من أزواج مفتاح/قيمة لترويسات الطلب التي يمكن إرسال الكائن transport إن كانت تدعمه.completeCallback: رد نداء يستعمل لإبلاغ Ajax عند اكتمال الطلب.
يملك completeCallback التوقيع التالي:
function( status, statusText, responses, headers ) {}
إذ يكون:
status: هي رمز حالة HTTP للرد مثل 200 عند النجاح الطبيعي، أو 404 عند عدم العثور على المصدر.statusText: هي الحالةstatusTextللرد.responses: (اختياري) هو كائن يحتوي على أزواج من نوع البيانات (dataType)/قيمة التي تحتوي على الرد في جميع الصيغ التي يمكن أن يوفرها الكائن transport (الكائن XMLHttpRequest الأساسي مثلًا سيضبط الردود إلى{ xml: XMLData, text: textData }من أجل ردٍ لمستند من النوع XML).headers: (اختياري) هو سلسلة نصية تحتوي على جميع ترويسات الردود في حال وَصَلَ الكائن transport إليهم (قريبٌ لما سيوفرهXMLHttpRequest.getAllResponseHeaders()).
بصورة مشابهة للمرشحات المسبقة، يمكن ربط التابع .ajaxTransport()$ الناتج بنوع بيانات (dataType) محدَّد:
$.ajaxTransport( "script", function( options, originalOptions, jqXHR ) {
// فقط script سيستدعى من أجل الطلبات
});
المثال التالي يوضِّح كيف يمكن تنفيذ عمليَّة نقل صورة:
$.ajaxTransport( "image", function( s ) {
if ( s.type === "GET" && s.async ) {
var image;
return {
send: function( _ , callback ) {
image = new Image();
function done( status ) {
if ( image ) {
var statusText = ( status === 200 ) ? "success" : "error",
tmp = image;
image = image.onreadystatechange = image.onerror = image.onload = null;
callback( status, statusText, { image: tmp } );
}
}
image.onreadystatechange = image.onload = function() {
done( 200 );
};
image.onerror = function() {
done( 404 );
};
image.src = s.url;
},
abort: function() {
if ( image ) {
image = image.onreadystatechange = image.onerror = image.onload = null;
}
}
};
}
});
معالجة أنواع بيانات مخصصة
يأتي مع تنفيذ Ajax في jQuery مجموعةً من أنواع البيانات (dataType) القياسيَّة مثل النوع "text"، والنوع "json"، والنوع "xml"، والنوع "html".
يمكنك استعمال الضبط converters في $.ajaxSetup() لزيادة أو تعديل خطة تحويل نوع البيانات المستعملة من قِبَل $.ajax().
يتضمن مصدر jQuery غير المُصغّر (المضغوط) بذاته قائمةً من المحولات الافتراضيَّة التي توضح كيف يمكن استعمالها بفاعلية:
// قائمة بمحولات البيانات
// 1) ”الصياغة المستعملة: “النوع_المصدر النوع_المستهدف
// يجب أن يوجد فراغ وحيد بين النوعين
// 2) يمكن استعمال محرف “*” مع النوع_المصدر
converters: {
// text حول أي شيء إلى النوع
"* text": window.String,
//("تعني "بلا تحويل true القيمة) html إلى text حول من
"text html": true,
// json كأنه تعبير text عامل النوع
"text json": jQuery.parseJSON,
// xml كأنه text حلل النوع
"text xml": jQuery.parseXML
}
عند تحديد قيمة الضبط converters بصورة عامة (globally) باستعمال $.ajaxSetup() أو عند استدعاء $.ajax()، فسيعيَّن الكائن إلى قيمة الضبط converters الافتراضيَّة بتبديل تلك القيم المحدَّدة وترك القيم الأخرى على حالها.
على سبيل المثال، تستعمل $.ajaxSetup() jQuery لإضافة محوِّل من النوع "text" إلى النوع "script":
jQuery.ajaxSetup({
accepts: {
script: "text/javascript, application/javascript"
},
contents: {
script: /javascript/
},
converters: {
"text script": jQuery.globalEval
}
});