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

<noinclude>{{DISPLAYTITLE:الدالة <code>Promise.prototype.catch()‎</code> في JavaScript}}</noinclude>
الدالة <code>catch()‎</code> تعيد وعدًا <code>[[JavaScript/Promise|Promise]]</code> وتتعامل مع حالات رفض الوعود فقط. وهي تسلك نفس سلوك استدعاء الدالة <code>[[JavaScript/Promise/then|Promise.prototype.then(undefined, onRejected)‎]]</code>. وفي الواقع، استدعاء الدالة <code>obj.catch(onRejected)‎</code> سيستدعي الدالة <code>[[JavaScript/Promise/then|obj.then(undefined, onRejected)‎]]</code> داخليًا.<syntaxhighlight lang="javascript">
var promise1 = new Promise(function(resolve, reject) {
  throw 'Uh-oh!';
});

promise1.catch(function(error) {
  console.log(error);
});
// Uh-oh!
</syntaxhighlight>

== البنية العامة ==
<syntaxhighlight lang="javascript">
p.catch(onRejected);

p.catch(function(reason) {
   // التعامل مع الرفض
});
</syntaxhighlight>

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

=== <code>onRejected</code> ===
دالة تستدعى عند رفض الوعد <code>[[JavaScript/Promise|Promise]]</code>. هذه الدالة تملك معاملًا وحيدًا:

=== <code>reason</code> ===
سبب الرفض.

الوعد المُعاد من الدالة <code>catch()‎</code> سيُرفَض إذا رمت الدالة <code>onRejected</code> أو أعادت وعدًا رُفِض بدوره؛ وإلا فسيكون الوعد مقبولًا.

== القيمة المعادة ==
هذه الدالة تستدعي الدالة <code>[[JavaScript/Promise/then|()Promise.prototype.then]]</code> داخليًا على الكائن الذي اُستدعيت عليه، وتمرر الوسائط <code>undefined</code> والدالة <code>onRejected</code> التي مُرِّرت إليها، وتعيد قيمة ذاك الاستدعاء (والذي هو وعدٌ <code>[[JavaScript/Promise|Promise]]</code>).

'''تحذير''': سنرمي سلاسل نصية في الأمثلة أدناه، وهذا أمرٌ غير منصوح به، حاول دومًا أن ترمي نسخةً من الكائن <code>[[JavaScript/Error|Error]]</code>، وإلا فعلى الجزء الذي سيلتقط الاستثناء أن يتحقق من نوع المعامل (هل هو سلسلة نصية أم خطأ)، وقد تخسر معلومات قيّمة عن الخطأ.

مثال عن استدعاء داخلي:<syntaxhighlight lang="javascript">
// إعادة تعريف الدوال الأصلية لإضافة بعض الأسطر التي تُسجِّل الأحداث
(function(Promise){
    var originalThen = Promise.prototype.then;
    var originalCatch = Promise.prototype.catch;
    
    Promise.prototype.then = function(){
        console.log('> > > > > > called .then on %o with arguments: %o', this, arguments);
        return originalThen.apply(this, arguments);
    };
    Promise.prototype.catch = function(){
        console.log('> > > > > > called .catch on %o with arguments: %o', this, arguments);
        return originalCatch.apply(this, arguments);
    };

})(this.Promise);



// استخدام الدالة catch على وعد مقبول
Promise.resolve().catch(function XXX(){});

// الناتج:
// > > > > > > called .catch on Promise{} with arguments: Arguments{1} [0: function XXX()]
// > > > > > > called .then on Promise{} with arguments: Arguments{2} [0: undefined, 1: function XXX()]
</syntaxhighlight>

== الوصف ==
يمكن أن تكون الدالة <code>()catch</code> مفيدةً لمعالجة الأخطاء في آلية الوعود التي تُطبِّقها.

== أمثلة ==

=== استخدام سلسلة من الدوال مع الدالة <code>()catch</code> ===
<syntaxhighlight lang="javascript">
var p1 = new Promise(function(resolve, reject) {
  resolve('Success');
});

p1.then(function(value) {
  console.log(value); // "Success!"
  throw 'oh, no!';
}).catch(function(e) {
  console.log(e); // "oh, no!"
}).then(function(){
  console.log('after a catch the chain is restored');
}, function () {
  console.log('Not fired due to the catch');
});

// ما يلي سيسلك نفس سلوك الشيفرة السابقة
p1.then(function(value) {
  console.log(value); // "Success!"
  return Promise.reject('oh, no!');
}).catch(function(e) {
  console.log(e); // "oh, no!"
}).then(function(){
  console.log('after a catch the chain is restored');
}, function () {
  console.log('Not fired due to the catch');
});
</syntaxhighlight>

=== رمي الأخطاء ===
رمي خطأ في وعد سيؤدي إلى استدعاء الدالة <code>()catch</code> في أغلبية الأوقات:<syntaxhighlight lang="javascript">
var p1 = new Promise(function(resolve, reject) {
  throw 'Uh-oh!';
});

p1.catch(function(e) {
  console.log(e); // "Uh-oh!"
});
</syntaxhighlight>الأخطاء المرمية داخل الدوال غير المتزامنة ستُعامل معاملة الاستثناءات غير المعالجة:<syntaxhighlight lang="javascript">
var p2 = new Promise(function(resolve, reject) {
  setTimeout(function() {
    throw 'Uncaught Exception!';
  }, 1000);
});

p2.catch(function(e) {
  console.log(e); // لن يصل الاستدعاء إلى هنا
});
</syntaxhighlight>لن يُعتد بالأخطاء المرمية بعد استدعاء الدالة <code>[[JavaScript/Promise/resolve|resolve()‎]]</code>:<syntaxhighlight lang="javascript">
var p3 = new Promise(function(resolve, reject) {
  resolve();
  throw 'Silenced Exception!';
});

p3.catch(function(e) {
   console.log(e); // لن يصل الاستدعاء إلى هنا
});
</syntaxhighlight>

=== في حالة قبول الوعد ===
إنشاء وعد لن يستدعي <code>onReject</code>:<syntaxhighlight lang="javascript">
var p1 = Promise.resolve("calling next");

var p2 = p1.catch(function (reason) {
    // لن يجري استدعاء ما يلي مطلقًا
    console.log("catch p1!");
    console.log(reason);
});

p2.then(function (value) {
    console.log("next promise's onFulfilled"); /* next promise's onFulfilled */
    console.log(value); /* calling next */
}, function (reason) {
    console.log("next promise's onRejected");
    console.log(reason);
});

</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[JavaScript/Promise/then|then()‎]]</code>: تعيد وعدًا <code>[[JavaScript/Promise|Promise]]</code>، وتأخذ وسيطين على الأكثر، وهما دالتا رد النداء (callback) لنجاح أو فشل الوعد.
* الدالة <code>[[JavaScript/Promise/resolve|resolve()‎]]</code>: تعيد كائن <nowiki/>[[JavaScript/Promise|<code>Promise</code>]] مقبول مع القيمة (value) المحددة.

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