We're looking for a user researcher to understand the needs of developers and designers. Is this you or someone you know? Check out the post: https://mzl.la/2IGzdXS

一個 Promise 物件代表一個可能還不能使用的值。

可以用不同的方式接收一個 promise 的參照,比如作為一個異步 API 的回傳值。一但你有了 promise 的參照,你就可以呼叫它的 then() 方法來在它的值準備好後,或是,當錯誤發生時執行一些動作。

Promises 物件也可以透過 new Promise() 建構子來創建。當你使用一個 Promise 物件的參照時,並不需要額外引入 Promise.jsm 模組 。

一個 promise 可以處於三種內部狀態:

  • Pending, 當最終的值尚未準備好被使用時。這是唯一一個可以轉移到其他兩個狀態的狀態。
  • Fulfilled, 當最終的值準備好被使用時。一個完成值將和 promise 建立永久關聯。它可能是任意的值,包和 undefined
  • Rejected, 當計算最終的值時有錯誤發生。一個拒絕原因將和 promise 建立永久關聯。它可以是任意的值,包含 undefined,儘管它通常是一個 Error 物件對象,就像例外處理時一樣。

註: 你永遠應該處理、轉送或是回報錯誤(或是拒絕的原因)。如果你看到 "A promise chain failed to handle a rejection",那很有可能是程式碼中有東西需要修正。請參考 handling errors and common pitfalls 。

文件規範

在說明文件中,完成值的型別通常被定義在角括號中。舉例來說,OS.File.exists 方法回傳的 promise 最終將會履行一個 boolean。

Promise<boolean> exists(string path);

拒絕原因通常可以分別在方法的文件中定義,而且當沒有特別說明時它將被當作是一個 Error 物件。

方法總覽

Promise then([optional] Function onFulfill, [optional] Function onReject);
Promise catch([optional] Function onReject);

建構子

創建一個新的 promise ,初始化等待狀態,並提供一些 resolving 方法的參照,這些方法將可以用來改變它的狀態。

new Promise(executor);

參數

executor

這個方法將立刻被呼叫,伴隨著兩個 resolving 方法作為其參數:

executor(resolve, reject);

建構子在 executor 結束之前不會結束。那些 resolving 方法可以在任何時候被使用,包含 executor 完成前和完成後,用來控制 promise 的最終狀態。如果 executor 拋出了例外,例外的值將被當作參數傳入 reject 方法。

Resolving 方法

resolve()

執行將特定值連結到 promise 的工作,或是傳遞狀態到一個已存在的 promise。如果被連結的 promise 已經處於被解決的狀態,無論是被連結到值、拒絕原因、或另外一個 promise,這個方法將不會做任何事。

註: 用一個等待中的 promise 當作此方法的 aValue 參數,並在這個 promise 被解決或被拒絕前再次呼叫此方法,第二次的呼叫並不會有任何效果,因為原本的 promise 已經被連結到這個等待中的 promise。
void resolve(
  aValue
);
參數
aValue Optional
如果這個值不是一個 promise,包含 undefined,它將成為被連結 promise 的完成值。如果這個值是一個 promise,則被連結的 promise 將會連結到這個傳入的 promise,並和它保持一樣的狀態(包含任何未來的轉變)。

reject()

用指定的原因拒絕被連結的 promise。如果該 promise 已經被解決,無論是連結到值、拒絕原因、或另外一個 promise,這個方法將不會做任何事。

void reject(
  aReason
);
參數
aReason Optional

被連結 promise 的拒絕原因。雖然原因可以是 undefined,它通常會是一個 Error 物件對象,就像例外處理那樣。

註: 這個參數不應該是一個 promise。指定一個拒絕 promise 作為拒絕原因會讓拒絕原因等於這個拒絕 promise 物件本身,而不是該 promise 的拒絕原因。

方法

then()

在 promise 被完成或是被拒絕後立刻呼叫提供的方法。一個新的 promise 將被回傳,新 promise 的狀態改變將基於此 promise 和提供的 callback 方法。

一個適當的 callback 總是在這個方法回傳後調用,無論此 promise 是否已經被完成或是被拒絕。你也可以在同一個 promise 上多次呼叫 then 方法,callback 們將被依照它們的註冊順序依序被調用。

