Promise

You’re reading the English version of this content since no translation exists yet for this locale. Help us translate this article!

Promise обектът представлява евентуалният завършек (или неуспех) на една асинхронна операция и нейната получена стойност.

Бележка:  Тази статия описва Promise конструктора и методите и свойствата на такива обекти. За да научите начина по който работят promisesи как може да ги използвате , съветваме ви първо да прочетете Как да използваме promises.  Конструктора се използва предимно за обхващане на функции, които вече не поддържат promises

Синтаксис

new Promise(executor);

Параметри

екзекутор (executor)
Функция , която се предава с аргументи resolve и reject. Екзекутор (executor) функцията се изпълнява незабавно след  изпълнението на Promise, предава resolve и reject функции (Екзекутора (executor) се извиква преди Promise конструктора , дори връща създадения обект). resolve и reject функциите, когато се извикват, разрешават или отхвърлят съответния  promise. Екзекутора (executor) обикновено инициира някаква асинхронна работа и след като веднъж приключи, извиква resolve функцията, за да разреши promise или дори да го отхвъли ако възникне грешка. Ако възникне грешка в екзекутора (executor) , promise  се отхвърля и върнатата стойност от екзекутора (executor) се отхвърля.

Описание

Promise е прокси за стойността, която не е непременно известна , когато се създава promise. Позволява ви да свържете манипулаторите с асинхронно действие, евентуално връщайки успешна стойност или грешка. Това позволява асинхронните методи да връщат стойност като синхронни методи: вместо да ни върне незабавно финална стойност, асинхронния метод връща promise, който да ни предостави стойността в някакъв бъдещ момент.

Promise се намира в едно от тези състояния:

  • pending (изчакващо): първоначално състояние, нито изпълнено или отхвърлено.
  • fulfilled (изпълнено): означава , че операцията е завършила успешно.
  • rejected (отказано): означава , че операцията не е завършила успешно.

Изчакващият promise може да бъде изпълнен със стойност или отказан с описание за грешка. Когато някоя от тези опции се случи, се извикват асоциираните манипулатори, поставени на опашка, след което се извикват then методите. (Ако promise вече е бил изпълнен или отказан, когато е приложен съответния манипулатор , манипулатора ще бъде извикан. Така че няма никакво състезателно условие между завършването на асинхронната операция и манипулаторите които са и били приложени.)

Като Promise.prototype.then() и Promise.prototype.catch() методи връщат promises, те могат да бъдат обхванати.

Забележка, не трябва да се бърка с:  Няколко дргуи езика имат механизъм за мързеливо (lazy) оценяване и отлагане на изчисления, които те също наричат "promises" ... схема. Promises в JavaScript представляват процеси, които вече се случват и могат да бъдат обхванати с функции за обратно извикване (callback functions).  Ако търсите мързеливо да изчислите израз, разгледайте функциите със стрелка (arrow function) без аргументи: f = () => израз(expression) за създаване на мързеливо-изчислителен израз  и f() за изчисление.

Забележка: Казва се че Promise се счита за установен ако е изпълнен или отказан, но не изчакващ. Също така ще чуете и термина resolved, който се изпозлва с promises — това означава че promise е установен или “заключен”, изчаквайки да съответства на състоянието на друг promise. States and fates съдържа повече детайли относно promise терминологията.

Свойства

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

Методи

Promise.all(iterable)
Изчаква всички promises да бъдат разрешени или отказани.
Ако върнатия promise е решен(resolves), той се решава с агрегиращ масив от стойности от разрешените promises в същата последователност, както е дефиниран в многобройните promises. Ако е отхвърлен, той се отхвърля с причина от първият promise който е бил отказан.
Promise.allSettled()
Изчаква докато всички promises са приключени/уредени (всеки може да бъде разрешен или отказан).
Връща promise което се решава след всички дадени promises били те разрешени или отказани, с масив от обекти , които описват резултата от всеки promise.
Promise.race(iterable)
Изчаква докато някой от promises е разрешен или отказан.
Ако върнатият promise е разрешен,е разрешен със стойноста от първият promise.Ако е отказан, е отакзан с причината от първият promise който е бил отказан.
Promise.reject()
Връща нов Promise обект, който е отказан с предоставена причина.
Promise.resolve()
Връща нов Promise който е разрешен с дадената му стойност. Ако стойността е  thenable (i.e. има then метод), върнатият promise ще "следва" този thenable, приемайки евентуалното му състояние; в противен случай върнатия promise ще бъде запълнен със стойността. Обикновенно ако не знаете дадена стойност дали е promise или не, Promise.resolve(value) замества и работи с върнатата стойност като promise.

