التابع .ajaxError() في jQuery
.ajaxError( handler )
القيمة المعادة
كائن jQuery.
الوصف
يُستخدَم التّابع .ajaxError() لتسجيل مُعالِج الأحداث (Event handler) لاستدعائه عند اكتمال تنفيذ طلب Ajax مع حدوث خطأ، يُعدُّ هذا التّابع حدثًا من أحداث Ajax.
.ajaxError( handler )
أضيفت في الإصدار 1.0.
handler
دالة على الشكل Function( Event event, jqXHR jqXHR, PlainObject ajaxSettings, String thrownError )، وهي الدالة المطلوب استدعاؤها.
حالما يكتمل تنفيذ طلب Ajax، تُطلِق jQuery الحدث ajaxError. وتُنفَّذ عندها كافّة مُعالجات الأحداث المُسجَّلة مع التّابع .ajaxError().
ملاحظة: لا يُستدعى مُعالِج الأحداث هذا لأجل الشيفرة المُنفَّذة عبر النطاقات (cross-domain script) أو لأجل طلبات JSONP المُنفَّذة عبر نطاقات متعددة (cross-domain JSONP).
لمشاهدة مثال عملي عن هذا التّابع نُجهِّز طلب بسيط لتحميل Ajax:
<button class="trigger">إطلاق مُعالِج الحدث</button>
<div class="result"></div> <!--تُعرَض هنا النتيجة-->
<div class="log"></div> <!--تُعرَض هنا رسالة السّجل-->
أرفِق مُعالِج الحدث (event handler) إلى المستند:
$( document ).ajaxError(function() {
$( ".log" ).text( ".ajaxErrorأُطلِق مُعالِج الحدث " );
});
نفذ الآن طلب Ajax باستخدام أي تابع jQuery:
$( "button.trigger" ).on( "click", function() {
$( "div.result" ).load( "ajax/missing.html" );
});
عندما يضغط المستخدم على العنصر الذي يمتلك الصنف trigger ويفشل تنفيذ طلب Ajax بسبب عدم وجود الملف المطلوب، ستُعرَض رسالة السّجل.
تُستدعى كافة مُعالِجات أحداث ajaxError عند اكتمال تنفيذ أي طلب Ajax، إن كنت تريد التفريق بين الطلبات فاستخدم المعاملات الممررة لمُعالِج الأحداث، ففي كل مرة يُنفَّذ فيها مُعالِج الحدث ajaxError يُمرِّر كائن الحدث، والكائن jqXHR (الكائن XHR قبل إصدار jQuery 1.5)، وكائن الإعدادات الذي استخدم في إنشاء الطلب. عند حدوث خطأ HTTP، يستقبل الوسيط الرابع وهو thrownError الجزء النّصي من حالة HTTP، مثل "Not Found" أو "Internal Server Error". بإمكاننا على سبيل المثال حصر الاستدعاء فقط من أجل الأحداث التي تتعامل مع روابط معينة:
$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) {
if ( settings.url == "ajax/missing.html" ) {
$( "div.log" ).text( ".ajaxError أُطلِق مُعالِج الحدث " );
}
});
ملاحظات إضافية
بدءًا من إصدار jQuery 1.9 أصبح إرفاق مُعالِجات الأحداث لأحداث Ajax العامة (jQuery global Ajax events) بالمستند إجباريًّا، بما في ذلك مُعالِجات الأحداث المُضافة عن طريق التّابع .ajaxError().
إن استدعينا التابع $.ajax() أو $.ajaxSetup() مع تعيين الخيار global إلى القيمة false، فلن يُنفَّذ التّابع .ajaxError().
أمثلة
إظهار رسالة عند فشل تنفيذ طلب Ajax:
$( document ).ajaxError(function( event, request, settings ) {
$( "#msg" ).append( "<li>فشل طلب الصفحة " + settings.url + "</li>" );
});