عرض مصدر jQuery/jQuery/Callbacks

<noinclude>{{DISPLAYTITLE:الدالة <code>‎‎jQuery.Callbacks()‎</code>‎ في jQuery}}</noinclude>
== <code>jQuery.Callbacks( flags )‎</code> ==

=== القيم المعادة ===
تعيد كائن ردود النداء [[jQuery/callbacks|Callbacks]].

=== الوصف ===
تعيد هذه الدالة كائنًا مُتعدِّد الأغراض يُزوِّدنا بطريقة فعَّالة لإدارة قائمة ردود النداء.

=== <code>jQuery.Callbacks( flags )‎</code> ===
أُضيف مع الإصدار: 1.7.

==== <code>flags</code> ====
[[JavaScript/String|سلسلة نصية]] تمثل قائمة اختياريَّة من عدِّة رايات (flags) مفصولةٍ بفراغٍ تسهم في تغيير كيفيَّة سلوك قائمة ردود النداء.

تُستخدَم الدالة ‎<code>$.Callbacks()</code>‎ داخليًّا لتأمين الوظائف الأساسيَّة التي يحتاجها المكونين ‎<code>[[jQuery/jQuery/ajax|$.ajax()]]</code>‎ و ‎<code>[[jQuery/jQuery/Deferred|$.Deferred()]]</code>‎ في jQuery. يمكن أن تُستخدَم كقاعدة متجانسة لتعريف وظائف العناصر الجديدة.

تدعم الدالة ‎<code>$.Callbacks()</code>‎ عددًا من التوابع منها التابع <code>[[jQuery/callbacks/add|callbacks.add()‎]]</code>، والتابع <code>[[jQuery/callbacks/remove|callbacks.remove()‎]]</code>، والتابع <code>[[jQuery/callbacks/fire|callbacks.fire()]]</code>‎، والتابع <code>[[jQuery/callbacks/disable|callbacks.disable()]]</code>‎ (ارجع إلى صفحة كائن ردود النداء <code>[[jQuery/callbacks|callbacks]]</code> للاطلاع على قائمة التوابع المدعومة الكاملة).

الشيفرة التالية تحتوي على نموذج لتابعين أحدهما يدعى <code>fn1</code> والآخر يدعى <code>fn2</code>:<syntaxhighlight lang="javascript">
function fn1( value ) {
  console.log( value );
}
 
function fn2( value ) {
  console.log( "يقول fn2: " + value );
  return false;
}
</syntaxhighlight>يمكن أن نضيف هذين التابعين إلى القائمة ‎<code>$.Callbacks</code> كردود نداء ثم نستدعيهما كما يلي:<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks();
callbacks.add( fn1 );
 
// ستظهر النتيجة: مرحبًا
callbacks.fire( "مرحبًا" );
 
callbacks.add( fn2 );
 
// أهلًا :fn2 ستظهر النتيجة: مرحبًا، يقول
callbacks.fire( "أهلًا" );
</syntaxhighlight>الخلاصة هي أنَّه أصبح من الممكن إنشاء قوائم معقَّدة لردود النداء ببساطة، إذ يمكن حينها تمرير القيم المدخلة عبر عدد من الدوال بقدر ما نحتاج بكل سهولة.

استُخدِم في هذا المثال تابعان هما: التابع <code>[[jQuery/callbacks/add|‎.add()‎]]</code>، والتابع ‎<code>[[jQuery/callbacks/fire|.fire()‎]]</code>؛ يدعم التابع ‎<code>[[jQuery/callbacks/add|.add()‎]]</code> إضافة ردود نداء جديدة إلى قائمة ردود النداء، بينما ينفِّذ التابع ‎<code>[[jQuery/callbacks/fire|.fire()]]</code>‎ الدوال المضافة مع توفير وسيلةٍ لتمرير الوسائط المعطاة لكي تعالجها ردود النداء في القائمة نفسها.

