jQuery/bind

‎.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() );
});