Promise

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Promise 物件代表一個即將完成、或失敗的非同步操作，以及它所產生的值。

備註： 此條目為介紹 Promise 建構式。要瞭解 Promise 相關使用方式，請先參考使用 Promise。Promise 建構式主要用於包裹尚未支援 Promise 的函式。

嘗試一下

const promise1 = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("foo");
  }, 300);
});

promise1.then((value) => {
  console.log(value);
  // Expected output: "foo"
});

console.log(promise1);
// Expected output: [object Promise]

語法

new Promise( /* executor */ function(resolve, reject) { ... } );

參數

executor: 為一個依序接收兩個參數的函式：resolve 及 reject（實現及拒絕回呼函式）。在 Promise 實作中，executor 函式在傳入參數 resolve 與 reject 後會立刻執行（executor 函式會在 Promise 建構式回傳 Promise 物件前被執行）。resolve 與 reject 函式，會在被個別呼叫時，個別執行之。通常 executor 函式會發起一些非同步操作。接著，成功完成後執行 resolve 以完成 promise；或如果有錯誤，執行 rejects。如果 executor 函式在執行中拋出錯誤，promise 會被拒絕（rejected），回傳值也將被忽略。

描述

Promise 會代理一個建立時，不用預先得知的值。它使你能夠繫結（associate）著發動非同步操作後，最終的成功值（success value）或失敗訊息（failure reason）的處理函式（handlers）。這讓非同步方法回傳值的方式很像同步方法，但不是回傳最終結果：非同步方法回傳一個 promise 物件作為未來某時間點的值。

一個 Promise 物件處於以下幾種狀態：

擱置（pending）：初始狀態，不是 fulfilled 與 rejected。
實現（fulfilled）：表示操作成功地完成。
拒絕（rejected）：表示操作失敗了。

一個處於擱置狀態的 promise 能以一個值被實現（fulfilled），或是以一個原因或錯誤而被拒絕（rejected）。當上述任一狀態轉換發生時，那些透過 then 方法所繫結（associated）的處理函式列隊就會依序被調用。（若一個 promise 已被實現或拒絕，繫結（attached）於它的處理函式將立即被呼叫，因此完成非同步操作與繫結處理函式之間不存在競爭條件（race condition）。）

由於 Promise.prototype.then() 以及 Promise.prototype.catch() 方法都回傳 promise，它們可以被串接。

備註： 許多其他語言擁有機制用來惰性求值（lazy evaluation）及延遲（deferring）運算，它們也被稱作「promises」 — e.g. Scheme. 然而在 JavaScript 中 Promises 代表那些（已經）發生中（happening）的程序，它們可以繫結回呼函式。若你要找的是惰性求值表示式，考慮不帶參數的 arrow function：f = () => expression 來建立惰性求值表示式，並透過 f() 進行求值.

備註： 一個被實現或拒絕，但不處於 pending 的 promise 被稱作被解決（settled）。你也會見到使用解決（resolved）一詞來描述 promises — 這代表 promises 被實現（fulfilled）了。States and fates 這篇文章包含了更多 promises 的專有名詞。

屬性

Promise.length: 長度屬性，值固定為 1。(建構式參數數目).
Promise.prototype: Promise 建構式的原型（prototype）.

方法

Promise.all(iterable): 回傳一個 promise，當在引數 iterable 中所有 promises 都被實現時被實現，或在引數 iterable 中有一個 promise 被拒絕時立刻被拒絕。若回傳的 promise 被實現，它將以一個實現值的陣列被實現，其順序與 iterable 中的 promises 相同。若回傳的 promise 被拒絕，它將以失敗訊息被拒絕，此訊息來自第一個在 iterable 中被拒絕的 promise。這個方法在聚集許多 promises 的結果時很有效。
Promise.race(iterable): 回傳一個被實現或拒絕的 promise，當 iterable 中有一個 promise 被實現或拒絕時。
Promise.reject(reason): 回傳一個以失敗訊息拒絕的 promise。