التابع .delegate() في jQuery
.delegate( selector, eventType, handler )
أُهمِل مع الإصدار: 3.0.
القيمة المعادة
يُعيد كائنًا من النوع jQuery.
الوصف
يُرفق هذا التابع معالج بأحد الأحداث أو أكثر لكافة العناصر التي تطابق المُحدِد، الآن أو في المستقبل، استنادًا إلى مجموعة محددة من العناصر الجذر.
.delegate( selector, eventType, handler )
أُضيف مع الإصدار: 1.4.2.
selector
سلسلة نصية تُحدد ترشيح العناصر التي تبدأ الحدث من النوع String.
eventType
سلسلة نصية تحتوي على واحد أو أكثر من أنواع أحداث JavaScript مفصولة بمسافات، مثل "click"، أو "keydown,"، أو أسماء أحداث مخصصة.
handler
دالة معالجة أحداث تُنفَّذ في وقت تشغيل الحدث، وهي من الشكل Function( Event eventObject ).
.delegate( selector, eventType, eventData, handler )
أُضيف مع الإصدار: 1.4.2.
selector
سلسلة نصية تُحدد ترشيح العناصر التي تبدأ الحدث من النوع String.
eventType
سلسلة نصية تحتوي على واحد أو أكثر من أنواع أحداث JavaScript مفصولة بمسافات، مثل "click"، أو "keydown,"، أو أسماء أحداث مخصصة.
eventData
كائن يحتوي على البيانات التي ستُمرر إلى مداول الحدث، ويمكن أن يكون من أي نوع من أنواع JavaScript.
handler
دالة معالجة أحداث تُنفَّذ في وقت تشغيل الحدث، وهي من الشكل Function( Event eventObject ).
.delegate( selector, events )
أُضيف مع الإصدار: 1.4.3.
selector
سلسلة نصية تُحدد ترشيح العناصر التي تبدأ الحدث، وهي من النوع String.
events
كائن بسيط من النوع Object لواحد أو أكثر من أنواع الأحداث والدوال لتنفيذها.
أهمل التابع .delegate() اعتبارًا من إصدار jQuery 3.0. وحل محله التابع .on() منذ الإصدار jQuery 1.7، لذلك كان من المحبذ عدم استعماله. ومع ذلك، سيبقى هذا التابع هو الوسيلة الأكثر فعالية لاستخدام تفويض الحدث في الإصدارات السابقة. مزيد من المعلومات حول ربط الحدث والتفويض في صفحة توثيق التابع .on(). بشكل عام، هذه هي القوالب المُكافِئة للتابعَين:
// jQuery 1.4.3+
$( elements ).delegate( selector, events, data, handler );
// jQuery 1.7+
$( elements ).on( events, selector, data, handler );
على سبيل المثال ، الشيفرة البرمجية التالية للتابع .delegate():
$( "table" ).delegate( "td", "click", function() {
$( this ).toggleClass( "chosen" );
});
تعادل الشيفرة التالية المكتوبة باستخدام التابع .on():
$( "table" ).on( "click", "td", function() {
$( this ).toggleClass( "chosen" );
});
لإزالة الأحداث المرفقة مع التابع .delegate()، راجع التابع .undelegate()، وهو يُمرر بيانات الأحداث ويعالجها بنفس الطريقة التي يعمل بها التابع .on().
ملاحظات إضافية
نظرًا لأن التابع .live() يعالج الأحداث بمجرد انتشارها (propagate) إلى أعلى المستند، فلا يمكن إيقاف انتشار أحداث live. وبالمثل، فإن الأحداث التي يعالجها التابع .delegate() سوف تنتشر إلى العناصر المفوَّضَة؛ وستُنفَّذ معالجات الأحداث المرتبطة بأي عناصر تحتها في شجرة DOM في الوقت الذي يُستدعى فيه معالج الحدث المفوَّض. لذلك، قد تمنع هذه المعالجات المعالجَ المفوَّض من التشغيل عن طريق استدعاء event.stopPropagation() أو إعادة false.
أمثلة
انقر على فقرة <p> لإضافة أخرى. لاحظ أن .delegate() يُرفِق معالج للحدث click مع كافة الفقرات، حتى تلك التي لم تضف بعد:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>delegate مثال على التابع</title>
<style>
p {
background: yellow;
font-weight: bold;
cursor: pointer;
padding: 5px;
}
p.over {
background: #ccc;
}
span {
color: red;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>أنقر هما!</p>
<span></span>
<script>
$( "body" ).delegate( "p", "click", function() {
$( this ).after( "<p>فقرة أخرى!</p>" );
});
</script>
</body>
</html>
لعرض نص كل فقرة في مربع تنبيه عند النقر عليه:
$( "body" ).delegate( "p", "click", function() {
alert( $( this ).text() );
});
لإلغاء إجراء افتراضي ومنعه من الانتشار إلى الأعلى (النمط bubble)، فأعد القيمة false من الدالة:
$( "body" ).delegate( "a", "click", function() {
return false;
});
أما لإلغاء الإجراء الافتراضي باستخدام التابع preventDefault فقط:
$( "body" ).delegate( "a", "click", function( event ) {
event.preventDefault();
});
يمكن ربط الأحداث المخصصة (custom events) أيضًا:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>delegate مثال على التابع</title>
<style>
p {
color: red;
}
span {
color: blue;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<p>مرفق معه حدث مخصص.</p>
<button>إطلاق حدث مخصص</button>
<span style="display:none;"></span>
<script>
$( "body" ).delegate( "p", "myCustomEvent", function( e, myName, myValue ) {
$( this ).text( "مرحبًا!" );
$( "span" )
.stop()
.css( "opacity", 1 )
.text( "اسمي = " + myName )
.fadeIn( 30 )
.fadeOut( 1000 );
});
$( "button" ).click(function() {
$( "p" ).trigger( "myCustomEvent" );
});
</script>
</body>
</html>