Promise прототип

Свойства

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

Методи

Promise.prototype.catch()
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()
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).
Promise.prototype.finally()
Appends a handler to the promise, and returns a new promise which is resolved when the original promise is resolved. The handler is called when the promise is settled, whether fulfilled or rejected.

Създаване на Promise

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

const myFirstPromise = new Promise((resolve, reject) => {
  // do something asynchronous which eventually calls either:
  //
  //   resolve(someValue); // fulfilled
  // or
  //   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((resolve, reject) => {
  // We call resolve(...) when what we were doing asynchronously was successful, and reject(...) when it failed.
  // In this example, we use setTimeout(...) to simulate async code. 
  // In reality, you will probably be using something like XHR or an HTML5 API.
  setTimeout(function(){
    resolve("Success!"); // Yay! Everything went well!
  }, 250);
});

myFirstPromise.then((successMessage) => {
  // successMessage is whatever we passed in the resolve(...) function above.
  // It doesn't have to be a string, but if it is only a succeed message, it probably will be.
  console.log("Yay! " + successMessage);
});

Разширени примери

Този малък пример показва механизма на Promise. testPromise() метод се извиква всеки път когато  <button> е натиснат. Създава promise който ще бъде изпълнен, използвайки window.setTimeout(), към promise броенето(номер започващ от 1) на всеки 1-3 секунди на случаен принцип. The Promise() се използва за създаването на promise.

Изпълнението на promise е просто записано, чрез сет за обратно извикване (callback set) , използвайки p1.then(). Няколко logs (данни) показват как синхронната част на метода е отделена от асинхронното завършване на обещанието.

'use strict';
var promiseCount = 0;

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

    let 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)
    let p1 = new Promise(
        // The executor function is called with the ability to resolve or
        // reject the promise
       (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 with the then() call,
    // and what to do when the promise is rejected with the catch() call
    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
       (reason) => {
            console.log('Handle rejected promise ('+reason+') here.');
        });

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

Този пример ще се стартира като кликнете на бутона. Имате нужда от браузер който поддържа Promise. Натискайки на бутона няколко пъти в кратки периоди от време , ще видите дори разллични promises , които се изпълняват един след друг.

Зареждане на снимка с XHR

Друг опростен пример използва Promise и XMLHttpRequest за зареждане на снимки е наличен в GitHub профила на MDN и се казва js-examples. Тук също може да го видите и в действие see it in action. Всяка стъпка е коментирана и ви позволява да следвате Promise и XHR архитектурата внимателно.

Спецификации

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

Съвместимост с браузърите

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
PromiseChrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
Promise() constructorChrome Full support 32Edge Full support 12Firefox Full support 29
Notes
Full support 29
Notes
Notes Constructor requires a new operator since version 37.
IE No support NoOpera Full support 19Safari Full support 8
Notes
Full support 8
Notes
Notes Constructor requires a new operator since version 10.
WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29
Notes
Full support 29
Notes
Notes Constructor requires a new operator since version 37.
Opera Android Full support YesSafari iOS Full support 8
Notes
Full support 8
Notes
Notes Constructor requires a new operator since version 10.
Samsung Internet Android Full support 2.0nodejs Full support 0.12
Notes
Full support 0.12
Notes
Notes Constructor requires a new operator since version 4.
all()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
allSettled()Chrome Full support 76Edge No support NoFirefox Full support 71IE No support NoOpera ? Safari ? WebView Android Full support 76Chrome Android Full support 76Firefox Android No support NoOpera Android Full support YesSafari iOS ? Samsung Internet Android No support Nonodejs Full support 12.9.0
catch()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
finally()Chrome Full support 63Edge Full support 18Firefox Full support 58IE No support NoOpera Full support 50Safari Full support 11.1WebView Android Full support 63Chrome Android Full support 63Firefox Android Full support 58Opera Android Full support 46Safari iOS Full support 11.3Samsung Internet Android Full support 8.0nodejs Full support 10.0.0
prototypeChrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
race()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
reject()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
resolve()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12
then()Chrome Full support 32Edge Full support 12Firefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Firefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support 2.0nodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

See also