الفرق بين المراجعتين ل"jQuery/ajaxError"
Kinan-mawed (نقاش | مساهمات) (أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:التابع <code>.ajaxError()</code> في jQuery}}</noinclude>') |
|||
| (5 مراجعات متوسطة بواسطة مستخدمين اثنين آخرين غير معروضة) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:التابع <code>.ajaxError()</code> في jQuery}}</noinclude> | <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, 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]] | ||
المراجعة الحالية بتاريخ 13:20، 1 يوليو 2018
.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>" );
});