这是用户在 2024-9-23 15:38 为 https://promisesaplus.com/ 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?

Promises/A+

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,而是将重点放在提供一种可互操作的方法。配套规范的未来工作可能会涉及这些主题。

Terminology

  1. “promise” is an object or function with a then method whose behavior conforms to this specification.
    "promise"是一个对象或函数,它有一个行为符合本规范的then方法。
  2. “thenable” is an object or function that defines a then method.
    "thenable"是定义then方法的对象或函数。
  3. “value” is any legal JavaScript value (including undefined, a thenable, or a promise).
    "value "是任何合法的 JavaScript 值(包括未定义、thenable 或promise)。
  4. “exception” is a value that is thrown using the throw statement.
    "异常 "是使用throw语句抛出的值。
  5. “reason” is a value that indicates why a promise was rejected.
    "原因 "是一个值,表示拒绝promise原因。

Requirements

Promise States

A promise must be in one of three states: pending, fulfilled, or rejected.
promise必须处于三种状态之一:待定、已履行或已拒绝。

  1. When pending, a promise:  待定,就是promise:
    1. may transition to either the fulfilled or rejected state.
      可过渡到满足或拒绝状态。
  2. When fulfilled, a promise:
    一旦实现,就是promise:
    1. must not transition to any other state.
      不得过渡到任何其他状态。
    2. must have a value, which must not change.
      必须有一个值,且该值不得更改。
  3. When rejected, a promise:
    当被拒绝时,一个promise:
    1. must not transition to any other state.
      不得过渡到任何其他状态。
    2. must have a reason, which must not change.
      必须有一个理由,而这个理由绝不能改变。

Here, “must not change” means immutable identity (i.e. ===), but does not imply deep immutability.
在这里,"不得改变 "指的是不变的特性(即===),但并不意味着深度不变性。

The 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)
  1. Both onFulfilled and onRejected are optional arguments:
    onFulfilledonRejected 都是可选参数:
    1. If onFulfilled is not a function, it must be ignored.
      如果onFulfilled不是函数,则必须忽略。
    2. If onRejected is not a function, it must be ignored.
      如果onRejected不是函数,则必须忽略。
  2. If onFulfilled is a function:
    如果onFulfilled是一个函数:
    1. it must be called after promise is fulfilled, with promise’s value as its first argument.
      必须在履行承诺后调用,并以承诺值作为第一个参数。
    2. it must not be called before promise is fulfilled.
      承诺兑现之前不得调用。
    3. it must not be called more than once.
      不得多次调用。
  3. If onRejected is a function,
    如果onRejected是一个函数、
    1. it must be called after promise is rejected, with promise’s reason as its first argument.
      必须在拒绝promise后调用,并以promise的理由作为第一个参数。
    2. it must not be called before promise is rejected.
      在拒绝许诺之前,不得调用它。
    3. it must not be called more than once.
      不得多次调用。
  4. onFulfilled or onRejected must not be called until the execution context stack contains only platform code. [3.1].
    执行上下文堆栈只包含平台代码之前,不得调用onFulfilledonRejected[3.1].
  5. onFulfilled and onRejected must be called as functions (i.e. with no this value). [3.2]
    onFulfilledonRejected必须作为函数调用(即不带值)。[3.2]
  6. then may be called multiple times on the same promise.
    可在同一promise上被多次调用。
    1. If/when promise is fulfilled, all respective onFulfilled callbacks must execute in the order of their originating calls to then.
      如果/当承诺被履行,所有相应的onFulfilled回调必须按照其最初调用的顺序执行。
    2. If/when promise is rejected, all respective onRejected callbacks must execute in the order of their originating calls to then.
      如果/当承诺被拒绝,所有相应的onRejected回调都必须按其最初调用的顺序执行。
  7. then must return a promise [3.3].
    必须返回一个promise[3.3]。

     promise2 = promise1.then(onFulfilled, onRejected);
    
    1. If either onFulfilled or onRejected returns a value x, run the Promise Resolution Procedure [[Resolve]](promise2, x).
      如果onFulfilledonRejected返回值为x 则运行Promise解析过程[[Resolve]](promise2, x)
    2. If either onFulfilled or onRejected throws an exception e, promise2 must be rejected with e as the reason.
      如果 onFulfilledonRejected 出现异常, e , promise2 必须被拒绝,理由是 e
    3. If onFulfilled is not a function and promise1 is fulfilled, promise2 must be fulfilled with the same value as promise1.
      如果onFulfilled不是函数,且promise1已实现,则promise2必须以与promise1 相同的值实现。
    4. If 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
