Promise 对象用于表示一个异步操作的最终状态(完成或失败),以及该异步操作的结果值。
本条目为Promise构造函数。想要了解promises,请首先阅读 使用 promises。构造函数主要是用来包装还未支持promises的函数。
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
new Promise( function(resolve, reject) {...} /* executor */ );
resolve
和 reject
两个参数的函数 。Promise构造函数执行时立即调用executor
函数, resolve
和 reject
两个函数作为参数传递给executor
(executor 函数在Promise构造函数返回所建promise实例对象前被调用)。resolve
和 reject
函数被调用时,分别将promise的状态改为fulfilled(完成)或rejected(失败)。executor 内部通常会执行一些异步操作,一旦异步操作执行完毕(可能成功/失败),要么调用resolve函数来将promise状态改成fulfilled,要么调用reject
函数将promise的状态改为rejected。如果在executor函数中抛出一个错误,那么该promise 状态为rejected。executor函数的返回值被忽略。Promise
对象是一个代理对象(代理一个值),被代理的值在Promise对象创建时可能是未知的。它允许你为异步操作的成功和失败分别绑定相应的处理方法(handlers)。 这让异步方法可以像同步方法那样返回值,但并不是立即返回最终执行结果,而是一个能代表未来出现的结果的promise对象
一个 Promise
有以下几种状态:
pending 状态的 Promise 对象可能会变为fulfilled 状态并传递一个值给相应的状态处理方法,也可能变为失败状态(rejected)并传递失败信息。当其中任一种情况出现时,Promise 对象的 then
方法绑定的处理方法(handlers )就会被调用(then方法包含两个参数:onfulfilled 和 onrejected,它们都是 Function 类型。当Promise状态为fulfilled时,调用 then 的 onfulfilled 方法,当Promise状态为rejected时,调用 then 的 onrejected 方法, 所以在异步操作的完成和绑定处理方法之间不存在竞争)。
因为
和 Promise.prototype.then
方法返回promise 对象, 所以它们可以被链式调用。Promise.prototype.catch
不要和惰性求值混淆: 有一些语言中有惰性求值和延时计算的特性,它们也被称为“promises”,例如Scheme. Javascript中的promise代表一种已经发生的状态, 而且可以通过回调方法链在一起。 如果你想要的是表达式的延时计算,考虑无参数的"箭头方法": f = () =>
表达式
创建惰性求值的表达式,使用 f()
求值。
注意: 如果一个promise对象处在fulfilled或rejected状态而不是pending状态,那么它也可以被称为settled状态。你可能也会听到一个术语resolved ,它表示promise对象处于fulfilled状态。关于promise的术语, Domenic Denicola 的 States and fates 有更多详情可供参考。
Promise.length
Promise.prototype
Promise
构造器的原型.Promise.all(iterable)
Promise.race(iterable)
Promise.reject(reason)
Promise.resolve(value)
Promise.prototype.constructor
Promise
函数.Promise.prototype.catch(onRejected)
Promise.prototype.then(onFulfilled, onRejected)
Promise.prototype.finally(onFinally)
Promise
对象是由关键字 new
及其构造函数来创建的。该构造函数会把一个叫做“处理器函数”(executor function)的函数作为它的参数。这个“处理器函数”接受两个函数——resolve
和 reject
——作为其参数。当异步任务顺利完成且返回结果值时,会调用 resolve
函数;而当异步任务失败且返回失败原因(通常是一个错误对象)时,会调用reject
函数。
const myFirstPromise = new Promise((resolve, reject) => {
// ?做一些异步操作,最终会调用下面两者之一:
//
// resolve(someValue); // fulfilled
// ?或
// reject("failure reason"); // rejected
});
想要某个函数?拥有promise功能,只需让其返回一个promise即可。
function myAsyncFunction(url) {
return new Promise((resolve, reject) => {
const xhr = new XMLHttpRequest();
xhr.open("GET", url);
xhr.onload = () => resolve(xhr.responseText);
xhr.onerror = () => reject(xhr.statusText);
xhr.send();
});
};
let myFirstPromise = new Promise(function(resolve, reject){
//当异步代码执行成功时,我们才会调用resolve(...), 当异步代码失败时就会调用reject(...)
//在本例中,我们使用setTimeout(...)来模拟异步代码,实际编码时可能是XHR请求或是HTML5的一些API方法.
setTimeout(function(){
resolve("成功!"); //代码正常执行!
}, 250);
});
myFirstPromise.then(function(successMessage){
//successMessage的值是上面调用resolve(...)方法传入的值.
//successMessage参数不一定非要是字符串类型,这里只是举个例子
console.log("Yay! " + successMessage);
});
本例展示了 Promise
的一些机制。 testPromise()
方法在每次点击 <button>
按钮时被调用,该方法会创建一个promise 对象,使用 window.setTimeout()
让Promise等待 1-3 秒不等的时间来填充数据(通过Math.random()方法)。
Promise 的值的填充过程都被日志记录(logged)下来,这些日志信息展示了方法中的同步代码和异步代码是如何通过Promise完成解耦的。
'use strict';
var promiseCount = 0;
function testPromise() {
let thisPromiseCount = ++promiseCount;
let log = document.getElementById('log');
log.insertAdjacentHTML('beforeend', thisPromiseCount +
') 开始 (<small>同步代码开始</small>)<br/>');
// 新构建一个 Promise 实例:使用Promise实现每过一段时间给计数器加一的过程,每段时间间隔为1~3秒不等
let p1 = new Promise(
// resolver 函数在 Promise 成功或失败时都可能被调用
(resolve, reject) => {
log.insertAdjacentHTML('beforeend', thisPromiseCount +
') Promise 开始 (<small>异步代码开始</small>)<br/>');
// 创建一个异步调用
window.setTimeout(
function() {
// 填充 Promise
resolve(thisPromiseCount);
}, Math.random() * 2000 + 1000);
}
);
// Promise 不论成功或失败都会调用 then
// catch() 只有当 promise 失败时才会调用
p1.then(
// 记录填充值
function(val) {
log.insertAdjacentHTML('beforeend', val +
') Promise 已填充完毕 (<small>异步代码结束</small>)<br/>');
})
.catch(
// 记录失败原因
(reason) => {
console.log('处理失败的 promise ('+reason+')');
});
log.insertAdjacentHTML('beforeend', thisPromiseCount +
') Promise made (<small>同步代码结束</small>)<br/>');
}
点击下面的按钮可以看到示例代码运行的效果,前提是你的浏览器支持 Promise
。快速点击按钮多次你会观察到Promises填充值的过程。
另一个用了 Promise 和 XMLHttpRequest 加载一个图像的例子可在MDN GitHub promise-test 中找到。 你也可以看这个实例。每一步都有注释可以让你详细的了解Promise和XHR架构。
规范 | 状态 | 备注 |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) Promise |
Standard | ECMA标准中的首次定义 |
ECMAScript Latest Draft (ECMA-262) Promise |
Draft |
To contribute to this compatibility data, please write a pull request against this repository: https://github.com/mdn/browser-compat-data.
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Promise | Chrome Full support 32 | Edge Full support Yes | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
Promise() constructor | Chrome Full support 32 | Edge Full support Yes | Firefox
Full support
29
| IE No support No | Opera Full support 19 | Safari
Full support
8
| WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android
Full support
29
| Opera Android Full support Yes | Safari iOS
Full support
8
| Samsung Internet Android Full support Yes | nodejs
Full support
0.12
|
all | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
prototype | Chrome Full support 32 | Edge Full support Yes | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
catch | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
finally | Chrome Full support 63 | Edge Full support 18 | Firefox Full support 58 | IE No support No | Opera Full support 50 | Safari Full support 11.1 | WebView Android Full support 63 | Chrome Android Full support 63 | Edge Mobile No support No | Firefox Android Full support 58 | Opera Android Full support 46 | Safari iOS Full support 11.1 | Samsung Internet Android No support No | nodejs Full support 10.0.0 |
then | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
race | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
reject | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |
resolve | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 29 | IE No support No | Opera Full support 19 | Safari Full support 8 | WebView Android Full support 4.4.3 | Chrome Android Full support 32 | Edge Mobile Full support Yes | Firefox Android Full support 29 | Opera Android Full support Yes | Safari iOS Full support 8 | Samsung Internet Android Full support Yes | nodejs Full support 0.12 |