Promise

BaselineWidely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Сводка

ОбъектPromise используется для отложенных и асинхронных вычислений.

Интерактивный пример

const promise1 = new Promise((resolve, reject) => {  setTimeout(() => {    resolve("foo");  }, 300);});promise1.then((value) => {  console.log(value);  // Expected output: "foo"});console.log(promise1);// Expected output: [object Promise]

Синтаксис

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

Параметры

executor: Объект функции с двумя аргументамиresolve иreject. Функцияexecutor получает оба аргумента и выполняется сразу, ещё до того как конструктор вернёт созданный объект. Первый аргумент (resolve) вызывает успешное исполнение промиса, второй (reject) отклоняет его.Обычно функцияexecutor описывает выполнение какой-то асинхронной работы, по завершении которой необходимо вызвать функциюresolve илиreject. Обратите внимание, что возвращаемое значение функцииexecutor игнорируется.

ИнтерфейсPromise (промис) представляет собой обёртку для значения, неизвестного на момент создания промиса. Он позволяет обрабатывать результаты асинхронных операций так, как если бы они были синхронными: вместо конечного результата асинхронного метода возвращается своего родаобещание (дословный перевод слова "промис") получить результат в некоторый момент в будущем.

Promise может находиться в трёх состояниях:

ожидание (pending): начальное состояние, не исполнен и не отклонён.
исполнено (fulfilled): операция завершена успешно.
отклонено (rejected): операция завершена с ошибкой.

При создании промис находится вожидании (pending), а затем может статьисполненным (fulfilled), вернув полученный результат (значение), илиотклонённым (rejected), вернув причину отказа. В любом из этих случаев вызывается обработчик, прикреплённый к промису методомthen. (Если в момент назначения обработчика промис уже исполнен или отклонён, обработчик всё равно будет вызван, т.е. асинхронное исполнение промиса и назначение обработчика не будет происходить в «состоянии гонки», как, например, в случае с событиями в DOM.)

Так как методыPromise.prototype.then() иPromise.prototype.catch() сами возвращают промис, их можно вызывать цепочкой, создаваясоединения.

Примечание:Говорят, что промис находится в состояниизавершён (settled) когда он или исполнен или отклонён, т.е. в любом состоянии, кроме ожидания (это лишь форма речи, не являющаяся настоящим состоянием промиса). Также можно встретить терминисполнен (resolved) — это значит что промисзавершён или "заблокирован" в ожидании завершения другого промиса. В статьесостояния и fates приводится более подробное описание терминологии.

Свойства

Promise.length: Значение свойства всегда равно 1 (количество аргументов конструктора).
Promise.prototype: Представляет прототип для конструктораPromise.

Методы

Promise.all(iterable)

Ожидает исполнения всех промисов или отклонения любого из них.

Возвращает промис, который исполнится после исполнения всех промисов вiterable. В случае, если любой из промисов будет отклонён,Promise.all будет также отклонён.

Promise.allSettled(iterable)

Ожидает завершения всех полученных промисов (как исполнения так и отклонения).

Возвращает промис, который исполняется когда все полученные промисы завершены (исполнены или отклонены), содержащий массив результатов исполнения полученных промисов.

Promise.race(iterable)

Ожидает исполнения или отклонения любого из полученных промисов.

Возвращает промис, который будет исполнен или отклонён с результатом исполнения первого исполненного или отклонённого промиса изiterable.

Promise.reject(reason)

Возвращает промис, отклонённый из-заreason.

Promise.resolve(value)

Возвращает промис, исполненный с результатомvalue.

Создание промиса

ОбъектPromise создаётся при помощи ключевого словаnew и своего конструктора. КонструкторPromise принимает в качестве аргумента функцию, называемую "исполнитель" (executor function). Эта функция должна принимать две функции-колбэка в качестве параметров. Первый из них (resolve) вызывается, когда асинхронная операция завершилась успешно и вернула результат своего исполнения в виде значения. Второй колбэк (reject) вызывается, когда операция не удалась, и возвращает значение, указывающее на причину неудачи, чаще всего объект ошибки.

const myFirstPromise = new Promise((resolve, reject) => {  // выполняется асинхронная операция, которая в итоге вызовет:  //  //   resolve(someValue); // успешное завершение  // или  //   reject("failure reason"); // неудача});

Чтобы снабдить функцию функциональностью промисов, нужно просто вернуть в ней объект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();  });}

Примеры

Простой пример

html

Создать промис!

let myFirstPromise = new Promise((resolve, reject) => {  // Мы вызываем resolve(...), когда асинхронная операция завершилась успешно, и reject(...), когда она не удалась.  // В этом примере мы используем setTimeout(...), чтобы симулировать асинхронный код.  // В реальности вы, скорее всего, будете использовать XHR, HTML5 API или что-то подобное.  setTimeout(function () {    resolve("Success!"); // Ура! Всё прошло хорошо!  }, 250);});myFirstPromise.then((successMessage) => {  // successMessage - это что угодно, что мы передали в функцию resolve(...) выше.  // Это необязательно строка, но если это всего лишь сообщение об успешном завершении, это наверняка будет она.  console.log("Ура! " + successMessage);});

Продвинутый пример

html

Создать промис!

html

<button>Создать Promise!</button><div></div>

Данный небольшой пример показывает механизм работы сPromise. МетодtestPromise() вызывается при каждом нажатии на<button>. При этом создаётся промис, который успешно выполняется при помощиwindow.setTimeout, со значением'result' в случайном интервале от 1 до 3-х секунд.

исполнение промиса протоколируется при помощи продолженияp1.then. Это показывает как синхронная часть метода отвязана от асинхронного завершения промиса.

var promiseCount = 0;function testPromise() {  var thisPromiseCount = ++promiseCount;  var log = document.getElementById('log');  log.insertAdjacentHTML('beforeend', thisPromiseCount +      ') Запуск (запуск синхронного кода)');  // Создаём промис, возвращающее 'result' (по истечении 3-х секунд)  var p1 = new Promise(    // Функция разрешения позволяет завершить успешно или    // отклонить промис    function(resolve, reject) {      log.insertAdjacentHTML('beforeend', thisPromiseCount +          ') Запуск промиса (запуск асинхронного кода)');      // Это всего лишь пример асинхронности      window.setTimeout(        function() {          // Промис исполнен!          resolve(thisPromiseCount)        }, Math.random() * 2000 + 1000);    });  // Указываем, что сделать с исполненным промисом  p1.then(    // Записываем в протокол    function(val) {      log.insertAdjacentHTML('beforeend', val +          ') Промис исполнен (асинхронный код завершён)');    });  log.insertAdjacentHTML('beforeend', thisPromiseCount +      ') Промис создан (синхронный код завершён)');}

if ("Promise" in window) {  btn = document.getElementById("btn");  btn.addEventListener("click", testPromise);} else {  log = document.getElementById("log");  log.innerHTML =    "Live example not available as your browser doesn't support the Promise interface.";}

if ("Promise" in window) {  let btn = document.getElementById("btn");  btn.addEventListener("click", testPromise);} else {  log = document.getElementById("log");  log.innerHTML =    "Демонстрация невозможна, поскольку ваш браузер не поддерживает интерфейс <code>Promise<code>.";}

Данный пример запускается при нажатии на кнопку. Для этого вам необходим браузер, поддерживающийPromise. При последовательных нажатиях на кнопку с коротким интервалом, вы можете увидеть как различные промиса будут исполнены один за другим.

Загрузка изображения при помощи XHR

Другой простой пример использованияPromise иXMLHttpRequest для загрузки изображения доступен в репозитории MDNpromise-test на GitHub. Вы также можетепосмотреть его в действии. Каждый шаг прокомментирован и вы можете подробно исследовать Promise и XHR.