jQuery/live

‎.live( events, handler )‎

أهمل مع الإصدار: 1.7، وحذف مع الإصدار: 1.9.

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

يعيد كائنًا من النوع jQuery.

الوصف

يربط هذا التابع معالج حدث معين بجميع العناصر التي طابقت المحدِّد الحالي الآن وفي المستقبل.

‎.live( events, handler )‎

أُضيف مع الإصدار: 1.3.

events

سلسلة نصية تحتوي على نوع حدث JavaScript مثل "click" أو "keydown". يمكن للسلسلة النصية بدءًا من الإصدار jQuery 1.4 أن تحتوي على أنواع أحداث متعدِّدة مفصولةً بمسافة فارغة، أو أسماء أحداث مخصَّصة.

handler

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

‎.live( events [, data ], handler )‎

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

events

سلسلة نصية تحتوي على نوع الحدث في JavaScript مثل "click" أو "keydown". يمكن للسلسلة النصية بدءًا من الإصدار jQuery 1.4 أن تحتوي على أنواع أحداث متعددة مفصولة بمسافة فارغة، أو أسماء أحداث مخصَّصة.

data

كائن مجرد (Object) يحتوي على البيانات التي ستُمرَّر إلى معالج الحدث.

handler

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

‎.live( events )‎

events

كائن مجرد لنوع واحد أو أكثر من أنواع أحداث JavaScript ودوال لتنفيذ تلك الأحداث.

بدءًا من الإصدار jQuery 1.7، أهمل التابع ‎.live()‎، وحل مكانه التابع ‎.on()‎ لربط معالجات الأحداث. يجب على مستخدمي إصدارات jQuery القديمة استعمال التابع ‎.delegate()‎ إذ له أفضلية على التابع ‎.live()‎.

يوفر هذا التابع وسيلة لربط معالجات الحدث المفوَّضة بالكائن document التابع للصفحة والذي يبسِّط استعمال معالجات الحدث عندما يضاف المحتوى بشكل ديناميكي إلى الصفحة. راجع للمزيد من المعلومات حول الموازنة بين الأحداث المفوَّضة (delegated events) مع الأحداث المباشرة (direct events) في توثيق التابع ‎.on()‎.

يوجد تابعان يشبهان التابع ‎.live()‎ ويمكن استعمالهما عوضًا عنه في الإصدارات اللاحقة. ستوضح الشيفرة التالية نموذج عن استعمال مماثل لتوابع ربط الأحداث تلك الثلاثة:

$( selector ).live( events, data, handler );                // jQuery 1.3+
$( document ).delegate( selector, events, data, handler );  // jQuery 1.4.3+
$( document ).on( events, selector, data, handler );

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

$( "a.offsite" ).live( "click", function() {
  alert( "Goodbye!" ); // jQuery 1.3+
});
$( document ).delegate( "a.offsite", "click", function() {
  alert( "Goodbye!" ); // jQuery 1.4.3+
});
$( document ).on( "click", "a.offsite", function() {
  alert( "Goodbye!" );  // jQuery 1.7+
});

لم يعد يُنصح باستعمال التابع ‎.live()‎ منذ أن وفرت إصدارات jQuery اللاحقة توابع أفضل منه ولا تحتوي على عيوبه. ظهرت المشكلات التالية على وجه الخصوص تزامنًا مع استعمال التابع ‎.live()‎:

• تحاول jQuery استرجاع العناصر التي اختارها المحدِّد قبل استدعاء التابع ‎.live()‎، وهذا قد يعدُّ هدرًا للوقت في الصفحات الكبيرة.
• استخدام سلسلة من  التوابع هو أمرٌ غير مدعوم. الشكل ‎$( "a" ).find( ".offsite, .external" ).live( ... );‎ مثلًا غير صحيح ولن يعمل بالشكل المتوقع له.
• لما كانت جميع أحداث التابع ‎.live()‎ مرتبطة بالعنصر document، فإنَّ الأحداث تسلك أطول وأبطأ مسار محتمل قبل أن تُعالج.
• لا ينتقل الحدث click في الأجهزة المحمولة (mobile) ذات النظام iOS (مثل iPhone أو iPad أو iPod Touch) إلى جسم الصفحة لأغلب العناصر، ولا يمكن استعماله آنذاك مع التابع ‎.live()‎ دون تطبيق أحد الحلول التالية:
  • استعمال عناصر أساسية قابلة للضغط مثل العنصر والعنصر <button> إذ ينقل كلاهما الحدث إلى العنصر document.
  • استعمال ‎.on()‎ أو ‎.delegate()‎ المرتبطة بالعنصر في مستوى أدنى من document.body بما أن أجهزة iOS المحمولة لا تنقل الحدث في جسم الصفحة.
  • تطبيق تنسيق CSS وهو cursor: pointer على العنصر الذي يريد نقل الأحداث click (أو على العنصر الأب من ضمنه document.documentElement). انتبه إلى أنَّ ذلك سيعطل خاصيَّة النسخ واللصق في العنصر، وسيسبب في تمييزه (highlighted) عند الضغط عليه.
• ليس لاستدعاء event.stopPropagation()‎ في معالج الحدث أثر في إيقاف معالجات الحدث المرتبطة في المستويات الدنيا في الصفحة، إذ يكون الحدث قد انتشر مسبقًا إلى document.
• يتفاعل التابع ‎.live()‎ مع توابع أحداث أخرى في عدة طرائق يمكنها أن تفاجئك مثل ‎$( document ).off( "click" )‎ الذي يزيل جميع معالجات الحدث click المرتبطة باستعمال أي استدعاءٍ للتابع ‎.live()‎.

بالنسبة للصفحات التي ما تزال تستعمل التابع ‎.live()‎، فهذه قائمة باختلافات بعض الإصدارات والتي قد تكون مفيدة:

• قبل الإصدار jQuery 1.7 ولإيقاف تنفيذ معالجات إضافية بعد ارتباط واحد باستعمال التابع ‎.live()‎، يجب على المعالج إعادة القيمة false. لن يحل استدعاء التابع ‎.stopPropagation()‎ هذه المشكلة.
• بدءًا من الإصدار jQuery 1.4، أصبحت التابع ‎.live()‎ يدعم أحداث مخصصة بالإضافة إلى جميع أحداث JavaScript التي تنتشر؛ ويدعم أيضًا بعض الأحداث التي لا تنتشر من ضمنها الحدث change، والحدث submit، والحدث focus، والحدث blur.
• في إصدارات jQuery 1.3.x، أحداث Javascript التالية يمكنها الارتباط فقط وهي: الحدث click، والحدث dblclick، والحدث keydown، والحدث keypress، والحدث keyup، والحدث mousedown، والحدث mousemove، والحدث mouseout، والحدث mouseover، والحدث mouseup.

أمثلة

إلغاء السلوك الافتراضي ومنعه من الإنتشار للأعلى بإعادة القيمة false:

$( "a" ).live( "click", function() {
 return false;
});

إلغاء السلوك الافتراضي فقط باستعمال التابع ‎.preventDefault()‎:

$( "a" ).live( "click", function( event ) {
 event.preventDefault();
});

ربط أحداث مخصصة باستعمال التابع ‎.live()‎:

$( "p" ).live( "myCustomEvent", function( event, myName, myValue ) {
  $( this ).text( "Hi there!" );
  $( "span" )
    .stop()
    .css( "opacity", 1 )
    .text( "myName = " + myName )
    .fadeIn( 30 )
    .fadeOut( 1000 );
  });
$( "button" ).click(function() {
  $( "p" ).trigger( "myCustomEvent" );

استعمال كائن لربط معالجات أحداث متعددة. لاحظ أنَّ التابع ‎.live()‎ يستدعي معالجات الحدث click، والحدث mouseover، والحدث mouseout لجميع الفقرات حتى الجديدة منها.

$( "p" ).live({
  click: function() {
    $( this ).after( "<p>Another paragraph!</p>" );
  },
  mouseover: function() {
    $( this ).addClass( "over" );
  },
  mouseout: function() {
    $( this ).removeClass( "over" );
  }
});

مصادر

• صفحة التابع ‎‎.live()‎ في توثيق jQuery الرسمي.