هنالك تابع آخر تدعمه الدالة <code>‎$.Callbacks</code> وهو التابع <code>[[jQuery/callbacks/remove|‎.remove()]]</code>‎ الذي يملك القدرة على حذف رد نداءٍ محدَّد من قائمة ردود النداء. إليك هذا المثال الذي يوضح كيفيَّة استعمال هذا التابع:<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks();
callbacks.add( fn1 );
 
// ستظهر النتيجة: مرحبًا
callbacks.fire( "مرحبًا" );
 
callbacks.add( fn2 );
 
// أهلًا :fn2 ستظهر النتيجة: مرحبًا، يقول
callbacks.fire( "أهلًا" );
 
callbacks.remove( fn2 );
 
// fn2 ستظهر النتيجة: مرحبًا مجددًا، إذ قد حذف
callbacks.fire( "مرحبًا مجددًا" );
</syntaxhighlight>

=== الرايات المدعومة (supported flags) ===
الوسيط <code>flags</code> هو وسيط اختياري يُمرَّر إلى الدالة ‎<code>$.Callbacks()‎</code> ويتألف من سلسلة نصية تمثِّل قائمةً من عدِّة رايات مفصولةٍ بفراغٍ تسهم في تغيير كيفيَّة سلوك قائمة ردود النداء (مثل <code>‎$.Callbacks( "unique stopOnFalse"</code> )‎).

الرايات الممكن استعمالها هي:
* <code>once</code>: التأكد من أنَّ قائمة دوال النداء يمكن أن تُطلَق مرةً واحدةً فقط (مثل [[jQuery/deferred|Deferred]]).
* <code>memory</code>: استمرار تتبع القيم السابقة واستدعاء أي رد نداء يضاف بعد إطلاق قائمة ردود النداء مباشرةً مع استعمال أحدث القيم المخزَّنة (مثل [[jQuery/deferred|Deferred]]).
* <code>unique</code>: التأكد من إضافة رد النداء مرةً واحدةً فقط (لذا لا توجد أية قيم مكررة في القائمة).
* <code>stopOnFalse</code>: مقاطعة الاستدعاءات عندما يعيد رد النداء القيمة <code>false</code>.
ستسلك قائمة ردود النداء افتراضيًّا سلوكًا مماثلًا لقائمة ردود نداء الأحداث ويمكن إطلاقها مرات عديدة.

تفحَّص الأمثلة التالية لمعرفة كيفيَّة استعمال الوسيط <code>flags</code> بشكل صحيح:
* ‎<code>$.Callbacks( "once" )‎</code>
<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks( "once" );
callbacks.add( fn1 );
callbacks.fire( "مرحبًا" );
callbacks.add( fn2 );
callbacks.fire( "أهلًا" );
callbacks.remove( fn2 );
callbacks.fire( "مرحبًا مجددًا" );
 
/*
ستظهر النتيجة:
مرحبًا
*/
</syntaxhighlight>
* <code>‎$.Callbacks( "memory" )‎</code>:
<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks( "memory" );
callbacks.add( fn1 );
callbacks.fire( "مرحبًا" );
callbacks.add( fn2 );
callbacks.fire( "أهلًا" );
callbacks.remove( fn2 );
callbacks.fire( "كيف الحال" );
 
/*
ستظهر النتيجة:
مرحبًا
مرحبًا :fn2 يقول
أهلًا
أهلًا :fn2 يقول
مرحبًا مجددًا
*/

</syntaxhighlight>
* ‎<code>$.Callbacks( "unique" )‎</code>:
<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks( "unique" );
callbacks.add( fn1 );
callbacks.fire( "مرحبًا" );
callbacks.add( fn1 ); // إضافته مرة أخرى
callbacks.add( fn2 );
callbacks.fire( "أهلًا" );
callbacks.remove( fn2 );
callbacks.fire( "مرحبًا مجددًا" );
 
/*
ستظهر النتيجة:
مرحبًا
أهلًا
أهلًا :fn2 يقول
مرحبًا مجددًا
*/

