MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

Переклад не закінчено. Будь ласка, допоможіть перекласти цю статтю з англійської.

Об'єкти Promise (обіцянка) використовуються для асинхронних операцій і обчислень. Promise повертає значення, яке може бути доступним зараз, або через де-який час, або ніколи.

Syntax

new Promise( /* executor */ function(resolve, reject) { ... } );

Parameters

executor (виконавець)
Функція, яку передають із параметрами resolve та reject. Ця функція виконується одразу, як тільки программа доходить до визову Promise. Параметри resolve та reject містять посилання на відповідні функції (або можна передати анонімні функції) (executor викликається перед Promise constructor, навіть якщо повертається створенний об'єкт). Коли викликаються функції resolve та reject,  promise обробляє вдале завершення (resolve) або реагує на невдачу (reject). Еxecutor ініціює якусь асинхронну роботу. Потім, якщо робота завершилась вдало, викликає функцію resolve. Якщо під час виконання роботи сталась якась помилка, то викликає функцію reject. У разі помилки, программа ігнорує значення, якае повертає executor.
 

Description

Promise - це представник значення, яке може бути невідомим на момент створення promise.  Це дозволяє вам зв'язати обробники з можливими асинхронними діями у випадку вдалого виконнання або помилки. Таким чином асинхронні методи повертають значення так само, як синхронні методи - замість негайного отримання значення, асинхронний метод повертає promise , щоб повернути значення у майбутньому, коли воно буде готове. Наприклад, буде чекати завершення запиту до бази данних або чекати відподь з віддаленного серверу.

Promise може бути в одному із цих станів:

  • pending: в очікуванні, початковий стан, нема відповіді або помилки.
  • fulfilled: завершений, тобто операція завершилася вдало.
  • rejected: означає, що операція завершилася помилкою.

При створенні об'єкт promise знаходиться в стані pending, а потім переходить до стану fulfilled, повертаючи значення отриманого результату, або до стану rejected, повертаючи причину відмови (помилку). В будь-якому випадку при зміні стану викликається метод об'єкта then, який ставить в чергу відповідні обробники. (Якщо promise був виконаний або завершився з помикою ще до моменту приєднання обробника, то обробник буде виконаний, таким чином не "стану гонки" між виконанням асинхронної операції та приєднанням обробника)

Оскільки методи Promise.prototype.then() та Promise.prototype.catch() повертають "обіцянки", вони можуть бути з'єднані в ланцюжки.

Не плутати з: деякі інші мови мають механізми лінивих (відкладених), які також називаються "обіцянками" (promises) - наприклад Scheme. Обіцянки в JavaScript представляють процеси, які вже відбуваються, і які можуть бути зв'язані з функціями зворотного виклику (callbacks). Якщо ви хочете лениво обрахувати вираз, розгляньте  стрілкову функцію  без аргументів: "f = () => вираз", щоб створити лінивий вираз і f () для розрахунку.

Примітка: Обіцянка називається встановленою (settled) якщо вона або виконана, або відхилена, але не занходиться в початковому стані. Також існує термін вирішена (resolved) обіцянка, який означає, що обіцянка встановлена (settled) або ж заблокована в ланцюжку обіцянок.

Властивості

Promise.length
Значення довжини завжди рівне 1 (кількість аргументів конструктора).
Promise.prototype
Представляє прототип для конструктора Promise.

Методи

Promise.all(iterable)
Повертає обіцянку, яка або виконується, коли виконані всі обіцянки в ітерабельному аргументі, або відхиляється, як тільки буде відхилена одна з обіцянок в ітерабельному аргументі. Якщо повернута обіцянка виконується, вона виконується з масивом значень із виконаних обіцянок у тому ж порядку, як і в аргументі. Якщо повернута обіцянка відхиляється, то вона відхиляється з помилкою, взятою з першої відхиленої обіцянки. Цей метод може бути корисним для об'єднання результатів кількох обіцянок.
 
Promise.race(iterable)
Повертає обіцянку, яка виконується або відхиляється  як тільки одна з обіцянок аргументу виконується або відхиляється, з результатом виконання/відмови з цієї обіцянки.
Promise.reject(reason)
Повертає об'єкт Promise, відхилений із заданою причиною.
Promise.resolve(value)
Повертає об'єкт Promise, який вирішується із заданим значенням. Якщо значення може бути продовжено, тобто має метод then, повернута обіцянка буде "слідувати" продовженню, набуваючи його стану; Інакше обіцянка буде виконана з поверненням значення.

Promise prototype

Properties

Promise.prototype.constructor
Returns the function that created an instance's prototype. This is the Promise function by default.

Methods

Promise.prototype.catch(onRejected)
Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled.
Promise.prototype.then(onFulfilled, onRejected)
Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled (i.e. if the relevant handler onFulfilled or onRejected is not a function).

Examples

Creating a Promise

This small example shows the mechanism of a Promise. The testPromise() method is called each time the <button> is clicked. It creates a promise that will be fulfilled, using window.setTimeout(), to the promise count (number starting from 1) every 1-3 seconds, at random. The Promise() constructor is used to create the promise.

The fulfillment of the promise is simply logged, via a fulfill callback set using p1.then(). A few logs shows how the synchronous part of the method is decoupled from the asynchronous completion of the promise.

'use strict';
var promiseCount = 0;

function testPromise() {
    var thisPromiseCount = ++promiseCount;

    var log = document.getElementById('log');
    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Started (<small>Sync code started</small>)<br/>');

    // We make a new promise: we promise a numeric count of this promise, starting from 1 (after waiting 3s)
    var p1 = new Promise(
        // The resolver function is called with the ability to resolve or
        // reject the promise
        function(resolve, reject) {
            log.insertAdjacentHTML('beforeend', thisPromiseCount +
                ') Promise started (<small>Async code started</small>)<br/>');
            // This is only an example to create asynchronism
            window.setTimeout(
                function() {
                    // We fulfill the promise !
                    resolve(thisPromiseCount);
                }, Math.random() * 2000 + 1000);
        }
    );

    // We define what to do when the promise is resolved/fulfilled with the then() call,
    // and the catch() method defines what to do if the promise is rejected.
    p1.then(
        // Log the fulfillment value
        function(val) {
            log.insertAdjacentHTML('beforeend', val +
                ') Promise fulfilled (<small>Async code terminated</small>)<br/>');
        })
    .catch(
        // Log the rejection reason
        function(reason) {
            console.log('Handle rejected promise ('+reason+') here.');
        });

    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Promise made (<small>Sync code terminated</small>)<br/>');
}

This example is started by clicking the button. You need a browser that supports Promise. By clicking the button several times in a short amount of time, you'll even see the different promises being fulfilled one after another.

Loading an image with XHR

Another simple example using Promise and XMLHttpRequest to load an image is available at the MDN GitHub promise-test repository. You can also see it in action. Each step is commented and allows you to follow the Promise and XHR architecture closely.

Specifications

Specification Status Comment
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'Promise' in that specification.
Standard Initial definition in an ECMA standard.
ECMAScript Latest Draft (ECMA-262)
The definition of 'Promise' in that specification.
Draft  

Browser compatibility

No compatibility data found. Please contribute data for "javascript/promise" to the MDN compatibility data repository.

See also

Мітки документа й учасники

 Зробили внесок у цю сторінку: oldhermit, AlinaKuzmenko, bsurai, kdex
 Востаннє оновлена: oldhermit,