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

<noinclude>{{DISPLAYTITLE:الدالة <code>Promise.prototype.finally()‎</code> في JavaScript}}</noinclude>
الدالة <code>finally()‎</code> تعيد وعدًا <code>[[JavaScript/Promise|Pormise]]</code>، وعندما تُقرَّر قيمة الوعد، سواءً كان مقبولًا أو مرفوضًا، فستُنفَّذ دالة رد النداء (callback) المُحدَّدة. وهذا ما يوفِّر طريقة لتنفيذ شيفرة ما بعد التعامل مع كائن <code>[[JavaScript/Promise|Pormise]]</code> سواءً كان الوعد مقبولًا أو مرفوضًا.

تسمح هذه الدالة لنا بتفادي تكرار الشيفرات في دوال <code>then()‎</code> و <code>catch()‎</code>.

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

p.finally(function() {
   // قُرِّرَت قيمة الوعد، سواءً كان مقبولًا أم مرفوضًا
});
</syntaxhighlight>

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

=== <code>onFinally</code> ===
الدالة التي ستُستدعى عند تقرير قيمة الوعد.

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

== الوصف ==
يمكن أن تكون الدالة <code>finally()‎</code> مفيدةً إذا كنتُ تريد إجراء بعض عمليات المعالجة أو «التنظيف» بعد تقرير قيمة الوعد، بغض النظر عنها.

الدالة <code>finally()‎</code> شبيهة جدًا باستدعاء ‎<code>.then(onFinally, onFinally)‎</code>، لكن هنالك بعض الاختلافات:
* عند تمرير دالة مجهولة وإنشائها موضعًا، فعليك تمريرها مرةً واحدةً، بدلًا من تعريفها مرتين، أو إسنادها إلى متغير.
* لن تستقبل دالة رد النداء <code>finally</code> أي وسيط، وذلك لأنه لا توجد طرائق عملية لتحديد إذا كان الوعد قد تحقق أم رُفِض. وهذه الحالة تعني أنَّك لا تلقي بالًا لسبب الرفض أو قيمة تحقيق الوعد، لذا لا حاجة لتوفيرها إلى دالة رد النداء.
* على العكس من <code>Promise.resolve(2).then(() => {}, () => {})‎</code> (والتي ستُقبَل مع القيمة <code>undefined</code>)، التعبير <code>Promise.resolve(2).finally(() => {})‎</code> ستُقبَل مع القيمة 2.
* وبشكل مشابه، على النقيض من <code>Promise.reject(3).then(() => {}, () => {})‎</code> (التي ستُحقَّق مع القيمة <code>undefined</code>)، التعبير <code>Promise.reject(3).finally(() => {})‎</code> سيُرفَض مع القيمة 3.
'''ملاحظة''': استخدام <code>[[JavaScript/throw|throw]]</code> (أو إعادة وعد مرفوض) في دالة رد النداء <code>finally</code> سيؤدي إلى رفض الوعد الجديد مع السبب المُحدَّد مع <code>[[JavaScript/throw|throw()‎]]</code>.

== أمثلة ==
مثال على استعمال الدالة <code>finally()‎</code>:<syntaxhighlight lang="javascript">
let isLoading = true;

fetch(myRequest).then(function(response) {
    var contentType = response.headers.get("content-type");
    if(contentType && contentType.includes("application/json")) {
      return response.json();
    }
    throw new TypeError("Oops, we haven't got JSON!");
  })
  .then(function(json) { /* process your JSON further */ })
  .catch(function(error) { console.log(error); })
  .finally(function() { isLoading = false; });
</syntaxhighlight>

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

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