التابع ‎.bind()‎‎ في jQuery

‎.bind( eventType [, eventData ], handler )‎

القيمة المعادة

كائن jQuery.

أُهمِل هذا التّابع في الإصدار: 3.0.

الوصف

يُستخدَم التّابع ‎.bind()‎ في إرفاق مُعالِج أحداث (Event handler) لحدثٍ ما للعناصر.

‎.bind( eventType [, eventData ], handler )‎

أضيفت في الإصدار: 1.0.

eventType

سلسلة نصيّة، وتُمثِّل أنواع حدث DOM مثل click، أو submit، أو أسماء مُخصَّصة للأحداث.

eventData

أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيّة استخدام أي نوع)، ويُمثِّل كائن يحتوي على البيانات التي ستُمرَّر إلى مُعالِج الأحداث.

handler

دالة على الشكل ‎Function( Event eventObject )‎، وتُمثِّل الدالة التي ستُنفَّذ في كل مرة يُطلَق فيها الحدث.

‎.bind( eventType [, eventData ] [, preventBubble ] )‎

أضيفت في الإصدار: 1.4.3.

eventType

سلسلة نصيّة، وتُمثِّل أنواع حدث DOM مثل click، أو submit، أو أسماء مُخصَّصة للأحداث.

eventData

أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيّة استخدام أي نوع)، ويُمثِّل كائن يحتوي على البيانات التي ستُمرَّر إلى مُعالِج الأحداث.

preventBubble

قيمة منطقيّة، يُؤدِّي تعيين هذا الوسيط إلى القيمة false إلى إرفاق دالة تمنع حدوث السّلوك الأساسي وتُوقف الحدث من التفاقم (bubbling)، القيمة الافتراضيّة هي true.

‎.bind( events )‎

أضيفت في الإصدار: 1.4.

events

كائن (Object)، ويُمثِّل كائنًا يحوي على واحد أو أكثر من أنواع أحداث DOM ودوال لتنفيذها من أجل كل حدث.

أُهمِل التّابع ‎.bind()‎ بدءًا من إصدار jQuery 3.0، وحلّ محلّه التّابع ‎.on()‎ لإرفاق مُعالِجات الأحداث إلى المستند منذ الإصدار 1.7، لذا كان من غير المُفضَّل استخدامه مُسبقًا. بالنسبة للإصدارات الأقدم كان التّابع ‎.bind()‎ مُستخدَمًا في إرفاق مُعالِج الأحداث مباشرةً إلى العناصر، حيث تُرفَق مُعالِجات الأحداث إلى العنصر المُحدَّد حاليًّا في الكائن jQuery، لذا كان من الإجباري وجود هذه العناصر عند حدوث استدعاء التّابع ‎.bind()‎ . للحصول على مرونة أكبر في ربط الأحداث انظر إلى المناقشة حول تفويض الأحداث في صفحة التّابع ‎.on()‎ .

تصلح أي سلسلة نصيّة من أجل الوسيط eventType إن لم تكن اسمًا لحدث أصلي في DOM، وحينها يُقيَّد مُعالِج الأحداث إلى حدث مُخصَّص. لا تستدعى هذه الأحداث إطلاقًا من قبل المتصفّح، ولكن يُمكِن إطلاقها يدويًّا من خلال شيفرة JavaScript أخرى باستخدام التّابع ‎.trigger()‎ أو ‎.triggerHandler()‎.

إن كانت السلسلة النصيّة المُمرَّرة للوسيط eventType تحتوي على محرف النقطة (.)، فستُخصَّص له مساحة اسم (namespace). يفصل مَحرَف النقطة الحدث عن مساحة الاسم الخاصّة به، فعلى سبيل المثال في الاستدعاء ‎.bind( "click.name", handler )‎ تُمثِّل السلسلة النصيّة click نوع الحدث، والسلسلة النصيّة name مساحة الاسم. تسمح مساحات الأسماء بفك ربط أو إطلاق بعض أنواع الأحداث بدون التأثير على الأنواع الأخرى، للمزيد من المعلومات انظر إلى توثيق ‎.unbind()‎.

تُوجَد توابع مُختصرَة لأجل بعض الأحداث المعياريّة للمتصفّح مثل ‎.click()‎ والتي يُمكِن استخدامها لإرفاق أو إطلاق مُعالِجات الأحداث، وللحصول على قائمة كاملة بهذه التوابع المُختصرَة انظر إلى التصنيف events.

عندما يصل الحدث إلى العنصر فستُطلَق كافّة مُعالِجات الأحداث المربوطة بنوع الحدث هذا، وإن كان هنالك عدّة مُعالِجات أحداث مُسجَّلة فستُنفَّذ دومًا بالترتيب التي رُبِطَت فيه. وبعد أن تُنفَّذ جميع مُعالِجات الأحداث سيستمر الحدث في مسار انتشار الحدث الاعتيادي.

مثال بسيط على استخدام التّابع ‎.bind()‎:

$( "#foo" ).bind( "click", function() {
  alert( "ضغط المستخدم على العنصر ذو المُعرِّف foo" );
});

تُؤدِّي هذه الشيفرة إلى استجابة العنصر الذي يمتلك المُعرِّف foo إلى الحدث click، فعندما يضغط المستخدم بداخل العنصر ستظهر رسالة التنبيه.

أحداث متعددة

يُمكِن ربط أنواع الأحداث المتعددة دفعةً واحدةً بتضمين كل واحدة منها مع الفصل بينها بمسافة فارغة:

$( "#foo" ).bind( "mouseenter mouseleave", function() {
  $( this ).toggleClass( "entered" );
});