警告: 如果 onFulfill callback 拋出例外, onReject callback 並不會被調用,錯誤也不會顯示在 console(你將會看到 promise 鍊失敗錯誤)。作為替代方法,你可以在你準備回傳的 promise 上註冊一個拒絕 callback 方法(使用 catch() 或是 then()),用於處理任何此 promise 上註冊的 callback 中拋出的例外。

註: 當你在同一個 promise 上呼叫多次 then 方法時,註冊的 callback 們將被獨立的調用。舉例來說,如果任何例外發生在其中一個 callback 中,它將不會影響其餘 callback 的執行。callback 的行為只會影響它註冊的 then 方法回傳的 promise。實際上,每次調用 then 方法將回傳完全不同的 promise。
Promise then(
  Function onFulfill,
  Function onReject
);
參數
onFulfill Optional
如果 promise 被完成,這個方法將被調用,完成值將作為它的唯一參數,此方法的回傳值將決定 then 方法回傳的新 promise 的狀態。若此參數不是一個方法(通常為null),then 方法回傳的新 promise 將被用和原本 promise 相同的完成值完成。
onReject Optional

如果 promise 被拒絕,這個方法將被調用,拒絕原因將作為它的唯一參數,此方法的回傳值將決定 then 方法回傳的新 promise 的狀態。若此參數不是一個方法(通常為null),then 方法回傳的新 promise 將被用和原本 promise 相同的拒絕原因拒絕。

回傳值

一個預設等待的 promise ,接著可以假設其狀態基於 callback 方法的結果:

  • 如果 callback 回傳一個不是 primise 的值,包含 undefined,新的 promise 將被用這個值完成,就算原本的 primise 是被拒絕的。
  • 如果 callback 拋出例外,新的 promise 將被用這個例外當作拒絕原因拒絕,就算原本的 promise 是被完成的。
  • 如果 callback 回傳一個 promise ,則可以假設新的 promise 最終將會和該 promise 擁有相同的狀態。

catch()

相當於呼叫 then() ,並使用 undefined 作為 onFulfill 參數的值。如果你串接 then(onFulfile).catch(onReject)onFulfill 拋出的例外將會被攔截並傳入 onReject ,這和直接將 onReject 傳入 then() 中不同。

Promise catch(
  Function onReject
);

因此以下的呼叫是等價的:

p.then(undefined, logError);
p.catch(logError);

除錯

基於 promise 的設計, promise 對象的狀態和值無法在不調用 then() 的前提下同步地檢視。

為了幫助除錯,只有在手動檢視 promise 對象時,才能看到更多資訊,這些資訊是代碼無法訪問的特殊屬性(目前,這是透過隨機化屬性名稱來實現的,因為缺少更複雜的語言或調適器的支持)。

這些代碼無法訪問,可檢視的屬性為:

  • {{private:status}}: 0 為等待, 1 為完成, 2 為拒絕。
  • {{private:value}}: 完成值或是拒絕原因,只對已完成或是已拒絕的 promise 有效。
  • {{private:handlers}}: 一個持有通過 then() 方法註冊之方法的參照的物件陣列,只對等待中的 promise 有效。

Promise properties are visible in the debugger.Promise handlers can be watched from the Console.

範例

參見 examples.

錯誤處理和常見的陷阱

你應該回報沒有被處理的錯誤,除非你將 promise 移交給調用者或是交給其他的代碼來處理這些錯誤。

// ###### WRONG: Silently drops any rejection notified by "OS.File.Exists".
OS.File.exists(path).then(exists => { if (exists) myRead(path); });

// ###### WRONG: Silently drops any exception raised by "myRead".
OS.File.exists(path).then(exists => { if (exists) myRead(path); }, Components.utils.reportError);

// CORRECT (for example, might report the exception "myRead is not defined")
OS.File.exists(path).then(exists => { if (exists) myRead(path); })
                    .catch(Components.utils.reportError);

// CORRECT (the function returns a promise, and the caller will handle the rejection)
function myReadIfExists(path)
{
  return OS.File.exists(path).then(exists => { if (exists) myRead(path); });
}

參見

文件標籤與貢獻者

標籤: 
此頁面的貢獻者: samsam2310, alk03073135, Shiyou
最近更新: samsam2310,