عرض مصدر JavaScript/Promise/then

<noinclude>{{DISPLAYTITLE:الدالة <code>Promise.prototype.then()‎</code> في JavaScript}}</noinclude>
الدالة <code>then()‎</code> تعيد وعدًا <code>[[JavaScript/Promise|Promise]]</code>، وتأخذ وسيطين على الأكثر، وهما دالتا رد النداء (callback) لنجاح أو فشل الوعد.<syntaxhighlight lang="javascript">
var promise1 = new Promise(function(resolve, reject) {
  resolve('Success!');
});

promise1.then(function(value) {
  console.log(value);
  // "Success!"
});
</syntaxhighlight>'''ملاحظة''': إذا كان أحد أو كلا المعاملين غير موجود، أو كان موجودًا لكنه ليس دالةً، فلن تضع الدالة <code>then()‎</code> معالجًا له، لكنها لن تولِّد أي أخطاء. إذا أصبحت هنالك حالة للوعد [[JavaScript/Promise|<code>Promise</code>]] الذي استدعيت الدالة <code>()then</code> عليه، ولم يكن للدالة <code>()then</code> وسائط مناسبة، فسيُنشَأ وعدٌ <code>[[JavaScript/Promise|Promise]]</code> جديد دون دوال للمعالجة، وذلك بأخذ آخر حالة للوعد <code>[[JavaScript/Promise|Promise]]</code> الأصلي الذي اُستدعيت عليه الدالة <code>()then</code>.

== البنية العامة ==
<syntaxhighlight lang="javascript">
p.then(onFulfilled[, onRejected]);

p.then(function(value) {
  // القبول
}, function(reason) {
  // الرفض
});
</syntaxhighlight>

== المعاملات ==

=== <code>onFulfilled</code> ===
دالة ستُستدعى عند قبول الوعد [[JavaScript/Promise|<code>Promise</code>]]. تملك هذه الدالة معاملًا وحيدًا هو قيمة القبول. إذا لم تكن هذه الدالة موجودًا، فستستبدل داخليًا بدالة تُعيد الوسيط المُمرَّر إليها.

=== <code>onRejected</code> ===
هذا المعامل اختياري. وهو دالة ستُستدعى عند رفض الوعد [[JavaScript/Promise|<code>Promise</code>]]. تملك هذه الدالة معاملًا وحيدًا هو سبب الرفض. إذا لم تكن هذه الدالة موجودًا، فستستبدل داخليًا بدالة تعيد رمي الوسيط المُمرَّر إليها.

== القيمة المعادة ==
كائن <code>[[JavaScript/Promise|Promise]]</code> في حالة الانتظار (pending). ثم ستستدعى دالة المعالجة (<code>onFilfilled</code> أو <code>onRejected</code>) استدعاءً غير متزامن، وبعد استدعاء الدالة المعالجة، إذا كانت:
*تعيد قيمةً، فالوعد المعاد من <code>then</code> سيقبل مع تلك القيمة.

*ترمي خطأً، فالوعد المعاد من <code>then</code> سيُرفض وسيرمى خطأٌ مع تلك القيمة.

*تعيد وعدًا مقبولًا من قبل، وسيقبل الوعد المُعاد من <code>then</code> مع قيمة الوعد الأصلي.

*تعيد وعدًا مرفوضًا من قبل، وسيرفض الوعد المعاد من <code>then</code> مع قيمة الوعد الأصلي.

*تعيد كائن <code>[[JavaScript/Promise|Promise]]</code> آخر في حالة الانتظار، وسيكون قبول أو رفض الوعد المُعاد من <code>then</code> تابعًا لقبول أو رفض الوعد المعاد من دالة المعالجة. وستكون قيمة الوعد المعاد من الدالة <code>then</code> هي نفس قيمة الوعد المعُاد من دالة المعالجة.
هذا مثال يوضِّح الآلية غير المتزامنة للدالة <code>()then</code>. لاحظ أننا نستخدم وعدًا مقبولًا، لذا ستستدعى <code>()then</code> مباشرةً، لكن الدوال المعالجة فيها ستُنفَّذ بشكل غير متزامن كما هو واضح من الرسائل الظاهرة:<syntaxhighlight lang="javascript">
var resolvedProm = Promise.resolve(33);

var thenProm = resolvedProm.then(function(value){
    console.log("this gets called after the end of the main stack. the value received and returned is: " + value);
    return value;
});

console.log(thenProm);

// سنؤجل تنفيذ الدالة
setTimeout(function(){
    console.log(thenProm);
});


