To tłumaczenie jest niekompletne. Pomóż przetłumaczyć ten artykuł z języka angielskiego.

Obiekt Promise reprezentuje ewentualne zakończenie (lub porażkę) asynchronicznej operacji i jej wartości.

Artykuł opisuje konstruktor, metody i właściwości obiektu Promise. By nauczyć się jak działają obietnice i jak można ich używać zalecamy przzeczytać najpierw Użycie obietnic . Ten konstruktor jest głównie używany do opakowania funkcji, które nie wspierają jeszcze obietnic.

Składnia

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

Parametry

wykonawca (executor)
Funkcja przekazywana z argumentami resolve i reject. Funkcja ta wykonywana jest natychmiast przez implementację obietnicy, przekazując funkcje resolve i reject (ta funkcja jest wywoływana, zanim konstruktor Promise zwróci utworzony obiekt). Funkcje resolve i reject , gdy są wywoływane, odpowiednio rozwiązują lub odrzucają obietnicę. Ta funkcja zwykle inicjuje pracę asynchroniczną, a następnie, po jej zakończeniu, wywołuje funkcję resolve w celu rozwiązania obietnicy lub odrzuca ją, jeśli wystąpił błąd. Jeśli błąd zostanie zgłoszony w tej funkcji, obietnica zostaje odrzucona. Wartość zwracana tej funkcji jest ignorowana.

Opis

Promise jest proxy dla wartości niekoniecznie znanej, gdy jest tworzona. Pozwala na kojarzenie uchwytu z ewentualnym sukcesem lub porażką asynchroniczne akcji. Pozwala to metodom asynchronicznym zwracać wartości takie jak metody synchroniczne, zamiast natychmiastowego zwracania wartości końcowej, metoda asynchroniczna zwraca obietnicę dostarczenia wartości w pewnym momencie w przyszłości.

Promise jest dostpny w jednym z tych stanów:

  • pending: stan inicjacji, ani wypełnione, ani odrzucone.
  • fulfilled: operacja zakończona sukcesem.
  • rejected: operacja zakończona porażką.

Obowiązująca objetnica może być zakończona z wartością lub odrzucona z powodem(błędem). Kiedy dzieje się jedna z tych opcji, wywoływane są zakolejkowane, powiązane za pomocą metody then procedury. (Jeśli obietnica została już spełniona lub odrzucona, gdy dołączony jest odpowiedni moduł obsługi, zostanie on wywołany, więc nie ma potrzeby wyścigu między zakończeniem operacji asynchronicznej a jej obsługą).

Tak jak w Promise.prototype.then() oraz Promise.prototype.catch() gdy metoda zwróci obietnice, mogą one być łączone w łańcuchy.

Nie mylić z: Kilka innych języków ma mechanizmy leniwego oceniania i odraczania obliczeń, które nazywają również "obietnicami", np. Scheme. Obietnice w JavaScript oznaczają procesy, które już się odbywają, które mogą być powiązane z funkcjami wywołania zwrotnego. Jeśli chcesz leniwie oceniać wyrażenie, rozważ  funkcje strzałkowe bez argumentów: f = () => wyrażenie by stworzyć leniwo oszacowane wyrażenie, i f() by ocenić.

Mówi się, że obietnica zostanie uregulowana, jeśli zostanie spełniona lub odrzucona, ale nie oczekuje na rozpatrzenie. Usłyszysz także termin rozwiązany używany z obietnicami - oznacza to, że obietnica jest ustalona lub "zamknięta", aby dopasować się do stanu innej obietnicy. Stany i losy zawierają więcej szczegółów na temat obiecanej terminologii.

Właściwości

Promise.length
Właściwość Length, której wartość wynosi zawsze 1 (liczba argumentów konstruktora).
Promise.prototype
Reprezentuje prototyp konstruktora Promise.

Metody

Promise.all(iterable)
Zwraca obietnice, która albo kończy się sukcesem gdy wszystkie z obietnic w iterable się zakończą powodzeniem lub kończy sie porażką tak szybko jak jedna z obietnic skończy się porażką. Jeżeli zwrócona obietnica kończy się sukcesem jest ona wypełniana tablicą wartości z obietnic zakończonych sukcesem w takim samym układzie jak były one zdefiniowane w iterable. Jeżeli zwrócona obietnica zakończyła się porażką, jest ona odrzucana z Powodem z pierwszej obietnicy w iterable, która zakończyła się porażką. Ta metoda może być pomocna do zachowywania rezultatów różnych obietnic.
Promise.race(iterable)
Returns a promise that fulfills or rejects as soon as one of the promises in the iterable fulfills or rejects, with the value or reason from that promise.
Promise.reject(reason)
Returns a Promise object that is rejected with the given reason.
Promise.resolve(value)
Returns a Promise object that is resolved with the given value. If the value is a thenable (i.e. has a then method), the returned promise will "follow" that thenable, adopting its eventual state; otherwise the returned promise will be fulfilled with the value. Generally, if you don't know if a value is a promise or not, Promise.resolve(value) it instead and work with the return value as a promise.

Promise prototype

Właściwości

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

Metody

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).
Promise.prototype.finally(onFinally)
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.

Tworzenie Promise

A Promise object is created using the new keyword and its constructor. This constructor takes as its argument a function, called the "executor function". This function should take two functions as parameters. The first of these functions (resolve) is called when the asynchronous task completes successfully and returns the results of the task as a value. The second (reject) is called when the task fails, and returns the reason for failure, which is typically an error object.

const myFirstPromise = new Promise((resolve, reject) => {
  // do something asynchronous which eventually calls either:
  //
  //   resolve(someValue); // fulfilled
  // or
  //   reject("failure reason"); // rejected
});

To provide a function with promise functionality, simply have it return a 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();
  });
}

Przykłady

Podstawowy przykład

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);
});

Zaawansowany Przykład

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 show how the synchronous part of the method is decoupled from the asynchronous completion of the promise.

'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 resolver 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/>');
}

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.

Ładowanie obrazka z XHR

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

Specyfikacja

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  

Zgodność z przeglądarkami

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung InternetNode.js
Basic supportChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
Promise() constructorChrome Full support 32Edge Full support YesFirefox 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 32Edge Mobile Full support YesFirefox 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 Yesnodejs Full support 0.12
Notes
Full support 0.12
Notes
Notes Constructor requires a new operator since version 4.
allChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
prototypeChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
catchChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
finallyChrome Full support 63Edge No support NoFirefox Full support 58IE No support NoOpera Full support 50Safari Full support 11.1WebView Android Full support 63Chrome Android Full support 63Edge Mobile No support NoFirefox Android Full support 58Opera Android Full support 50Safari iOS Full support 11.1Samsung Internet Android No support Nonodejs Full support 10.0.0
thenChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
raceChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
rejectChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12
resolveChrome Full support 32Edge Full support YesFirefox Full support 29IE No support NoOpera Full support 19Safari Full support 8WebView Android Full support 4.4.3Chrome Android Full support 32Edge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support 8Samsung Internet Android Full support Yesnodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Zobacz również

Autorzy i etykiety dokumentu

Etykiety: 
Autorzy tej strony: SkillGG, szopenkrk
Ostatnia aktualizacja: SkillGG,