التابع .one() في jQuery
.one( events [, data ], handler )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يربط هذا التابع دالة معالج حدث لحدثٍ واحدٍ أو أكثر بالعناصر المحدَّدة. يُنفَّذ معالج الحدث مرةً واحدةً لكل عنصر ولكل نوع من الأحداث المرتبطة.
.one( events [, data ], handler )
أُضيف مع الإصدار: 1.1.
events
سلسلة نصية تحتوي على نوع حدث واحد أو عدَّة أنواع من أحداث JavaScript مثل "click" أو "submit,".
data
كائن مجرَّد (Object) يحتوي على البيانات التي ستُمرَّر إلى مُعالِج الحدث في event.data عندما يُستدعَى الحدث.
handler
دالة من الشكل Function( Event eventObject ) وتمثِّل الدالة المراد تنفيذها عندما يُستدعَى الحدث.
.one( events [, selector ] [, data ], handler )
أضيف مع الإصدار: 1.7.
events
سلسلة نصية تحتوي على نوع حدث واحد، أو عدَّة أنواع أحداث مفصولة بمسافة فارغة بالإضافة إلى مجال الاسم (اختياريَّا) مثل "click"، أو "keydown.myPlugin".
selector
سلسلة نصية تمثِّل اسم المحدِّد الذي يرشِّح أحفاد (descedants) العناصر المحدَّدة حاليًا التي تستدعي الحدث. إن كانت قيمة هذا الوسيط null أو لم يُعطَ، فسيُتسدعى الحدث دومًا عند الوصول إلى العنصر المحدَّد.
data
أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيَّة استخدام أي نوع)، ويُمثِّل البيانات التي ستُمرَّر إلى مُعالِج الأحداث في event.data عندما يُستدعَى الحدث.
handler
دالة من الشكل Function( Event eventObject ) وتمثِّل الدالة المراد تنفيذها عندما يُستدعى الحدث. يُمكن استعمال القيمة false كاختصارٍ لدالةٍ وظيفتها هي إعادة هذه القيمة (return false).
.one( events [, selector ] [, data ] )
أضيف مع الإصدار: 1.7.
events
كائن مجرَّد (Object) تمثِّل المفاتيح فيه نوعَ حدثٍ واحدٍ أو عدَّة أنواع أحداث مفصولة بمسافة فارغة بالإضافة إلى مجال الاسم (اختياريًّا)، وتمثِّل القيم فيه دالة معالج الحدث المراد تنفيذها عندما يُستدعَى الحدث.
selector
سلسلة نصية تمثِّل اسم المحدِّد الذي يرشِّح أحفاد (descedants) العناصر المحدَّدة حاليًا التي تستدعي الحدث. إن كانت قيمة هذا الوسيط null أو لم يُعطَ، فسيُتسدعى الحدث دومًا عند الوصول إلى العنصر المحدَّد.
data
أي شيء (وهو نوع افتراضي مُستخدَم في jQuery للإشارة إلى إمكانيَّة استخدام أي نوع)، ويُمثِّل البيانات التي ستُمرَّر إلى مُعالِج الأحداث في event.data عندما يُستدعَى الحدث.
التابع .one() مماثل تمامًا للتابع .on() باستثناء أنَّ معالج الحدث للعنصر المعطى يُفك ارتباطه بنوع الحدث بعد استدعائه في المرة الأولى. انظر إلى الشيفرة التالية مثلًا:
$( "#foo" ).one( "click", function() {
alert( "ستظهر هذه الرسالة مرة واحدة فقط." );
});
بعد تنفيذ الشيفرة، سيؤدي الضغط لأول مرة على العنصر ذي المعرِّف "foo" إلى اظهار رسالة تنبيه. الضغط على العنصر في المرات اللاحقة ليس له أي تأثير. هذه الشيفرة تقابل الشيفرة التالية:
$( "#foo" ).on( "click", function( event ) {
alert( "ستظهر هذه الرسالة مرة واحدة فقط." );
$( this ).off( event );
});
بعبارةٍ أخرى، الاستدعاء الصريح للتابع .off() من ضمن معالج الحدث المرتبط له نفس التأثير تمامًا في التابع .off().
إن احتوى الوسيط الأول على أكثر من نوع حدث واحد وكانت مفصولة فيما بينها بفراغ، فسيُستدعى معالج الحدث مرةًَ واحدةًَ لكل نوع من أنواع الأحداث تلك.
$( "#foo" ).one( "click mouseover", function( event ) {
alert( "الحدث " + event.type + " قد وقع فعلًا." );
});
في المثال السابق، ستظهر رسالة التنبيه مرتين لأنَّه مُرِّر إلى التابع حدثين (الحدث click والحدث mouseover).
أمثلة
تغيير شكل كل عنصر <div> عند الضغط عليه لمرة واحدة:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>one مثالٌ عن استعمال التابع</title>
<style>
div {
width: 60px;
height: 60px;
margin: 5px;
float: left;
background: green;
border: 10px outset;
cursor:pointer;
}
p {
color: red;
margin: 0;
clear: left;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div></div>
<div></div>
<div></div>
<div></div>
<div></div>
<p>اضغط على المربع الأخضر</p>
<script>
var n = 0;
$( "div" ).one( "click", function() {
var index = $( "div" ).index( this );
$( this ).css({
borderStyle: "inset",
cursor: "auto"
});
$( "p" ).text( "ضُغط على العنصر div ذي الفهرس #" + index + "." +
" أصبح العدد " + (++n) + " ضغطات بالمجمل." );
});
</script>
</body>
</html>
إظهار محتوى فقرةٍ في مربع تنبيه لمرة واحدة عندما يُضغط عليها:
<!doctype html>
<html lang="ar">
<head>
<meta charset="utf-8">
<title>one مثالٌ عن استعمال التابع</title>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<div class="count">0</div>
<div class="target">اضغط عليّ أو حرك المؤشر فوقي</div>
<script>
var n = 0;
$(".target").one("click mouseenter", function() {
$(".count").html(++n);
});
</script>
</body>
</html>