Promise系列06：Promise API Reference

原創

2020-02-21 22:58

1. Promise#then

promise.then(onFulfilled, onRejected);

var promise = new Promise(function(resolve, reject){
    resolve("傳遞給then的值");
});
promise.then(function (value) {
    console.log(value);
}, function (error) {
    console.error(error);
});

這段代碼創建一個promise對象，定義了處理onFulfilled和onRejected的函數（handler），然後返回這個promise對象。

這個promise對象會在變爲resolve或者reject的時候分別調用相應註冊的回調函數。

當handler返回一個正常值的時候，這個值會傳遞給promise對象的onFulfilled方法。
定義的handler中產生異常的時候，這個值則會傳遞給promise對象的onRejected方法。

2. Promise#catch

promise.catch(onRejected);

var promise = new Promise(function(resolve, reject){
    resolve("傳遞給then的值");
});
promise.then(function (value) {
    console.log(value);
}).catch(function (error) {
    console.error(error);
});

這是一個等價於promise.then(undefined, onRejected) 的語法糖。

3. Promise.resolve

Promise.resolve(promise);
Promise.resolve(thenable);
Promise.resolve(object);

var taskName = "task 1"
asyncTask(taskName).then(function (value) {
    console.log(value);
}).catch(function (error) {
    console.error(error);
});
function asyncTask(name){
    return Promise.resolve(name).then(function(value){
        return "Done! "+ value;
    });
}

根據接收到的參數不同，返回不同的promise對象。

雖然每種情況都會返回promise對象，但是大體來說主要分爲下面3類。

接收到promise對象參數的時候
返回的還是接收到的promise對象
接收到thenable類型的對象的時候
返回一個新的promise對象，這個對象具有一個 then 方法
接收的參數爲其他類型的時候（包括JavaScript對或null等）
返回一個將該對象作爲值的新promise對象

4. Promise.reject

Promise.reject(object)

另外，和 Promise.resolve不同的是，即使Promise.reject接收到的參數是一個promise對象，該函數也還是會返回一個全新的promise對象。

var r = Promise.reject(new Error("error"));
console.log(r === Promise.reject(r)); // false

5. Promise.all

Promise.all(promiseArray);

var p1 = Promise.resolve(1),
    p2 = Promise.resolve(2),
    p3 = Promise.resolve(3);
Promise.all([p1, p2, p3]).then(function (results) {
    console.log(results);  // [1, 2, 3]
});

生成並返回一個新的promise對象。
參數傳遞promise數組中所有的promise對象都變爲resolve的時候，該方法纔會返回，新創建的promise則會使用這些promise的值。
如果參數中的任何一個promise爲reject的話，則整個Promise.all調用會立即終止，並返回一個reject的新的promise對象。
由於參數數組中的每個元素都是由 Promise.resolve 包裝（wrap）的，所以Paomise.all可以處理不同類型的promose對象。

6. Promise.race

Promise.race(promiseArray);

var p1 = Promise.resolve(1),
    p2 = Promise.resolve(2),
    p3 = Promise.resolve(3);
Promise.race([p1, p2, p3]).then(function (value) {
    console.log(value);  // 1
});

生成並返回一個新的promise對象。
參數 promise 數組中的任何一個promise對象如果變爲resolve或者reject的話，該函數就會返回，並使用這個promise對象的值進行resolve或者reject。

6. 術語

Promises
Promise規範自身

promise對象
promise對象指的是 Promise 實例對象

ES6 Promises
如果想明確表示使用 ECMAScript 6th Edition 的話，可以使用ES6作爲前綴（prefix）

Promises/A+
Promises/A+。這是ES6 Promises的前身，是一個社區規範，它和 ES6 Promises 有很多共通的內容。

Thenable
類Promise對象。擁有名爲.then方法的對象。

轉載：JavaScript Promise迷你書