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

`‎.promise( [type ] [, target ] )‎`

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

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

الوصف

يعيد هذا التابع كائنًا من النوع Promise عند انتهاء تنفيذ إجراءات ذات نوع محدَّد جميعها، سواءً كانت في الطابور (queued) أم لا، والمرتبطة بالمجموعة؛ وهذا التابع مفيد لمراقبة إكتمال تنفيذ إجراءات معينة.

`‎.promise( [type ] [, target ] )‎`

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

`type`

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

`target`

كائن مجرَّد (object) يبين أيًّا من توابع Promise يجب أن تكون مرفقة.

يعيد التابع ‎.promise()‎ الكائن Promise المولد بشكل دينامكي، وتكون قيمته مقبول (resolved) حالما تنتهي جميع الإجراءات التي نوع محدَّد، سواءً في الطابور أم لا، والمرتبطة بالمجموعة.

قيمة الوسيط type الافتراضيَّة هي fx وهذا يعني أنَّ الكائن Promise المُعاد سيكون مقبولًا (resolved) عندما يكتمل تنفيذ جميع الحركات (animations) للعناصر المطابقة.

إن أعطي وسيط وحيد، فسيُستبين محتواه لمعرفة المجموعة التي سيُستدعى التابع ‎.promise()‎ معها.

إن أعطي الوسيط target، فسيرفق التابع ‎.promise()‎ التوابع معه ثمَّ يعيد هذا الكائن بدلًا من إنشاء كائن جديد. قد يكون ذلك مفيدًا لإرفاق سلوك الكائن Promise بكائن موجود بالفعل.

ملاحظة: يُخزَّن الكائن Promise المُعاد الذي يُربط بكائن مؤجَّل Deferred في عنصرٍ في مخزن البيانات ‎.data()‎. لمَّا كان التابع ‎.remove()‎ يحذف عناصر مخزن البيانات عند حذفه للعناصر، فستُمنع جميع وعود (Promises) العناصر غير المقبولة (ذات الحالة unresolved) من أن تُقبل (أي تصبح resolved). إن كان لابدَّ من حذف عنصرٍ من شجرة DOM قبل تنفيذ الوعود المرتبطة به، فيجب حذفها باستعمال التابع ‎.detach()‎ بدلًا من التابع السابق ثم استعمال التابع ‎.removeData()‎ بعد تنفيذ عملية الحذف.

أمثلة

استعمال التابع ‎.promise()‎ على مجموعةٍ من العناصر ليس فيها حركات نشطة سيؤدي إلى إعادة الكائن Promise مقبول:

var div = $( "<div>" );
 
div.promise().done(function( arg1 ) {
  // "true" سيُصدر التنبيه مباشرةً ويكون
  alert( this === div && arg1 === div );
});

استبيان حالة الوعد (Promise) المعادة باستعمال التابع ‎.promise()‎ عندما تنتهي جميع الحركات المطبقة على العناصر <div> من ضمنها تلك التي بدأت في دالة رد النداء animation او التي تضاف لاحقًا:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>promise مثالٌ عن استعمال التابع</title>
  <style>
  div {
    height: 50px;
    width: 50px;
    float: left;
    margin-right: 10px;
    display: none;
    background-color: #090;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>انطلق</button>
<p>مستعد...</p>
<div></div>
<div></div>
<div></div>
<div></div>
 
<script>
$( "button" ).on( "click", function() {
  $( "p" ).append( "بدأ..." );
 
  $( "div" ).each(function( i ) {
    $( this ).fadeIn().fadeOut( 1000 * ( i + 1 ) );
  });
 
  $( "div" ).promise().done(function() {
    $( "p" ).append( " انتهى! " );
  });
});
</script>
 
</body>
</html>

استبيان حالة الوعد (Promise) المعادة باستعمال ‎$.when()‎ (يجعل التابع ‎.promise()‎ هذه العمليَّة ممكنة في مجموعات jQuery):

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>promise مثالٌ عن استعمال التابع</title>
  <style>
  div {
    height: 50px;
    width: 50px;
    float: left;
    margin-right: 10px;
    display: none;
    background-color: #090;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<button>انطلق</button>
<p>مستعد...</p>
<div></div>
<div></div>
<div></div>
<div></div>
 
<script>
var effect = function() {
  return $( "div" ).fadeIn( 800 ).delay( 1200 ).fadeOut();
};
 
$( "button" ).on( "click", function() {
  $( "p" ).append( " بدأ... " );
 
  $.when( effect() ).done(function() {
    $( "p" ).append( " انتهى! " );
  });
});
</script>
 
</body>
</html>

مصادر

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