</syntaxhighlight>
* ‎<code>$.Callbacks( "stopOnFalse" )‎</code>:
<syntaxhighlight lang="javascript">
function fn1( value ) {
  console.log( value );
  return false;
}
 
function fn2( value ) {
  fn1( "يقول fn2: " + value );
  return false;
}
 
var callbacks = $.Callbacks( "stopOnFalse" );
callbacks.add( fn1 );
callbacks.fire( "مرحبًا" );
callbacks.add( fn2 );
callbacks.fire( "أهلًا" );
callbacks.remove( fn2 );
callbacks.fire( "مرحبًا مجددًا" );
 
/*
ستظهر النتيجة:
مرحبًا
أهلًا
مرحبًا مجددًا
*/
</syntaxhighlight>بما أنَّ ‎<code>$.Callbacks()</code>‎ تدعم قائمة من الرايات عوضًا عن رايةٍواحدة، فإنَّ تعيين عدة رايات في آنٍ واحدٍ له تأثير تراكمي مشابه لتأثير "<code>&&</code>". أي من الممكن الدمج بين الرايات لإنشاء قائمة ردود نداء فريدة والتأكد من أنَّ القائمة قد أُطلقت مسبقًا، ويؤدي إضافة المزيد من ردود النداء إلى استدعائها مع أحدث القيم المُطلَقَة (مثل استعمال ‎<code>$.Callbacks("unique memory")</code>‎).
* <code>‎$.Callbacks( 'unique memory' )</code>‎:
<syntaxhighlight lang="javascript">
function fn1( value ) {
  console.log( value );
  return false;
}
 
function fn2( value ) {
  fn1( "يقول fn2: " + value );
  return false;
}
 
var callbacks = $.Callbacks( "unique memory" );
callbacks.add( fn1 );
callbacks.fire( "مرحبًا" );
callbacks.add( fn1 ); // إضافته مرة أخرى
callbacks.add( fn2 );
callbacks.fire( "أهلًا" );
callbacks.add( fn2 );
callbacks.fire( "كيف الحال" );
callbacks.remove( fn2 );
callbacks.fire( "الحمد لله" );
 
/*
ستظهر النتيجة:
مرحبًا
مرحبًا :fn2 يقول
أهلًا
أهلًا :fn2 يقول
كيف الحال
كيف الحال :fn2 يقول
الحمد لله
*/
</syntaxhighlight>دمج الرايات مع ‎<code>$.Callbacks()</code>‎ مدعومٌ داخليًّا في jQuery للدالة <code>[[jQuery/deferred/done|‎.done()‎]]</code> والدالة <code>[[jQuery/deferred/fail|‎.fail()]]</code>‎ في الكائن المؤجَّل <code>[[jQuery/deferred|Deferred]]</code>، إذ يستعمل كلاهما ‎<code>$.Callbacks('memory once')‎</code>.

يمكن أيضًا فك ارتباط توابع ‎<code>[[jQuery/callbacks|$.Callbacks]]</code>، وتصبح الحاجة لذلك مُلحَّةً عندما تحتاج إلى تعريف إصدارات مختزلة للسهولة:<syntaxhighlight lang="javascript">
var callbacks = $.Callbacks(),
  add = callbacks.add,
  remove = callbacks.remove,
  fire = callbacks.fire;
 
add( fn1 );
fire( "مرحبًا يا صديق" );
remove( fn1 );

</syntaxhighlight>

=== التابع ‎<code>$.Callbacks</code> والتابع ‎<code>$.Deferred</code>، والنشر/الاشتراك ===
الفكرة العامة القابعة خلف النشر/الاشتراك (pub/sub أو نمط المراقبة) هي تعزيز الاقتران الرخو (loose coupling) في التطبيقات. فبدلًا من استدعاء كائنات وحيدة مع توابع لكائنات أخرى، يشترك كائنٌ بمهمة أو نشاط محدَّد لكائن آخر ويُنبَّه عندما يحدث ذلك. المراقبون يُدعَون أيضًا بأنَّهم مشتركون، ونشير إلى الكائن المُراقِب على أنَّه ناشر (Publisher أو الفاعل [subject])؛ فيُنبِّه الناشرون المشتركين عند وقوع الأحداث.

