An open standard for sound, interoperable JavaScript promises—by implementers, for implementers.
一个健全的、可互操作的 JavaScript 的开放标准由实现者promises ,为实现者承诺。
A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then
method, which registers callbacks to receive either a promise’s eventual value or the reason why the promise cannot be fulfilled.
promise代表异步操作的最终结果。与promise交互的主要方式是通过其then
方法,该方法注册回调以接收promise的最终值或promise无法实现的原因。
This specification details the behavior of the then
method, providing an interoperable base which all Promises/A+ conformant promise implementations can be depended on to provide. As such, the specification should be considered very stable. Although the Promises/A+ organization may occasionally revise this specification with minor backward-compatible changes to address newly-discovered corner cases, we will integrate large or backward-incompatible changes only after careful consideration, discussion, and testing.
本规范详细说明了then
方法的行为,为所有符合Promises 的promise实现提供了一个可互操作的基础。因此,该规范应被视为非常稳定。尽管Promises 组织可能会偶尔对本规范进行一些小的向后兼容的修改,以解决新发现的角落情况,但我们只有在仔细考虑、讨论和测试之后,才会整合大的或向后不兼容的修改。
Historically, Promises/A+ clarifies the behavioral clauses of the earlier Promises/A proposal, extending it to cover de facto behaviors and omitting parts that are underspecified or problematic.
从历史上看,Promises 阐明了早期Promises 提案中的行为条款,将其扩展到包括事实上的行为,并省略了未充分说明或有问题的部分。
Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable then
method. Future work in companion specifications may touch on these subjects.
最后,核心Promises 规范并不涉及如何创建、履行或拒绝promises,而是将重点放在提供一种可互操作的方法上
。配套规范的未来工作可能会涉及这些主题。
then
method whose behavior conforms to this specification.then
方法。then
method."thenable
"是定义then
方法的对象或函数。undefined
, a thenable, or a promise).未定义
、thenable 或promise)。throw
statement.throw
语句抛出的值。A promise must be in one of three states: pending, fulfilled, or rejected.
promise必须处于三种状态之一:待定、已履行或已拒绝。
Here, “must not change” means immutable identity (i.e. ===
), but does not imply deep immutability.
在这里,"不得改变 "指的是不变的特性(即===
),但并不意味着深度不变性。
then
Method当时的
方法A promise must provide a then
method to access its current or eventual value or reason.
promise必须提供一个then
方法来访问其当前或最终值或理由。
A promise’s then
method accepts two arguments:
promise的then
方法接受两个参数:
promise.then(onFulfilled, onRejected)
onFulfilled
and onRejected
are optional arguments:
onFulfilled
和 onRejected
都是可选参数:
onFulfilled
is a function:
onFulfilled
是一个函数:
onRejected
is a function,
onRejected
是一个函数、
onFulfilled
or onRejected
must not be called until the execution context stack contains only platform code. [3.1].onRejected
。[3.1].onFulfilled
and onRejected
must be called as functions (i.e. with no this
value). [3.2]onFulfilled
和onRejected
必须作为函数调用(即不带此
值)。[3.2]then
may be called multiple times on the same promise.
则
可在同一promise上被多次调用。promise
is fulfilled, all respective onFulfilled
callbacks must execute in the order of their originating calls to then
.承诺
被履行时
,所有相应的onFulfilled
回调必须按照其最初调用的顺序执行。promise
is rejected, all respective onRejected
callbacks must execute in the order of their originating calls to then
.承诺
被拒绝时
,所有相应的onRejected
回调都必须按其最初调用的顺序执行。then
must return a promise [3.3].则
必须返回一个promise[3.3]。
promise2 = promise1.then(onFulfilled, onRejected);
onFulfilled
or onRejected
returns a value x
, run the Promise Resolution Procedure [[Resolve]](promise2, x)
.onFulfilled
或onRejected
返回值为x
,
则运行Promise解析过程[[Resolve]](promise2, x)
。onFulfilled
or onRejected
throws an exception e
, promise2
must be rejected with e
as the reason.onFulfilled
或 onRejected
出现异常, e
, promise2
必须被拒绝,理由是 e
。onFulfilled
is not a function and promise1
is fulfilled, promise2
must be fulfilled with the same value as promise1
.onFulfilled
不是函数,且promise1
已实现,则promise2
必须以与promise1
相同的值实现。onRejected
is not a function and promise1
is rejected, promise2
must be rejected with the same reason as promise1
.onRejected
不是函数,且promise1
被拒绝,则promise2
必须以与promise1
相同的理由被拒绝。The promise resolution procedure is an abstract operation taking as input a promise and a value, which we denote as [[Resolve]](promise, x)
. If x
is a thenable, it attempts to make promise
adopt the state of x
, under the assumption that x
behaves at least somewhat like a promise. Otherwise, it fulfills promise
with the value x
.
promise解析过程是一个抽象操作,它的输入是一个允诺
和一个值,我们将其命名为[[解析]](
。如果允诺
,x)x
是可promise的,它就会尝试让promise采用x
的状态,前提是x
的行为至少有点像promise。否则,它会用x
的值来实现
。promise
This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliant then
method. It also allows Promises/A+ implementations to “assimilate” nonconformant implementations with reasonable then
methods.
对 thenables 的这种处理方法允许promise实现互操作,只要它们暴露了Promises 的 then
方法。它还允许Promises 实现用合理的then
方法 "同化 "不符合要求的实现。
To run [[Resolve]](promise, x)
, perform the following steps:
要运行[[Resolve]](
,请执行以下步骤:promise
, x)
promise
and x
refer to the same object, reject promise
with a TypeError
as the reason.promise
和x
指向同一个对象,则以TypeError
作为理由拒绝promise
。x
is a promise, adopt its state [3.4]:
x
是promise,则采用其状态[3.4]:
x
is an object or function,
x
是一个对象或函数、then
be x.then
. [3.5]then
成为 x.then
。[ 3.5]x.then
results in a thrown exception e
, reject promise
with e
as the reason.x.then
属性导致抛出异常e
,则以e
为理由拒绝接受承诺
。then
is a function, call it with x
as this
, first argument resolvePromise
, and second argument rejectPromise
, where:
then
是一个函数,则以x
为this
、第一个参数resolvePromise
和第二个参数rejectPromise
调用它,其中resolvePromise
is called with a value y
, run [[Resolve]](promise, y)
.resolvePromise
被调用且值为 y
时,运行 [[Resolve]](promise, y)
。rejectPromise
is called with a reason r
, reject promise
with r
.rejectPromise
被调用时,理由是 r
,则用 r
拒绝 promise
。resolvePromise
and rejectPromise
are called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.resolvePromise
和rejectPromise
,或对同一参数进行多次调用,则以第一次调用为准,以后的调用将被忽略。then
throws an exception e
,
then
会出现异常 e
、
then
is not a function, fulfill promise
with x
.then
不是函数,则用 x
完成 promise
。x
is not an object or function, fulfill promise
with x
.x
不是对象或函数,则用x
履行承诺
。If a promise is resolved with a thenable that participates in a circular thenable chain, such that the recursive nature of [[Resolve]](promise, thenable)
eventually causes [[Resolve]](promise, thenable)
to be called again, following the above algorithm will lead to infinite recursion. Implementations are encouraged, but not required, to detect such recursion and reject promise
with an informative TypeError
as the reason. [3.6]
如果使用参与循环 thenable 链的 thenable 来解决一个promise,从而使 [[Resolve]](promise, thenable)
的递归性质最终导致 [[Resolve]](promise, thenable)
再次被调用,那么按照上述算法将导致无限递归。我们鼓励(但不要求)实现检测这种递归,并以信息丰富的TypeError
作为理由拒绝
。[3.6]promise
Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures that onFulfilled
and onRejected
execute asynchronously, after the event loop turn in which then
is called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such as setTimeout
or setImmediate
, or with a “micro-task” mechanism such as MutationObserver
or process.nextTick
. Since the promise implementation is considered platform code, it may itself contain a task-scheduling queue or “trampoline” in which the handlers are called.
这里的 "平台代码 "是指引擎、环境和promise实现代码。在实践中,这一要求可确保onFulfilled
和onRejected
在调用它们
的事件循环转折之后异步执行,并使用新的堆栈。这可以通过setTimeout
或setImmediate
等 "宏任务 "机制或MutationObserver
或process.nextTick
等 "微任务 "机制来实现。由于promise实现被视为平台代码,因此它本身可能包含一个任务调度队列或 "蹦床",处理程序就在其中被调用。
That is, in strict mode this
will be undefined
inside of them; in sloppy mode, it will be the global object.
也就是说,在严格模式下,这在
它们内部是未定义的
;而在粗放模式下,它将是全局对象。
Implementations may allow promise2 === promise1
, provided the implementation meets all requirements. Each implementation should document whether it can produce promise2 === promise1
and under what conditions.
实现可以允许promise2 === promise1
,前提是实现满足所有要求。每个实现都应记录它能否产生promise2 === promise1
以及在什么条件下产生。
Generally, it will only be known that x
is a true promise if it comes from the current implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant promises.
一般来说,只有当x
来自当前的实现时,我们才会知道它是一个真正的promise。本条款允许使用特定于实现的方法来采用已知符合promises的状态。
This procedure of first storing a reference to x.then
, then testing that reference, and then calling that reference, avoids multiple accesses to the x.then
property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.
首先存储x.then
的引用,然后测试该引用,最后调用该引用,这一过程避免了对x.then
属性的多次访问。这种预防措施对于确保访问者属性的一致性非常重要,因为访问者属性的值可能会在两次检索之间发生变化。
Implementations should not set arbitrary limits on the depth of thenable chains, and assume that beyond that arbitrary limit the recursion will be infinite. Only true cycles should lead to a TypeError
; if an infinite chain of distinct thenables is encountered, recursing forever is the correct behavior.
实现不应对 thenable 链的深度设置任意限制,并假定超出任意限制后递归将是无限的。只有真正的循环才会导致TypeError
;如果遇到不同 thenable 的无限链,那么永远递归才是正确的行为。
To the extent possible under law,
the Promises/A+ organization
has waived all copyright and related or neighboring rights to
Promises/A+ Promise Specification.
This work is published from:
United States.
在法律允许的范围内, Promises 组织已放弃Promises PromiseSpecification 的所有版权及相关或邻接权。本作品发布于: 美国。