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

deferred.promise( [target ] )‎

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

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

الوصف

يُعيد هذا التابع كائن Promise للكائن المؤجل Deferred.

deferred.promise( [target ] )‎

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

target

الكائن الذي يجب إرفاق تابع promise به وهو من النوع Object.

يسمح التابع deferred.promise()‎‎ لدالة غير متزامنة بمنع الشيفرات البرمجية الأخرى من التدخل في تقدم أو حالة الطلب الداخلي الخاص به. ويعرض التابع promise فقط التوابع المؤجلة اللازمة لإرفاق معالجات إضافية أو تحديد الحالة (then و done و fail و always و pipe و progress و state و promise)، ولكن ليس التوابع التي تغير الحالة (resolve و reject و notify و resolveWith و rejectWith و notifyWith).

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

إذا كنت تنشئ كائن مؤجل Deferred، فاحتفظ بمرجع إليه بحيث يمكن قبوله أو رفضه في مرحلة ما. حاول إعادة الكائن Promise عبر التابع deferred.promise()‎‎ فقط، بحيث يمكن للشيفرات الأخرى تسجيل دوال رد النداء (callbacks) أو تفقد الحالة الحالية.

لمزيد من المعلومات، راجع توثيق الكائن Deferred.

أمثلة

إنشاء كائن مؤجل Deferred وضبط دالتين تستندان إلى مؤقِّت لقبول أو رفض الكائن المؤجل بعد فاصل عشوائي. أيهما يُطلق أولًا "يربح" ويستدعي أحد دوال رد النداء. المهلة الثانية ليس لها أي تأثير نظرًا لأن الكائن المؤجل Deferred قد اكتمل بالفعل (في حالة قبول أو رفض) أثناء إجراء المهلة الأولى. ويضبط أيضًا دالة إشعار تَقدُّم مستندة إلى مُؤقِّت، ويستدعي معالج تَقدُّم يضيف "working...‎" إلى نص المستند.

function asyncEvent() {
  var dfd = jQuery.Deferred();
 
  // القبول بعد فترة زمنية عشوائية
  setTimeout(function() {
    dfd.resolve( "hurray" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
    // الرفض بعد فترة زمنية عشوائية
  setTimeout(function() {
    dfd.reject( "sorry" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
  // عرض رسالة "قيد التنفيذ..." كل نصف ثانية
  setTimeout(function working() {
    if ( dfd.state() === "pending" ) {
      dfd.notify( "قيد التنفيذ... " );
      setTimeout( working, 500 );
    }
  }, 1 );
 
  // إعادة Promise حتى لا يستطيع المتصل تغيير المؤجل
  return dfd.promise();
}
 
// إرفاق معالج الانتهاء والفشل والتقدم لـ asyncEvent
$.when( asyncEvent() ).then(
  function( status ) {
    alert( status + ", الأمور تسير بشكل جيد" );
  },
  function( status ) {
    alert( status + ", لم تنجح هذه المرة" );
  },
  function( status ) {
    $( "body" ).append( status );
  }
);

استخدام الوسيط target لترقية كائن موجود إلى كائن Promise:

// كائن موجود
var obj = {
    hello: function( name ) {
      alert( "Hello " + name );
    }
  },
  // إنشاء كائن مؤجل
  defer = $.Deferred();
 
// ضبط كائن كـ promise
defer.promise( obj );
 
// قبول كائن مؤجل
defer.resolve( "John" );
 
// استخدم الكائن كـ Promise
obj.done(function( name ) {
  obj.hello( name ); // سوف يخرج تنبيه "Hello John"
}).hello( "Karl" ); // سوف يخرج تنبيه "Hello Karl"

مصادر

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