لإظهار إمكانيات مكوِّن الإنشاء (component-creation) للدالة ‎<code>$.Callbacks()</code>‎، يمكن تنفيذ نظام النشر/الاشتراك باستعمال قوائم ردود النداء فقط. عند استعمال ‎<code>$.Callbacks</code> كصفوف (topics) في الطابور، يمكن أن يُنفَّذ نظامٌ للنشر والاشتراك بتلك الصفوف كما موضَّح في الشيفرة التالية:<syntaxhighlight lang="javascript">
var topics = {};
 
jQuery.Topic = function( id ) {
  var callbacks, method,
    topic = id && topics[ id ];
 
  if ( !topic ) {
    callbacks = jQuery.Callbacks();
    topic = {
      publish: callbacks.fire,
      subscribe: callbacks.add,
      unsubscribe: callbacks.remove
    };
    if ( id ) {
      topics[ id ] = topic;
    }
  }
  return topic;
};
</syntaxhighlight>يمكن استخدام هذه الشيفرة لتكون جزءًا من تطبيقك للنشر والاشتراك بالأحداث التي تريدها بسهولة كبيرة:<syntaxhighlight lang="javascript">
// مشتركون
$.Topic( "mailArrived" ).subscribe( fn1 );
$.Topic( "mailArrived" ).subscribe( fn2 );
$.Topic( "mailSent" ).subscribe( fn1 );
 
// ناشرون
$.Topic( "mailArrived" ).publish( "مرحبًا يا صديق" );
$.Topic( "mailSent" ).publish( "رائع! إنه بريد" );
 
// fn2 و fn1 هنا، تُدفَع "مرحبًا يا صديق" إلى  
// "mailArrived" عندما ينشر التنبيه
// fn1 تُدفَع أيضًا العبارة "رائع! إنه بريد" إلى
//"mailSent" عندما ينشر التنبيه 
 
/*
ستظهر النتيجة::
مرحبًا يا صديق
مرحبًا يا صديق :fn2 يقول: hello world!
رائع! إنه بريد
*/
</syntaxhighlight>ستجد أنَّ هذا مفيدٌ ويمكن الوصول إلى حدود أبعد مما تتخيل. فباستعمال ‎<code>[[jQuery/deferred|$.Deferreds]]</code>، يمكن التأكد من أنَّ الناشرين ينشرون التنبيهات للمشتركين فقط حالما تكتمل مهام معيَّنة (تكون مقبولة [resolved]). تَفحَّص الشيفرة التالية التي تعدُّ نموذجًا يشرح كيفيَّة تطبيق هذا الأمر:<syntaxhighlight lang="javascript">
// mailArrived الاشتراك بالتنبيهات
$.Topic( "mailArrived" ).subscribe( fn1 );
 
// Deferreds إنشاء نسخة جديدة من الكائن
var dfd = $.Deferred();
 
// دون النشر بشكل مباشرة topic تعريف صف
var topic = $.Topic( "mailArrived" );
 
// عندما يقبل الكائن المؤجل، تنشر 
// تنشر التنبيهات إلى المشتركين
dfd.done( topic.publish );
 
// الكائن المؤجل الذي بصدد قبوله مع رسالة
// سيعاد إرسال هذه الرسالة إلى المشتركين. من الممكن دمج هذا 
// ليكتمل) وبذلك Ajax السلوك بسهولة مع نمط أكثر تعقيدًا (مثل انتظار استدعاء
// تُنشَر الرسائل عندما تنتهي المهمة فعليًّا فقط
dfd.resolve( "لقد نشرت الرسالة" );
</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/jQuery.Callbacks/ صفحة التابع Callbacks في توثيق jQuery الرسمي.]
[[تصنيف:jQuery]]
[[تصنيف:jQuery Callbacks Object]]