Promise解决程序

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),请执行以下步骤:

  1. If promise and x refer to the same object, reject promise with a TypeError as the reason.
    如果promisex指向同一个对象,则以TypeError作为理由拒绝promise
  2. If x is a promise, adopt its state [3.4]:
    如果x是promise,则采用其状态[3.4]:
    1. If x is pending, promise must remain pending until x is fulfilled or rejected.
      如果x处于待定状态,则承诺必须保持待定状态,直到x满足或被拒绝。
    2. If/when x is fulfilled, fulfill promise with the same value.
      如果/当x实现时,以相同的值履行承诺
    3. If/when x is rejected, reject promise with the same reason.
      如果/当x被拒绝时,以同样的理由拒绝承诺
  3. Otherwise, if x is an object or function,
    否则,如果x是一个对象或函数、
    1. Let then be x.then. [3.5]
      then 成为 x.then 。[ 3.5]
    2. If retrieving the property x.then results in a thrown exception e, reject promise with e as the reason.
      如果检索x.then属性导致抛出异常e,则以e为理由拒绝接受承诺
    3. If then is a function, call it with x as this, first argument resolvePromise, and second argument rejectPromise, where:
      如果then是一个函数,则以xthis、第一个参数resolvePromise 和第二个参数rejectPromise 调用它,其中
      1. If/when resolvePromise is called with a value y, run [[Resolve]](promise, y).
        如果/当 resolvePromise 被调用且值为 y 时,运行 [[Resolve]](promise, y)
      2. If/when rejectPromise is called with a reason r, reject promise with r.
        如果/当 rejectPromise 被调用时,理由是 r ,则用 r 拒绝 promise
      3. If both 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.
        如果同时调用resolvePromiserejectPromise,或对同一参数进行多次调用,则以第一次调用为准,以后的调用将被忽略。
      4. If calling then throws an exception e,
        如果调用 then 会出现异常 e
        1. If resolvePromise or rejectPromise have been called, ignore it.
          如果已调用 resolvePromiserejectPromise ,请忽略它。
        2. Otherwise, reject promise with e as the reason.
          否则,拒绝 promise ,理由是 e
    4. If then is not a function, fulfill promise with x.
      如果 then 不是函数,则用 x 完成 promise
  4. If 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作为理由拒绝promise[3.6]

Notes

  1. 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实现代码。在实践中,这一要求可确保onFulfilledonRejected在调用它们的事件循环转折之后异步执行,并使用新的堆栈。这可以通过setTimeoutsetImmediate 等 "宏任务 "机制或MutationObserverprocess.nextTick 等 "微任务 "机制来实现。由于promise实现被视为平台代码,因此它本身可能包含一个任务调度队列或 "蹦床",处理程序就在其中被调用。

  2. That is, in strict mode this will be undefined inside of them; in sloppy mode, it will be the global object.
    也就是说,在严格模式下,这在它们内部是未定义的;而在粗放模式下,它将是全局对象。

  3. 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以及在什么条件下产生。

  4. 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的状态。

  5. 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属性的多次访问。这种预防措施对于确保访问者属性的一致性非常重要,因为访问者属性的值可能会在两次检索之间发生变化。

  6. 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 的无限链,那么永远递归才是正确的行为。


CC0
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 的所有版权及相关或邻接权。本作品发布于: 美国