// الناتج بالترتيب هو
// Promise {[[PromiseStatus]]: "pending", [[PromiseValue]]: undefined}
// "this gets called after the end of the main stack. the value received and returned is: 33"
// Promise {[[PromiseStatus]]: "resolved", [[PromiseValue]]: 33}
</syntaxhighlight>

== الوصف ==
لمّا كانت الدالة <code>()then</code> والدالة <code>[[JavaScript/Promise/prototype/catch|Promise.prototype.catch()‎]]</code> تعيدان وعودًا (الكائن <code>[[JavaScript/Promise|Promise]]</code>)، فيمكن تنفيذها على شكل سلسلة (chain).

== أمثلة ==

=== استخدام الدالة <code>()then</code> ===
<syntaxhighlight lang="javascript">
var p1 = new Promise( (resolve, reject) => {
  resolve('Success!');
  // or
  // reject ("Error!");
} );

p1.then( value => {
  console.log(value); // Success!
}, reason => {
  console.log(reason); // Error!
} );
</syntaxhighlight>

=== استخدام الدالة كسلسلة ===
تُعيد الدالة <code>()then</code> كائنًا من النوع <code>[[JavaScript/Promise|Promise]]</code>، مما يسمح باستدعاء الدوال كسلسلة (chain). إذا كانت الدالة المُمرَّرة كدالة معالجة إلى الدالة <code>()then</code> تُعيد كائن <code>[[JavaScript/Promise|Promise]]</code>، فيمكن أن يكون الكائن <code>[[JavaScript/Promise|Promise]]</code> المعاد يستطيع أن ينفِّذ الدالة <code>()then</code>.

المثال الآتي يحاكي شيفرة غير متزامنة مع الدالة <code>[[JavaScript/setTimeout|setTimeout]]</code>:
*الخطوة الأولى هي الحصول على <code>foo</code> ودمج <code>bar</code> إليه، وقبول الوعد واستدعاء <code>()then</code>.

*الخطوة الثانية هي الحصول على <code>foobar</code>، وتسجيل دالة رد نداء (callback) التي تجري عملية على تلك السلسلة النصية، وتطبعها، لكن ذلك لن يحدث قبل إعادة السلسلة النصية الأصلية إلى الدالة <code>()then</code> التالية.

*الخطوة الثالثة هي طباعة رسائل مفيدة.
لاحظ أنَّ السلسلة النصية الأخيرة <code>string</code> لن تحتوي على <code>baz</code> في آخرها، وذلك لأننا أضفنا ذلك بشكل غير متزامن داخل الدالة <code>[[JavaScript/setTimeout|setTimeout]]</code>:<syntaxhighlight lang="javascript">
Promise.resolve('foo')
  // الخطوة الأولى
  .then(function(string) {
    return new Promise(function(resolve, reject) {
      setTimeout(function() {
        string += 'bar';
        resolve(string);
      }, 1);
    });
  })
  // الخطوة الثانية
  .then(function(string) {
    setTimeout(function() {
      string += 'baz';
      console.log(string);
    }, 1)
    return string;
  })
  // الخطوة الثالثة
  .then(function(string) {
    console.log("Last Then:  oops... didn't bother to instantiate and return " +
                "a promise in the prior then so the sequence may be a bit " +
                "surprising");

    console.log(string);
  });
</syntaxhighlight>عند إعادة القيمة ببساطة داخل دالة معالجة في <code>()then</code>، فستُعاد <code>[[JavaScript/Promise/resolve|Promise.resolve]]</code> (<القيمة المعادة>):<syntaxhighlight lang="javascript">
var p2 = new Promise(function(resolve, reject) {
  resolve(1);
});

p2.then(function(value) {
  console.log(value); // 1
  return value + 1;
}).then(function(value) {
  console.log(value + '- This synchronous usage is virtually pointless'); // 2- This synchronous usage is virtually pointless
});

p2.then(function(value) {
  console.log(value); // 1
});
</syntaxhighlight>استدعاء <code>()then</code> سيعيد وعدًا مرفوضًا إذا رمت الدالة استثناءً، أو أعادت وعدًا مرفوضًا:<syntaxhighlight lang="javascript">
Promise.resolve()
  .then( () => {
    // رمي استثناء
    throw 'Oh no!';
  })
  .then( () => { 
    console.log( 'Not called.' );
  }, reason => {
    console.error( 'onRejected function called: ' + reason );
  });
</syntaxhighlight>في جميع الحالات الأخرى، يعاد وعدًا مقبولًا. في المثال التالي، سيعيد الاستدعاء ()then الأول القيمة 42 مغلفة بوعد مقبول رغم رفض الوعد السابق في السلسلة نفسها:<syntaxhighlight lang="javascript">
Promise.reject()
  .then( () => 99, () => 42 ) // القيمة 42 مغلفةً بوعد مقبول onRejected يعيد
  .then( solution => console.log( 'Resolved with ' + solution ) ); // 42 يقبل الوعد مع القيمة

