التابع .off() في jQuery
.off( events [, selector ] [, handler ] )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يزيل هذا التابع معالج حدث معين.
.off( events [, selector ] [, handler ] )
أُضيف مع الإصدار: 1.7.
events
سلسلة نصية تحتوي على نوع حدث واحد، أو عدَّة أنواع أحداث مفصولة بمسافة فارغة بالإضافة إلى مجال الاسم (اختياريَّا)، أو مجال الاسم فقط مثل "click"، أو "keydown.myPlugin"، أو ".myPlugin".
selector
سلسلة نصية تمثِّل اسم المحدِّد الذي يجب أن يطابق اسم الحدث الأساسي الذي مُرِّر إلى التابع .on() عندما رُبطت معالجات الحدث.
handler
دالة من الشكل Function( Event eventObject ) وتمثِّل دالة المعالج التي رُبطت مسبقًا بالحدث أو الأحداث أو بالقيمة المخصصة false.
.off( events [, selector ] )
أضيف مع الإصدار 1.7.
events
سلسلة نصية تحتوي على نوع حدث واحد، أو عدَّة أنواع أحداث مفصولة بمسافة فارغة بالإضافة إلى مجال الاسم (اختياريَّا)، أو مجال الاسم فقط مثل "click"، أو "keydown.myPlugin"، أو ".myPlugin".
selector
سلسلة نصية تمثِّل اسم المحدِّد الذي يجب أن يطابق اسم الحدث الأساسي الذي مُرِّر إلى التابع .on() عندما رُبطت معالجات الحدث.
.off( event )
أضيف مع الإصدار 1.7.
event
حدثٌ، وهو كائن من النوع jQuery.Event.
.off()
أضيف مع الإصدار 1.7، وهذا الشكل من التابع لا يقبل أي وسائط.
يُزيل التابع .off() معالجات الحدث التي رُبطت باستعمال التابع .on(). راجع صفحة هذا التابع للمزيد من المعلومات حول الأحداث المفوَّضة (delegated events) والأحداث المرتبطة مباشرةً. يُزيل استدعاء التابع .off() دون وسائط جميع المعالجات المرتبطة بالعناصر. يمكن إزالة معالجات حدث محدَّدة مرتبطة بعنصر بتمرير مجموعة من أسماء الحدث، أو مجالات اسم (namespaces) الحدث، أو أسماء محدِّدات، أو أسماء توابع معالجة. عندما تُعطى عدة وسائط للترشيح، فيجب أن تطابق جميع تلك الوسائط المُعطاة معالج الحدث المراد إزالته.
إن أُعطي اسم الحدث ببساطة مثل "click"، فستُزال جميع الأحداث ذات النوع المعطى سواءً كانت مفوَّضة أم مباشرة من العناصر في مجموعة jQuery. عند كتابة شيفرة ستُستخدم على أنَّها إضافة (plugin) أو عند العمل على شيفرة ذات حجم كبير، فينصح بشدَّة ربط وإزالة معالجات حدثٍ باستعمال مجالات اسم الحدث؛ وبذلك لن تزيل الشيفرة معالجات الحدث المرتبطة بوساطة شيفرات أخرى. يمكن أن تُزال جميع الأحداث من جميع الأنواع في مجال اسم (namespace) محدَّدٍ من عنصرٍ بتمرير مجال الاسم مثل ".myPlugin". يجب على الأقل تمرير مجال اسم أو اسم حدث إلى التابع.
لإزالة معالجات حدث مفوَّض محدَّدة، مرِّر الوسيط selector. يجب أن يطابق اسم المحدِّد المعطى آنذاك تمامًا اسم الحدث الممرر إلى التابع .on() عندما رُبط معالج الحدث حينها. إن أردت إزالة جميع الأحداث المفوَّضة المرتبطة بعنصرٍ دون إزالة الأحداث غير المفوَّضة، فاستعمل **.
يمكن أيضًا إزالة معالج محدَّد وذلك بتحديد اسم الدالة في الوسيط handler. عندما تربط jQuery معالج حدث، فإنَّها تُسند مُعرِّف (id) فريد إلى دالته. ستملك المعالجات الوسيطة (proxied handlers) المرتبطة باستعمال jQuery.proxy() أو أي آلية مشابهة المعرِّف (id) نفسه (مُعرِّف الدالة proxy)، لذا قد يزيل التابع .ff() عند تمرير معالجات مفوَّضة إليه معالجات حدث أكثر مما نريد. في مثل هذه الحالات، يُفضل ربط وإزالة معالجات الأحداث باستعمال مجالات الاسم.
كما هو الحال في التابع .on()، يمكن تمرير الوسيط events ككائن بدلًا من تحديد سلسلة نصية للوسيط events ودالة للوسيط handler وتمريرهما كوسيطين منفصلين. مفاتيح الكائن events هي أحداث و/أو مجالات أسماء؛ أمَّا القيم فهي دوال المعالج أو القيمة false.
أمثلة
إضافة وإزالة معالجات حدث من الزر <button> ذي اللون الأصفر:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>off مثالٌ عن استعمال التابع</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">إضافة الحدث click</button>
<button id="unbind">إزالة الحدث Click</button>
<div style="display:none;">رائع! ضُغط على الزر</div>
<script>
function flash() {
$( "div" ).show().fadeOut( "slow" );
}
$( "#bind" ).click(function() {
$( "body" )
.on( "click", "#theone", flash )
.find( "#theone" )
.text( "اضغط هنا" );
});
$( "#unbind" ).click(function() {
$( "body" )
.off( "click", "#theone", flash )
.find( "#theone" )
.text( "لا يمكنني فعل شيء" );
});
</script>
</body>
</html>
إزالة جميع معالجات الحدث من جميع الفقرات <p>:
$( "p" ).off();
إزالة جميع معالجات الحدث click المفوَّضة من جميع الفقرات <p>:
$( "p" ).off( "click", "**" );
إزالة المعالج الذي رُبط للتو بتمريره كوسيط ثالث:
var foo = function() {
// شيفرة لمعالجة بعض الأحداث
};
// <P> عند الضغط على الفقرة foo ستستدعى
$( "body" ).on( "click", "p", foo );
// مجددًا foo لن تستدعى
$( "body" ).off( "click", "p", foo );
فك ربط معالجات الحدث المفوَّضة عبر مجالات أسمائها:
var validate = function() {
// شيفرة لمدخلات نموذج صالحة
};
// ".validator" أحداث مفوَّضة تحت مجال الاسم
$( "form" ).on( "click.validator", "button", validate );
$( "form" ).on( "keypress.validator", "input[type='text']", validate );
// ".validator" إزالة معالجات الحدث ذات مجال الاسم
$( "form" ).off( ".validator" );