عرض مصدر jQuery/ajaxError

<noinclude>{{DISPLAYTITLE:التابع <code>‎.ajaxError()‎‎</code>‎ في jQuery}}</noinclude>
== <code>‎.ajaxError( handler )‎</code> ==

=== القيمة المعادة ===
كائن [[jQuery/jQuery|jQuery]].

=== الوصف ===
يُستخدَم التّابع <code>‎.ajaxError()</code>‎ لتسجيل مُعالِج الأحداث (Event handler) لاستدعائه عند اكتمال تنفيذ طلب Ajax مع حدوث خطأ،  يُعدُّ هذا التّابع حدثًا من [[JQuery/ajax events|أحداث Ajax]].

=== <code>‎.ajaxError( handler )‎</code> ===
أضيفت في الإصدار 1.0.

==== <code>handler</code> ====
دالة على الشكل ‎<code>[[JavaScript/Function|Function]]( [[JavaScript/Event|Event]] event, [[jQuery/jqXHR|jqXHR]] jqXHR, [[JavaScript/Object|PlainObject]] ajaxSettings, [[JavaScript/String|String]] thrownError )</code>‎، وهي الدالة المطلوب استدعاؤها.

حالما يكتمل تنفيذ طلب Ajax، تُطلِق jQuery الحدث <code>ajaxError</code>. وتُنفَّذ عندها كافّة مُعالجات الأحداث المُسجَّلة مع التّابع <code>‎‎.ajaxError()‎‎</code>.

'''ملاحظة:''' لا يُستدعى مُعالِج الأحداث هذا لأجل الشيفرة المُنفَّذة عبر النطاقات (cross-domain script) أو لأجل طلبات JSONP المُنفَّذة عبر نطاقات متعددة (cross-domain JSONP).

لمشاهدة مثال عملي عن هذا التّابع نُجهِّز طلب بسيط لتحميل Ajax:<syntaxhighlight lang="html">
<button class="trigger">إطلاق مُعالِج الحدث</button>
<div class="result"></div> <!--تُعرَض هنا النتيجة-->
<div class="log"></div> <!--تُعرَض هنا رسالة السّجل-->

</syntaxhighlight>أرفِق مُعالِج الحدث (event handler) إلى المستند:<syntaxhighlight lang="javascript">
$( document ).ajaxError(function() {
 $( ".log" ).text( ".‏ajaxError‏أُطلِق مُعالِج الحدث ‏" );
});


</syntaxhighlight>نفذ الآن طلب Ajax باستخدام أي تابع jQuery:<syntaxhighlight lang="javascript">
$( "button.trigger" ).on( "click", function() {
 $( "div.result" ).load( "ajax/missing.html" );
});
</syntaxhighlight>عندما يضغط المستخدم على العنصر الذي يمتلك الصنف <code>trigger</code> ويفشل تنفيذ طلب Ajax بسبب عدم وجود الملف المطلوب، ستُعرَض رسالة السّجل.

تُستدعى كافة مُعالِجات أحداث <code>ajaxError</code> عند اكتمال تنفيذ أي طلب Ajax، إن كنت تريد التفريق بين الطلبات فاستخدم المعاملات الممررة لمُعالِج الأحداث، ففي كل مرة يُنفَّذ فيها مُعالِج الحدث <code>ajaxError</code> يُمرِّر كائن الحدث، والكائن <code>jqXHR</code> (الكائن <code>XHR</code> قبل إصدار jQuery 1.5)، وكائن الإعدادات الذي استخدم في إنشاء الطلب. عند حدوث خطأ HTTP، يستقبل الوسيط الرابع وهو <code>thrownError</code> الجزء النّصي من حالة HTTP، مثل <code>"Not Found"</code> أو <code>"Internal Server Error"</code>. بإمكاننا على سبيل المثال حصر الاستدعاء فقط من أجل الأحداث التي تتعامل مع روابط معينة:<syntaxhighlight lang="javascript">
$( document ).ajaxError(function( event, jqxhr, settings, thrownError ) {
 if ( settings.url == "ajax/missing.html" ) {
   $( "div.log" ).text( ".‏ajaxError ‏أُطلِق مُعالِج الحدث " );
 }
});


</syntaxhighlight>

=== ملاحظات إضافية ===
بدءًا من إصدار jQuery 1.9 أصبح إرفاق مُعالِجات الأحداث لأحداث Ajax العامة (jQuery global Ajax events) بالمستند إجباريًّا، بما في ذلك مُعالِجات الأحداث المُضافة عن طريق التّابع <code>‎.ajaxError()‎‎</code>.

إن استدعينا التابع ‎<code>[[jQuery/jQuery/ajax|$.ajax()]]</code>‎ أو ‎<code>[[jQuery/jQuery/ajaxSetup|$.ajaxSetup()]]</code>‎ مع تعيين الخيار <code>global</code> إلى القيمة <code>false</code>، فلن يُنفَّذ التّابع ‎<code>.ajaxError()</code>‎‎.

=== أمثلة ===
إظهار رسالة عند فشل تنفيذ طلب Ajax:<syntaxhighlight lang="javascript">
$( document ).ajaxError(function( event, request, settings ) {
 $( "#msg" ).append( "<li>فشل طلب الصفحة " + settings.url + "</li>" );
});


</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/ajaxError/ صفحة التابع ‎‎‎.ajaxError()‎‎ في توثيق jQuery الرسمي].
[[تصنيف:jQuery]]
[[تصنيف:jQuery Method]]
[[تصنيف:jQuery Ajax]]