翻譯服務

Promise物件代表一個非同步操作的最終完成（或失敗），以及它所產生的值。

Promise 的生命週期

Promise有三種狀態：

1. pending
2. fulfilled
3. rejected

建立時，Promise 處於 pending 狀態。 在未來的某個時間點，它可能會_解決_或_拒絕_。 Promise 一旦變成 resolved 或 rejected 一次，就永遠無法再變成 resolved 或 rejected，它的狀態也無法改變。

換句話說：

1. 處於 pending 時，Promise：
   • 可以轉變成 fulfilled 或 rejected 狀態。
2. 處於 fulfilled 時，Promise：
   • 不得轉變成任何其他狀態。
   • 必須有一個值，而且這個值不得改變。
3. 處於 rejected 時，Promise：
   • 不得轉變成任何其他狀態。
   • 必須有一個原因，而且這個原因不得改變。

解決 Promise

Promise 可以用各種方式解決：

// Creates a promise that is immediately resolved
Promise.resolve(value);

// Creates a promise that is immediately resolved
new Promise((resolve) => {
  resolve(value);
});

// Chaining a promise leads to a resolved promise
somePromise.then(() => {
  // ...
  return value;
});

在以上的例子中，value可以是_任何東西_，包括錯誤、undefined、null或其他 Promise。 通常你會想用一個不是錯誤的值來解決。

拒絕 Promise

Promise 可以用各種方式拒絕：

// Creates a promise that is immediately rejected
Promise.reject(reason)

// Creates a promise that is immediately rejected
new Promise((_, reject) {
  reject(reason)
})

// Chaining a promise with an error leads to a rejected promise
somePromise.then(() => {
  // ...
  throw reason
})

在以上的例子中，reason可以是_任何東西_，包括錯誤、undefined或null。 通常你會想用一個錯誤來拒絕。

串接 Promise

Promise 可以在解決或拒絕之後，用後續動作來_繼續_。

• promise.then()會在promise解決後被呼叫
• promise.catch()會在promise拒絕後被呼叫
• promise.finally()會在promise解決或拒絕後被呼叫

then

每個 Promise 都是「thenable」。 這表示有一個then函式可用，它會在原本的 Promise 解決後被執行。 以promise.then(onResolved)來說，回呼onResolved會收到原本 Promise 被解決時所帶的值。 這總是會回傳一個_新_的「串接」Promise。

在then裡回傳value會解決這個「串接」Promise。 在then裡丟出reason會拒絕這個「串接」Promise。

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);
});

const promise2 = promise1.then(function (value) {
  console.log(value);
  // expected output: "Success!"

  return true;
});

這會在大約 1000 毫秒後印出"Success!"。 promise1的狀態與值會是resolved和"Success!"。 promise2的狀態與值會是resolved和true。

還有第二個引數可用，會在原本的 Promise 拒絕時執行。 以promise.then(onResolved, onRejected)來說，回呼onResolved會收到原本 Promise 被解決時所帶的值，或者回呼onRejected會收到 Promise 被拒絕的原因。

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return true;
}

function shout(reason) {
  console.error(reason.toUpperCase());
  return false;
}

const promise2 = promise1.then(log, shout);

• 大約有一半的情況，這會在大約 1000 毫秒後印出"Success!"。
  • promise1的狀態與值會是resolved和"Success!"。
  • promise2的狀態與值會是resolved和true。
• 大約有一半的情況，這會立刻印出"NOPE!"。
  • promise1的狀態與值會是rejected和Nope!。
  • promise2的狀態與值會是resolved和false。

重要的是要理解，由於生命週期的規則，當它reject時，大約 1000 毫秒後才出現的resolve會被默默忽略，因為內部狀態一旦拒絕或解決就無法再改變。 同樣重要的是要理解，從 Promise 回傳值會解決它，而丟出值則會拒絕它。 當promise1解決，而且有串接的onResolved：then(onResolved)時，那個後續結果是一個新的 Promise，可以再解決或拒絕。 當promise1拒絕，但有串接的onRejected：then(, onRejected)時，那個後續結果是一個新的 Promise，可以再解決或拒絕。

catch

有時候你會想捕捉錯誤，只在原本的 Promise reject 時才繼續。 以promise.catch(onCatch)來說，回呼onCatch會收到原本 Promise 被拒絕的原因。 這總是會回傳一個_新_的「串接」Promise。

在catch裡回傳value會解決這個「串接」Promise。 在catch裡丟出reason會拒絕這個「串接」Promise。

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return 'done';
}

function recover(reason) {
  console.error(reason.toUpperCase());
  return 42;
}

const promise2 = promise1.catch(recover).then(log);

大約有一半的情況，這會在大約 1000 毫秒後印出"Success!"。 另外一半的情況，這會立刻印出42。

• 如果promise1解決，catch會被跳過並進到then，然後印出該值。
  • promise1的狀態與值會是resolved和"Success!"。
  • promise2的狀態與值會是resolved和"done"；
• 如果promise1拒絕，catch會被執行，而它_回傳了一個值_，因此串接結果現在變成resolved，接著進到then，並印出該值。
  • promise1的狀態與值會是rejected和"Nope!"。
  • promise2的狀態與值會是resolved和"done"；

finally

有時候你會想在某個 Promise 結束後執行程式碼，不論它最後是解決還是拒絕。 以promise.finally(onSettled)來說，回呼onSettled不會收到任何東西。 這總是會回傳一個_新_的「串接」Promise。

在finally裡回傳value會複製原本 Promise 的狀態與值，並忽略這個value。 在finally裡丟出reason會拒絕這個「串接」Promise，並覆寫原本 Promise 的任何狀態與值或原因。

範例

各種方法一起使用：

const myPromise = new Promise(function (resolve, reject) {
  const sampleData = [2, 4, 6, 8];
  const randomNumber = Math.round(Math.random() * 5);

  if (sampleData[randomNumber]) {
    resolve(sampleData[randomNumber]);
  } else {
    reject('Sampling did not result in a sample');
  }
});

const finalPromise = myPromise
  .then(function (sampled) {
    // If the random number was 0, 1, 2, or 3, this will be
    // reached and the number 2, 4, 6, or 8 will be logged.
    console.log(`Sampled data: ${sampled}`);
    return 'yay';
  })
  .catch(function (reason) {
    // If the random number was 4 or 5, this will be reached and
    // reason will be "An error occurred". The entire chain will
    // then reject with an Error with the reason as message.
    throw new Error(reason);
  })
  .finally(function () {
    // This will always log after either the sampled data is
    // logged or the error is raised.
    console.log('Promise completed');
  });

• 當randomNumber是0-3時：
  • myPromise會以值2, 4, 6, or 8解決
  • finalPromise會以值'yay'解決
  • 會有兩筆紀錄：
    • Sampled data: ...
    • Promise completed
• 當randomNumber是4-5時：
  • myPromise會以原因'Sampling did not result in a sample'拒絕
  • finalPromise會以原因Error('Sampling did not result in a sample')拒絕
  • 會有一筆紀錄：
    • Promise completed
    • 在某些環境中，這會產生一筆"uncaught rejected promise: Error('Sampling did not result in a sample')"紀錄

如上所示，reject可以搭配字串使用，而 Promise 也可以用Error來拒絕。