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

‎.unbind( eventType [, handler ] )‎

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

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

اٌُهمل مع الإصدار: 3.0.

الوصف

إزالة معالج أحداث سبق إرفاقه بالعناصر.

‎.unbind( eventType [, handler ] )‎

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

eventType

سلسلة نصية من النوع String تحتوي على واحد أو أكثر من أنواع أحداث DOM، مثل click أو submit أو أسماء أحداث مخصصة.

handler

الدالة التي سيتوقف تنفيذها وهي على الشكل Function( Event eventObject )‎.

‎.unbind( eventType, false )‎

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

eventType

سلسلة نصية من النوع String تحتوي على واحد أو أكثر من أنواع أحداث DOM، مثل click أو submit أو أسماء أحداث مخصصة.

false

إلغاء ربط الدالة 'return false' المقابلة والمرتبطة باستخدام ‎.bind( eventType, false )‎، وهو من النوع Boolean.

‎.unbind( event )‎‎

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

event

كائن jQuery.Event من النوع Event.

‎.unbind()‎

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

هذا الشكل لا يقبل أي وسائط.

توقف ‎.unbind()‎ بدءًا من الإصدار jQuery 3.0. وحل محله التابع ‎.off()‎ منذ الإصدار jQuery 1.7، لذا كان استخدامه غير محبذ بالفعل.

يمكن إزالة معالجات الأحداث المرفقة مع ‎.bind()‎ باستخدام ‎.unbind()‎. في أبسط الحالات، مع عدم وجود وسائط، يزيل ‎.unbind()‎ جميع المعالجات المتعلقة بالعناصر:

$( "#foo" ).unbind();

يزيل هذا الإصدار المعالجات بغض النظر عن نوعها. يمكننا تمرير نوع الحدث لنكون أكثر دقة:

$( "#foo").unbind( "click" );

عند تحديد نوع حدث click، ستُزال فقط المعالجات من نوع هذا الحدث. ومع ذلك، يمكن أن يكون لهذه الطريقة تداعيات سلبية إذا كانت هناك برامج نصية أخرى يمكن أن تربط سلوكيات أخرى لنفس العنصر. عادةً ما تتطلب التطبيقات الكبيرة الإصدار الذي يقبل الوسيطين لهذا السبب:

var handler = function() {
  alert( "أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ." );
};
$( "#foo" ).bind( "click", handler );
$( "#foo" ).unbind( "click", handler );

يؤكد تمرير المعالجات عدم إزالة أي دوال أخرى عن طريق الخطأ. لاحظ أن ما يلي لن يعمل:

$( "#foo" ).bind( "click", function() {
  alert( "أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ." );
});
 
// لن يعمل
$( "#foo" ).unbind( "click", function() {
  alert( "أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ." );
});

على الرغم من أن الدالتين متطابقتين في المحتوى، إلا أنهما يُنشأن بشكل منفصل ولذا فإن JavaScript ستتعامل معها ككائنات دوال مستقلة. لإبطال معالج معين، نحتاج إلى مرجع إلى تلك الدالة وليس لدالة مختلفة تحدث لعمل الشيء نفسه.

ملاحظة: يؤدي استخدام دالة بالوساطة (proxied) في إلغاء حدث ما على عنصر إلى فك جميع الدوال التي تعمل بالوساطة على هذا العنصر، حيث تُستخدم نفس الدالة الوسيطة لكافة الأحداث التي تعمل بالوساطة. للسماح بإزالة حدث معين، تُستخدم أسماء أصناف فريدة من نوعها في الحدث (على سبيل المثال click.proxy1 و click.proxy2 ) عند إرفاقها.

استخدام مجالات الأسماء (namespaces)

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

$( "#foo" ).bind( "click.myEvents", handler );

عند ارتباط معالج بهذه الطريقة، لا يزال بإمكاننا إزالته بالطريقة العادية:

$( "#foo" ).unbind( "click" );

ومع ذلك، فإذا أردنا تجنب التأثير على معالجات أخرى، فيمكن أن نكون أكثر تحديدًا:

$( "#foo" ).unbind( "click.myEvents" );

يمكننا أيضًا إزالة جميع المعالجات في مجال الاسم، بغض النظر عن نوع الحدث:

$( "#foo" ).unbind( ".myEvents" );

من المفيد بشكل خاص إرفاق مجالات الأسماء بعمليات ربط الأحداث عند تطوير المكونات الإضافية أو كتابة الشيفرات البرمجية التي قد تتفاعل مع شيفرات معالجات الأحداث الأخرى في المستقبل.

استخدام كائن الحدث

يستخدم الشكل الثالث من التابع ‎.unbind()‎ عندما نرغب في ازالة معالج من داخل نفسه. على سبيل المثال، لنفترض أننا نرغب في تشغيل معالج أحداث ثلاث مرات فقط:

var timesClicked = 0;
$( "#foo" ).bind( "click", function( event ) {
  alert( "أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ." );
  timesClicked++;
  if ( timesClicked >= 3 ) {
    $( this ).unbind( event );
  }
});

يجب أن يأخذ المعالج في هذه الحالة معامل، بحيث يمكن التقاط كائن الحدث واستخدامه لإزالة المعالج بعد النقرة الثالثة. يحتوي كائن الحدث على السياق الضروري للتابع ‎.unbind()‎ لمعرفة المعالج المطلوب إزالته. هذا المثال هو أيضا مثال على تعبير مغلق (closure). بما أن المعالج يشير إلى متغير timesClicked، والذي يُعرّف خارج الدالة، فإن زيادة المتغير لها تأثير حتى بين عمليات استدعاء المعالج.

أمثلة

يمكن ربط الأحداث بالزر الملون ثم إزالتها منه.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>unbind demo</title>
  <style>
  button {
    margin: 5px;
  }
  button#theone {
    color: red;
    background: yellow;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button id="theone">لا يحدث شيء...</button>
<button id="bind">ربط النقر</button>
<button id="unbind">إزالة النقر</button>
<div style="display:none;">انقر!</div>
 
<script>
function aClick() {
  $( "div" ).show().fadeOut( "slow" );
}
$( "#bind" ).click(function() {
  $( "#theone" )
    .bind( "click", aClick )
    .text( "يمكن النقر!" );
});
$( "#unbind" ).click(function() {
  $( "#theone" )
    .unbind( "click", aClick )
    .text( "لا يحدث شيء..." );
});
</script>
 
</body>
</html>

لإزالة جميع الأحداث من جميع الفقرات <p>:

$( "p" ).unbind();

لإزالة جميع أحداث النقر من جميع الفقرات <p>:

$( "p" ).unbind( "click" );

لإزالة ارتباط معالج واحد سبق ارتباطه، تُمرر الدالة كوسيط ثاني:

var foo = function() {
  // شيفرة للتعامل مع نوع من الأحداث
};
 
$( "p" ).bind( "click", foo ); // ... الآن سيستدعى foo عند النقر فوق الفقرات ...
 
$( "p" ).unbind( "click", foo ); // ... لن يستدعى foo بعد الآن.

مصادر

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