عرض مصدر jQuery/deferred/promise

<noinclude>{{DISPLAYTITLE:التابع <code>deferred.promise()‎‎‎‎‎‎‎‎‎</code>‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ في jQuery}}</noinclude>
== <code>deferred.promise( [target ] )‎</code> ==

=== القيمة المعادة ===
يُعيد كائنًا من النوع [[JavaScript/Promise|Promise]].

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

=== <code>deferred.promise( [target ] )‎</code> ===
أُضيف مع الإصدار: [http://api.jquery.com/category/version/1.5/ 1.5].

==== <code>target</code> ====
الكائن الذي يجب إرفاق تابع promise به وهو من النوع [[JavaScript/Object|Object]].

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

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

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

لمزيد من المعلومات، راجع توثيق الكائن [[jQuery/deferred/|Deferred]].

=== أمثلة ===
إنشاء كائن مؤجل Deferred وضبط دالتين تستندان إلى مؤقِّت لقبول أو رفض الكائن المؤجل بعد فاصل عشوائي. أيهما يُطلق أولًا "يربح" ويستدعي أحد دوال رد النداء. المهلة الثانية ليس لها أي تأثير نظرًا لأن الكائن المؤجل Deferred قد اكتمل بالفعل (في حالة قبول أو رفض) أثناء إجراء المهلة الأولى. ويضبط أيضًا دالة إشعار تَقدُّم مستندة إلى مُؤقِّت، ويستدعي معالج تَقدُّم يضيف "working...‎" إلى نص المستند.<syntaxhighlight lang="jquery">
function asyncEvent() {
  var dfd = jQuery.Deferred();
 
  // Resolve after a random interval
  setTimeout(function() {
    dfd.resolve( "hurray" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
  // Reject after a random interval
  setTimeout(function() {
    dfd.reject( "sorry" );
  }, Math.floor( 400 + Math.random() * 2000 ) );
 
  // Show a "working..." message every half-second
  setTimeout(function working() {
    if ( dfd.state() === "pending" ) {
      dfd.notify( "working... " );
      setTimeout( working, 500 );
    }
  }, 1 );
 
  // Return the Promise so caller can't change the Deferred
  return dfd.promise();
}
 
// Attach a done, fail, and progress handler for the asyncEvent
$.when( asyncEvent() ).then(
  function( status ) {
    alert( status + ", things are going well" );
  },
  function( status ) {
    alert( status + ", you fail this time" );
  },
  function( status ) {
    $( "body" ).append( status );
  }
);
</syntaxhighlight>استخدام الوسيط <code>target</code> لترقية كائن موجود إلى كائن Promise:<syntaxhighlight lang="jquery">
// Existing object
var obj = {
    hello: function( name ) {
      alert( "Hello " + name );
    }
  },
  // Create a Deferred
  defer = $.Deferred();
 
// Set object as a promise
defer.promise( obj );
 
// Resolve the deferred
defer.resolve( "John" );
 
// Use the object as a Promise
obj.done(function( name ) {
  obj.hello( name ); // Will alert "Hello John"
}).hello( "Karl" ); // Will alert "Hello Karl"
</syntaxhighlight>

== مصادر ==
* [http://api.jquery.com/deferred.promise/ صفحة التابع ‎deferred.promise()‎‎‎‎‎‎‎‎‎‎ في توثيق jQuery الرسمي].
[[تصنيف:jQuery]]
[[تصنيف:jQuery Method]]
[[تصنيف:jQuery Deferred]]