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

يُظهِر هذا التابع أو يعدل طابور الدوال المطلوب تنفيذها على العناصر المطابقة.

`‎.queue( [queueName ] )‎`

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

يعيد مصفوفة من النوع Array.

الوصف

يجلب هذا التابع طابور الدوال المطلوب تنفيذها على العناصر المطابقة.

`‎.queue( [queueName ] )‎`

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

`queueName`

سلسلة نصية تمثِّل اسم الطابور. القيمة الافتراضية هي fx وهو طابور التأثيرات القياسيَّة.

أمثلة

إظهار طول الطابور:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>queue مثالٌ عن استعمال التابع</title>
  <style>
  div {
    margin: 3px;
    width: 40px;
    height: 40px;
    position: absolute;
    left: 0px;
    top: 60px;
    background: green;
    display: none;
  }
  div.newcolor {
    background: blue;
  }
  p {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<p>طول الطابور هو: <span></span></p>
<div></div>
 
<script>
var div = $( "div" );
 
function runIt() {
  div
    .show( "slow" )
    .animate({ left: "+=200" }, 2000 )
    .slideToggle( 1000 )
    .slideToggle( "fast" )
    .animate({ left: "-=200" }, 1500 )
    .hide( "slow" )
    .show( 1200 )
    .slideUp( "normal", runIt );
}
 
function showIt() {
  var n = div.queue( "fx" );
  $( "span" ).text( n.length );
  setTimeout( showIt, 100 );
}
 
runIt();
showIt();
</script>
 
</body>
</html>

`‎.queue( [queueName ], newQueue )‎`

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

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

الوصف

يعدِّل هذا التابع محتوى طابور الدوال المطلوب تنفيذها لكل عنصر مطابق مرةً واحدة.

`‎.queue( [queueName ], newQueue )‎`

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

`queueName`

سلسلة نصية تمثِّل اسم الطابور. القيمة الافتراضيَّة هي fx وهو طابور التأثيرات القياسيَّة.

`newQueue`

مصفوفة تحتوي على طابور الدوال الجديد المراد استبداله بمحتوى الطابور الحالي.

`‎.queue( [queueName ], callback )‎`

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

`queueName`

سلسلة نصية تمثِّل اسم الطابور. القيمة الافتراضيَّة هي fx وهو طابور التأثيرات القياسيَّة.

callback

دالة من الشكل Function( Function next() )‎، وتمثل الدالة الجديدة المراد إضافتها إلى الطابور، وتحتوي على دالة تزيل عند استدعائها العنصر التالي من الطابور.

يستطيع كل عنصر أن يمتلك طابورًا واحدًا أو أكثر من دوالٍ مرفقة به باستعمال jQuery. يُستعمَل في أغلب التطبيقات طابورًا واحدًا يدعى fx. تسمح الطوابير بتطبيق سلسلة من الأحداث على عنصرٍ بشكل غير متزامن ودون التأثير على سير عمل البرنامج. أبسط مثال عن ذلك هو استدعاء توابع تحريك متعددة مع عنصر مثل:

$( "#foo" ).slideUp().fadeIn();

عند تنفيذ هذا السطر من الشيفرة، سيبدأ العنصر بتنفيذ الحركات مباشرةً، إذ اصطُفَّت حركة التلاشي (fading transition) في الطابور fx لتُستدعى حالما تنتهي حركة الإنزلاق (sliding transition) فقط.

يسمح لنا التابع ‎.queue()‎ بتعديل طابور الدوال هذا مباشرةً. إنَّ استدعائه مع الوسيط callback مفيد إلى حدٍّ ما، إذ يسمح لنا بإضافة دالة جديدة إلى نهاية الطابور. تُنفَّذ الدالة callback مرة واحدة لكل عنصر في مجموعة jQuery.

تشبه هذه الميزة تمامًا حالة تزويد تابع الحركة بدالة رد نداء callback، باستثناء أنَّها لا تتطلب أن تُزوَّد هذه الدالة في الوقت الذي تُنفَّذ فيه الحركة.

$( "#foo" ).slideUp();
$( "#foo" ).queue(function() {
  alert( "Animation complete." );
  $( this ).dequeue();
});

هذه الشيفرة مُكافئِة للشيفرة التالية:

$( "#foo" ).slideUp(function() {
  alert( "Animation complete." );
});

انتبه إلى أنَّه يجب عليك عندما تضيف دالة باستعمال ‎.queue()‎ أن تتأكد من استدعاء التابع ‎.dequeue()‎ في النهاية من أجل ضمان تنفيذ الدالة الموجودة في السطر التالي من الطابور. بدءًا من الإصدار jQuery 1.4، يمكن تمرير دالة أخرى إلى الدالة callback كوسيط أول، وسيخرج العنصر التالي تلقائيًّا من الطابور عندما تُستدعى ويستمر الطابور بالحركة. تُستخدَم هذه الحالة بالشكل التالي:

$( "#test" ).queue(function( next ) {
   // افعل شيئًا هنا
   next();
});

أمثلة

صفُّ دوال مخصصَّة في الطابور:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>queue demo</title>
  <style>
  div {
    margin: 3px;
    width: 40px;
    height: 40px;
    position: absolute;
    left: 0px;
    top: 30px;
    background: green;
    display: none;
  }
  div.newcolor {
    background: blue;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
Click here...
<div></div>
 
<script>
$( document.body ).click(function() {
  $( "div" )
    .show( "slow" )
    .animate({ left: "+=200" }, 2000 )
    .queue(function() {
      $( this ).addClass( "newcolor" ).dequeue();
    })
    .animate({ left: "-=200" }, 500 )
    .queue(function() {
      $( this ).removeClass( "newcolor" ).dequeue();
    })
    .slideUp();
});
</script>
 
</body>
</html>

تبديل محتوى الطابور الحالي إلى محتوى جديد باستعمال مصفوفة:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>queue demo</title>
  <style>
  div {
    margin: 3px;
    width: 40px;
    height: 40px;
    position: absolute;
    left: 0px;
    top: 30px;
    background: green;
    display: none;
  }
  div.newcolor {
    background: blue;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button id="start">Start</button>
<button id="stop">Stop</button>
<div></div>
 
<script>
$( "#start" ).click(function() {
  $( "div" )
    .show( "slow" )
    .animate({ left: "+=200" }, 5000 )
    .queue(function() {
      $( this ).addClass( "newcolor" ).dequeue();
    })
    .animate({ left: '-=200' }, 1500 )
    .queue(function() {
      $( this ).removeClass( "newcolor" ).dequeue();
    })
    .slideUp();
});
$( "#stop" ).click(function() {
  $( "div" )
    .queue( "fx", [] )
    .stop();
});
</script>
 
</body>
</html>

مصادر

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