</syntaxhighlight>عمليًّا، يفضل التقاط الوعود المرفوضة بدلًا من استعمال حالة الصياغة الثنائية كما موضح في المثال التالي:<syntaxhighlight lang="javascript">
Promise.resolve()
  .then( () => {
    // يعيد وعدًا مرفوضًا .then() جعل
    throw new Error('Oh no!');
  })
  .catch( error => {
    console.error( 'onRejected function called: ' + error.message );
  })
  .then( () => {
    console.log( "I am always called even if the prior then's promise rejects" );
  });


</syntaxhighlight>يمكن ربط الاستدعاءات بسلسلة لتنفيذ دالة واحدة مع واجهة برمجية تعتمد على الوعود (Promise-based API) فوق دالة أخرى:<syntaxhighlight lang="javascript">
function fetch_current_data() {
  // وعدًا. تعرض هذه الدالة fetch() تعيد الواجهة البرمجية
  // واجهة برمجية مماثلة باستثناء أن القيمة المنجزة لوعد 
  // هذه الدالة لديه عملًا إضافيًّا لينجزه معها
  return fetch('current-data.json').then((response) => {
    if (response.headers.get('content-type') != 'application/json') {
      throw new TypeError();
    }
    var j = response.json();
    // j يمكن فعل شيء مع
    return j; // تعطى القيمة المنجزة لمستخدم
              // fetch_current_data().then()
  });
}
I
</syntaxhighlight>إن أعاد onFulfilled وعدًا، فسيقبل أو يرفض هذا الوعد قيمة <code>()then</code>:<syntaxhighlight lang="javascript">
function resolveLater(resolve, reject) {
  setTimeout(function () {
    resolve(10);
  }, 1000);
}
function rejectLater(resolve, reject) {
  setTimeout(function () {
    reject(new Error('Error'));
  }, 1000);
}

var p1 = Promise.resolve('foo');
var p2 = p1.then(function() {
  // إعادة وعد هنا والذي سيقبل مع القيمة 10 بعد 1 ثانية
  return new Promise(resolveLater);
});
p2.then(function(v) {
  console.log('resolved', v);  // "resolved", 10
}, function(e) {
  // لا تستدع
  console.log('rejected', e);
});

var p3 = p1.then(function() {
  // بعد 1 ثانية 'Error' إعادة وعد هنا والذي سيرفض مع خطأ
  return new Promise(rejectLater);
});
p3.then(function(v) {
  // لا تستدع
  console.log('resolved', v);
}, function(e) {
  console.log('rejected', e); // "rejected", 'Error'
});
</syntaxhighlight>

=== نقص الدعم للنمط <code>window.setImmediate</code> الذي يعتمد على الوعود ===
استعمال التابع <code>[[JavaScript/Function/bind|Function.prototype.bind]]()‎</code> ‏‎ <code>Reflect.apply</code> ‎‏(<code>[[JavaScript/Reflect/apply|Reflect.apply()‎]]</code>) لإنشاء دالة بنمط <code>setImmediate</code> غير قابلة للإلغاء (non-cancellable):<syntaxhighlight lang="javascript">
const nextTick = (()=>{
  const noop = () => {}; // حرفيًّا
  const nextTickPromise = () => Promise.resolve().then(noop);

  const rfab = Reflect.apply.bind; // (thisArg, fn, thisArg, [...args])
  const nextTick = (fn, ...args) => (
    fn !== undefined
    ? Promise.resolve(args).then(rfab(null, fn, null))
    : nextTickPromise(),
    undefined
  );
  nextTick.ntp = nextTickPromise;

  return nextTick;
})();
S
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[JavaScript/Promise/catch|catch()‎]]</code>: تعيد وعدًا <code>[[JavaScript/Promise|Promise]]</code> وتتعامل مع حالات رفض الوعود فقط.
* الدالة <code>[[JavaScript/Promise/finally|finally()‎]]</code>: تعيد وعدًا <code>[[JavaScript/Promise|Pormise]]</code>، وعندما تُقرَّر قيمة الوعد، سواءً كان مقبولًا أو مرفوضًا، فستُنفَّذ دالة رد النداء (callback) المُحدَّدة.

== المصادر ==
* [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then صفحة Promise.prototype.then()‎ في توثيق MDN الرسمي].
[[تصنيف:JavaScript]]
[[تصنيف:JavaScript Functions]]
[[تصنيف:JavaScript Promise]]