Promise系列06：Promise API Reference

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迷你书