يكون تأثير هذه الشيفرة على العنصر <div id="foo"> (عندما لا يمتلك الصنف entered بشكل مبدئي) هو إضافة الصنف entered عندما تدخل الفأرة مجال العنصر <div> وإزالة هذا الصّنف عندما تغادره. بإمكاننا بدءًا من إصدار jQuery 1.4 أن نربط العديد من مُعالِجات الأحداث بشكل متزامن عن طريق تمرير كائن من الأزواج نوع الحدث\مُعالِج الحدث:

$( "#foo" ).bind({
  click: function() {
    // فعل شيء عند النقرة
  },
  mouseenter: function() {
    // فعل شيء عند دخول الفأرة مجال العنصر
  }
});

مُعالِجات الأحداث

يأخذ المُعامِل handler دالة استدعاء كما رأينا سابقًا، تُشير الكلمة المفتاحيّة this داخل مُعالِج الأحداث إلى عنصر DOM المربوط إليه مُعالِج الأحداث، وللاستفادة من العنصر في jQuery يُمكِن تمريره إلى دالة ‎$()‎ الاعتياديّة، كما يلي:

$( "#foo" ).bind( "click", function() {
  alert( $( this ).text() );
});

بعد تنفيذ هذه الشيفرة، عندما يضغط المستخدم بداخل العنصر ذي المُعرِّف foo، فستظهر محتوياته النصيّة على شكل رسالة تنبيه.

بدءًا من إصدار jQuery 1.4.2 يُمكِننا ربط مُعالِجات الأحداث المُكرَّرة إلى العنصر بدلًا من تجاهلها. يُفيدنا هذا عند استخدام ميزة بيانات الحدث أو عند وجود بيانات فريدة تقع على مقربة من دالة مُعالِج الحدث.

بإمكاننا في إصدار jQuery 1.4.3 تمرير القيمة false مكان مُعالِج الحدث، سيربط هذا مُعالِج الحدث مُكافِئ لـ ‎function(){ return false; }‎ ، ويُمكِن إزالة هذه الدالة لاحقًا عن طريق استدعاء ‎.unbind( eventName, false )‎.

كائن الحدث

تستطيع دالة الاستدعاء handler أن تأخذ مُعامِلات أيضًا، عندما تُستَدعَى الدالة فسيُمرَّر كائن الحدث إلى المُعامِل الأول.

يكون كائن الحدث غالبًا غير ضروري ويُحذَف المُعامِل الخاص به، حيث يكون السّياق كافيًا عند ربط مُعالِج الحدث لمعرفة ما الذي يجب القيام به بالضبط عند إطلاق مُعالِج الحدث، ولكن أحيانًا يُصبِح من الضروري جمع المزيد من المعلومات حول بيئة المستخدم وقت تهيئة الحدث، انظر إلى كائن الحدث.

يُكافِئ إعادة القيمة false من مُعالِج الحدث استدعاء التّابعين ‎.preventDefault()‎ و ‎.stopPropagation()‎ على كائن الحدث.

يكون استخدام كائن الحدث في مُعالِج الحدث مُماثلًا لما يلي:

$( document ).ready(function() {
  $( "#foo" ).bind( "click", function( event ) {
    alert( "إحداثيات مؤشر الفأرة هي (" +
      event.pageX + ", " + event.pageY +
      ")" );
  });
});

لاحظ المُعامِل المُضاف إلى الدالة المجهولة (anonymous function). تُؤدِّي هذه الشيفرة عند النقر على العنصر ذي المُعرِّف foo إلى الإعلام عن إحداثيَّات مُؤشِّر الفأرة وقت النقرة.

تمرير بيانات الحدث

لا يُستخدَم المُعامِل eventData الخياري بشكل شائع، وهو يسمح عند تزويده بتمرير معلومات إضافيّة إلى مُعالِج الأحداث. من الاستخدامات المفيدة له هو الالتفاف على بعض المشاكل، فلنفرض مثلًا أنّنا نملك مُعالِجين للأحداث يُشير كلاهما إلى نفس المتغير الخارجي:

var message = "أحمر";
$( "#foo" ).bind( "click", function() {
  alert( message );
});
message = "أزرق";
$( "#bar" ).bind( "click", function() {
  alert( message );
});

سيعرض كلا مُعالِجي الأحداث الرسالة "أزرق" عند إطلاقهما، حيث تغيّرت قيمة المتغيّر message. ولتجاوز هذا نُمرِّر الرسالة باستخدام eventData:

var message = "أحمر";
$( "#foo" ).bind( "click", {
  msg: message
}, function( event ) {
  alert( event.data.msg );
});
message = "أزرق";
$( "#bar" ).bind( "click", {
  msg: message
}, function( event ) {
  alert( event.data.msg );
});

في هذه المرّة لم يُشَر إلى المتغير بشكل مباشر ضمن مُعالِج الحدث، بل مرّرنا بدلًا من ذلك قيمة هذا المتغير عبر eventData والذي يُصلِح القيمة وقت ربط الحدث. سيعرض مُعالِج الحدث الأول القيمة أحمر وسيعرض الثاني القيمة أزرق.

لاحظ أنّ تمرير الكائنات للدوال يكون بواسطة المرجع (by reference) ممّا يُعقِّد الأمور بشكل أكبر.

إن كان المُعامِل eventData موجودًا فهو الوسيط الثاني للتابع ‎.bind()‎، وإن لم تكن هناك أيّة بيانات إضافية في حاجة إلى إرسالها لمُعالِج الأحداث، فسيُمرَّر الاستدعاء كثاني وآخر وسيط.