التابع .stop() في jQuery
.stop( [clearQueue ] [, jumpToEnd ] )
القيم المعادة
يعيد كائنًا من النوع jQuery.
الوصف
يوقف هذا التابع الحركة التي يجري تنفيذها آنذاك على العناصر المطابقة.
.stop( [clearQueue ] [, jumpToEnd ] )
أُضيف مع الإصدار: 1.2.
clearQueue
قيمة منطقيَّة تحدِّد إن كان يجب حذف الحركات التي تنتظر في الطابور أيضًا أم لا. القيمة الافتراضيَّة هي false.
jumpToEnd
قيمة منطقيَّة تحدِّد إن كان يجب إكمال الحركة الحاليَّة مباشرةًَ والتوقف بعدها أم التوقف مباشرةً دون انتظار اكمال الحركة التي تنفَّذ آنذاك. القيمة الافتراضيَّة هي false.
.stop( [queue ] [, clearQueue ] [, jumpToEnd ] )
أُضيف مع الإصدار: 1.7.
queue
سلسلة نصية تمثل اسم طابور الانتظار الذي يحتوي على الحركات المنتظرة المراد إيقافها أيضًا.
clearQueue
قيمة منطقيَّة تحدِّد إن كان يجب حذف الحركات التي تنتظر في الطابور أيضًا أم لا. القيمة الافتراضيَّة هي false.
jumpToEnd
قيمة منطقيَّة تحدِّد إن كان يجب إكمال الحركة الحالية مباشرةً والتوقف بعدها أم التوقف مباشرةً دون انتظار اكمال الحركة التي تنفَّذ آنذاك. القيمة الافتراضيَّة هي false.
عندما يُستدعَى التابع .stop() مع عنصر، فستتوقف أي حركة تنفَّذ آنذاك مباشرةً. إن كان العنصر قيد الإخفاء مثلًا باستعمال التابع .sildeUp() عند استدعاء التابع .stop()، فستتوقف الحركة ويبقى العنصر ظاهرًا بغض النظر عن ارتفاعه الذي قد يصبح أصغر من الارتفاع الأصلي، ولن تُستدعَى دوال رد النداء أيضًا.
إن استُدعي أكثر من تابع حركي مع العنصر ذاته، فستوضع التوابع اللاحقة في طابور التأثيرات الخاص بالعنصر، ولن تبدأ حركات هذه التوابع حتى تكتمل حركة التابع الأول. عندما يُستدعى التابع .stop() حينئذٍ، فستبدأ الحركة التالية التي تنتظر في الطابور مباشرةً. إن أُعطيت قيمة الوسيط clearQueue وكانت true، فستزال حينها جميع توابع الحركات تلك من الطابور ولن تنفَّذ مطلقًا.
إن أُعطيت قيمة الوسيط jumbToEnd وكانت true، فستتوقف الحركة الحاليَّة وستُضبط القيم المستهدفة لكل خاصِّيَّة CSS من خاصِّيَّات العنصر مباشرةً. في مثالنا السابق الذي يراد إخفاء العنصر فيه باستعمال .slideUp()، سيُخفى العنصر مباشرةً في هذه الحالة، وستُستدعى دالة رد النداء مباشرةً حينئذٍ إن كانت معطاة.
بدءًا من الإصدار jQuery 1.7، إن كان المعامل الأول المُمرَّر إلى التابع سلسلة نصية، فستتوقف جميع الحركات التي تقبع منتظرةً في الطابور الذي تمثله هذه السلسلة المعطاة فقط.
تظهر فائدة التابع .stop() جليَّةً عندما نريد تحريك عنصرٍ أثناء وقوع الحدث mouseenter والحدث mouseleave:
<div id="hoverme">
حرك المؤشّر فوقي
<img id="hoverme" src="book.png" alt="" width="100" height="123">
</div>
يمكننا إنشاء تأثير تلاشي (fade) جميل جدًا دون أخذ مشكلة طوابير الحركة المتعدِّدة الشائعة بالحسبان وذلك بإضافة .stop(true, true) إلى السلسلة:
$( "#hoverme-stop-2" ).hover(function() {
$( this ).find( "img" ).stop( true, true ).fadeOut();
}, function() {
$( this ).find( "img" ).stop( true, true ).fadeIn();
});
تبديل الحركات (Toggling Animations)
بدءًا من الإصدار jQuery 1.7، أصبح إيقاف الحركات المبدِّلة (toggled animation) بشكل سابق لأوانه باستعمال التابع .stop() يؤدِّي إلى استدعاء تعقُّب التأثيرات الداخليَّة (internal effects tracking) في jQuer. قبل هذا الإصدار، كان يسبب استدعاء التابع .stop() قبل اكتمال الحركات المبدِّلة فقدان الحركة أثر التعقُّب الذي تجريه توابع الحركيَّة لمعرفة حالة العنصر (إن كانت قيمة الوسيط jumpToEnd هي false). ستبدأ الحركات اللاحقة عند الحالة الجديدة التي تجدها، ولا يظهر أحيانًا أي اختلاف على العنصر. لمراقبة السلوك الجديد، تفحَّص المثال الأخير في قسم الأمثلة.
ملاحظة: يمكن إيقاف الحركات عمومًا بضبط الخاصية $.fx.off إلى القيمة true. وإن حدث ذلك، فستنقل التوابع الحركيَّة العناصر التي تطبق عليها إلى حالتها النهائيَّة مباشرةً عند استدعائها بدلًا من إظهار التأثيرات الحركيَّة عليها.
أمثلة
مثالٌ يوضَّح فيه كيفيَّة بدء حركة العنصر عند الضغط على الزر "انطلق" وإيقافها عند الضغط على الزر "توقف" حيث يكون العنصر. يمكن الضغط على الزر "انطلق" عدة مرات لوضع الحركات التالية في الطابور وسيؤدي الضغط على "توقف" إلى إيقاف الحركة الحاليَّة التي تُنفَّذ آنذاك فقط:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>stop مثالٌ عن استعمال التابع</title>
<style>
div {
position: absolute;
background-color: #abc;
left: 0px;
top: 30px;
width: 60px;
height: 60px;
margin: 5px;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button id="go">انطلق</button>
<button id="stop">توقف</button>
<button id="back">ارجع</button>
<div class="block"></div>
<script>
// بدء الحركة
$( "#go" ).click(function() {
$( ".block" ).animate({ left: "+=100px" }, 2000 );
});
// إيقاف الحركة عند الضغط على زر الإيقاف
$( "#stop" ).click(function() {
$( ".block" ).stop();
});
// بدء الحركة باتجاه معاكس
$( "#back" ).click(function() {
$( ".block" ).animate({ left: "-=100px" }, 2000 );
});
</script>
</body>
</html>
مثال يوضِّح الحركات المبِّدلة، إذ سيؤدي الضغط أول مرة على "بدّل الحركة" إلى بدء الحركة، ثمَّ سيؤدي الضغط على الزر نفسه مرة أخرى قبل انتهاء الحركة إلى تبديل الحركة إلى الاتجاه الآخر وفقًا للاتجاه المخزَّن عند بدء الحركة:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>stop مثالٌ عن استعمال التابع</title>
<style>
.block {
background-color: #abc;
border: 2px solid black;
width: 200px;
height: 80px;
margin: 10px;
}
</style>
<script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
<button id="toggle">بدّل الحركة</button>
<div class="block"></div>
<script>
var $block = $( ".block" );
// Toggle a sliding animation animation
$( "#toggle" ).on( "click", function() {
$block.stop().slideToggle( 1000 );
});
</script>
</body>
</html>