path: root/files/pl/web/javascript/referencje/obiekty/promise/index.html

---
title: Promise
slug: Web/JavaScript/Referencje/Obiekty/Promise
tags:
  - JavaScript
  - Obietnice
translation_of: Web/JavaScript/Reference/Global_Objects/Promise
---
<div>{{JSRef}}</div>

<p>Obiekt <strong><code>Promise</code></strong> reprezentuje ewentualne zakończenie (lub porażkę) asynchronicznej operacji i jej wartości.</p>

<div class="note">
<p>Artykuł opisuje konstruktor, metody i właściwości obiektu <code>Promise</code>. By nauczyć się jak działają obietnice i jak można ich używać zalecamy przeczytać najpierw <a href="/en-US/docs/Web/JavaScript/Guide/Using_promises">Użycie obietnic</a> . Ten konstruktor jest głównie używany do opakowania funkcji, które nie wspierają jeszcze obietnic.</p>
</div>

<div>{{EmbedInteractiveExample("pages/js/promise-constructor.html")}}</div>

<p class="hidden">Źródło tego interaktywnego przykładu jest przechowywane w repozytorium GitHub. Jeśli chcesz przyczynić się do interaktywnego projektu sklonuj <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> i wyślij do nas pull request.</p>

<p class="hidden">Źródło tego interaktywnego przykładu jest przechowywane w repozytorium GitHub. Jeśli chcesz przyczynić się do interaktywnego projektu sklonuj <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> i wyślij do nas pull request.</p>

<h2 id="Składnia">Składnia</h2>

<pre class="brush: js notranslate">new Promise( /* wykonawca */ function(resolve, reject) { ... } );</pre>

<h3 id="Parametry">Parametry</h3>

<dl>
 <dt>wykonawca (executor)</dt>
 <dd>Funkcja przekazywana z argumentami <code>resolve</code> i <code>reject</code>. Funkcja ta wykonywana jest natychmiast przez implementację obietnicy, przekazując funkcje <code>resolve</code> i <code>reject</code> (ta funkcja jest wywoływana, zanim konstruktor Promise zwróci utworzony obiekt). Funkcje <code>resolve</code> i <code>reject</code> , 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ę <code>resolve</code> 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.</dd>
</dl>

<h2 id="Opis">Opis</h2>

<p><code><strong>Promise</strong></code> 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 <em>obietnicę </em>dostarczenia wartości w pewnym momencie w przyszłości.</p>

<p><code>Promise</code> jest dostępny w jednym z tych stanów:</p>

<ul>
 <li><em>pending</em>: stan inicjacji, ani wypełnione, ani odrzucone.</li>
 <li><em>fulfilled</em>: operacja zakończona sukcesem.</li>
 <li><em>rejected</em>: operacja zakończona porażką.</li>
</ul>

<p>Obowiązująca objetnica może być <em>zakończona </em>z wartością lub <em>odrzucona </em>z powodem(błędem). Kiedy dzieje się jedna z tych opcji, wywoływane są zakolejkowane, powiązane za pomocą metody <code>then</code> 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ą).</p>

<p>Tak jak w <code>{{jsxref("Promise.then", "Promise.prototype.then()")}}</code> oraz <code>{{jsxref("Promise.catch", "Promise.prototype.catch()")}}</code> gdy metoda zwróci obietnice, mogą one być łączone w łańcuchy.</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/8633/promises.png" style="height: 297px; width: 801px;"></p>

<div class="note">
<p><strong>Nie mylić z:</strong> 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ż  <a href="/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions">funkcje strzałkowe</a> bez argumentów: <code>f = () =&gt; <em>wyrażenie</em></code> by stworzyć leniwo oszacowane wyrażenie, i <code>f()</code> by ocenić.</p>
</div>

<div class="note">
<p>Mówi się, że obietnica zostanie uregulowana, jeśli zostanie spełniona lub odrzucona, ale nie oczekuje na rozpatrzenie. Usłyszysz także termin <em>rozwiązany </em>używany z obietnicami - oznacza to, że obietnica jest ustalona lub "zamknięta", aby dopasować się do stanu innej obietnicy. <a href="https://github.com/domenic/promises-unwrapping/blob/master/docs/states-and-fates.md">Stany i losy</a> zawierają więcej szczegółów na temat obiecanej terminologii.</p>
</div>

<h2 id="Właściwości">Właściwości</h2>

<dl>
 <dt><code>Promise.length</code></dt>
 <dd>Właściwość Length, której wartość wynosi zawsze 1 (liczba argumentów konstruktora).</dd>
 <dt>{{jsxref("Promise.prototype")}}</dt>
 <dd>Reprezentuje prototyp konstruktora <code>Promise</code>.</dd>
</dl>

<h2 id="Metody">Metody</h2>

<dl>
 <dt>{{jsxref("Promise.all", "Promise.all(iterable)")}}</dt>
 <dd>Zwraca obietnice, która albo kończy się sukcesem gdy wszystkie z obietnic w <code>iterable</code> 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 <code>iterable</code>. Jeżeli zwrócona obietnica zakończyła się porażką, jest ona odrzucana z Powodem z pierwszej obietnicy w <code>iterable</code>, która zakończyła się porażką. Ta metoda może być pomocna do zachowywania rezultatów różnych obietnic.</dd>
 <dt>{{jsxref("Promise.race", "Promise.race(iterable)")}}</dt>
 <dd>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.</dd>
</dl>

<dl>
 <dt>{{jsxref("Promise.reject", "Promise.reject(reason)")}}</dt>
 <dd>Returns a <code>Promise</code> object that is rejected with the given reason.</dd>
</dl>

<dl>
 <dt>{{jsxref("Promise.resolve", "Promise.resolve(value)")}}</dt>
 <dd>Returns a <code>Promise</code> object that is resolved with the given value. If the value is a thenable (i.e. has a <code>then</code> 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, {{jsxref("Promise.resolve", "Promise.resolve(value)")}} it instead and work with the return value as a promise.</dd>
</dl>

<h2 id="Promise_prototype">Promise prototype</h2>

<h3 id="Właściwości_2">Właściwości</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Properties')}}</p>

<h3 id="Metody_2">Metody</h3>

<p>{{page('en-US/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Methods')}}</p>

<h2 id="Tworzenie_Promise">Tworzenie Promise</h2>

<p>A <code>Promise</code> object is created using the <code>new </code>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 (<code>resolve</code>) is called when the asynchronous task completes successfully and returns the results of the task as a value. The second (<code>reject</code>) is called when the task fails, and returns the reason for failure, which is typically an error object.</p>

<pre class="brush: js notranslate">const myFirstPromise = new Promise((resolve, reject) =&gt; {
  // do something asynchronous which eventually calls either:
  //
  //   resolve(someValue); // fulfilled
  // or
  //   reject("failure reason"); // rejected
});
</pre>

<p>To provide a function with promise functionality, simply have it return a promise:</p>

<pre class="brush: js notranslate">function myAsyncFunction(url) {
  return new Promise((resolve, reject) =&gt; {
    const xhr = new XMLHttpRequest();
    xhr.open("GET", url);
    xhr.onload = () =&gt; resolve(xhr.responseText);
    xhr.onerror = () =&gt; reject(xhr.statusText);
    xhr.send();
  });
}</pre>

<h2 id="Przykłady">Przykłady</h2>

<h3 id="Podstawowy_przykład">Podstawowy przykład</h3>

<pre class="brush: js notranslate">let myFirstPromise = new Promise((resolve, reject) =&gt; {
  // 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) =&gt; {
  // 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);
});
</pre>

<h3 id="Zaawansowany_Przykład">Zaawansowany Przykład</h3>

<pre class="brush: html hidden notranslate">&lt;button id="btn"&gt;Make a promise!&lt;/button&gt;
&lt;div id="log"&gt;&lt;/div&gt;
</pre>

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

<p>The fulfillment of the promise is simply logged, via a fulfill callback set using {{jsxref("Promise.prototype.then()","p1.then()")}}. A few logs show how the synchronous part of the method is decoupled from the asynchronous completion of the promise.</p>

<pre class="brush: js notranslate">'use strict';
var promiseCount = 0;

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

    let log = document.getElementById('log');
    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Started (&lt;small&gt;Sync code started&lt;/small&gt;)&lt;br/&gt;');

    // 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) =&gt; {
            log.insertAdjacentHTML('beforeend', thisPromiseCount +
                ') Promise started (&lt;small&gt;Async code started&lt;/small&gt;)&lt;br/&gt;');
            // 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 (&lt;small&gt;Async code terminated&lt;/small&gt;)&lt;br/&gt;');
        })
    .catch(
        // Log the rejection reason
       (reason) =&gt; {
            console.log('Handle rejected promise ('+reason+') here.');
        });

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

<pre class="brush:js hidden notranslate">if ("Promise" in window) {
  let 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 &lt;code&gt;Promise&lt;code&gt; interface.";
}
</pre>

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

<p>{{EmbedLiveSample("Advanced_Example", "500", "200")}}</p>

<h2 id="Ładowanie_obrazka_z_XHR">Ładowanie obrazka z XHR</h2>

<p>Another simple example using <code>Promise</code> and <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> to load an image is available at the MDN GitHub<a href="https://github.com/mdn/js-examples/tree/master/promises-test"> js-examples</a> repository. You can also <a href="https://mdn.github.io/js-examples/promises-test/">see it in action</a>. Each step is commented and allows you to follow the Promise and XHR architecture closely.</p>

<h2 id="Specyfikacja">Specyfikacja</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('ES2015', '#sec-promise-objects', 'Promise')}}</td>
   <td>{{Spec2('ES2015')}}</td>
   <td>Initial definition in an ECMA standard.</td>
  </tr>
  <tr>
   <td>{{SpecName('ESDraft', '#sec-promise-objects', 'Promise')}}</td>
   <td>{{Spec2('ESDraft')}}</td>
   <td></td>
  </tr>
 </tbody>
</table>

<h2 id="Zgodność_z_przeglądarkami">Zgodność z przeglądarkami</h2>

<p class="hidden">To contribute to this compatibility data, please write a pull request against this repository: <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a>.</p>

<p>{{Compat("javascript.builtins.Promise")}}</p>

<h2 id="Zobacz_również">Zobacz również</h2>

<ul>
 <li><a href="/en-US/docs/Web/JavaScript/Guide/Using_promises">Using promises</a></li>
 <li><a href="http://promisesaplus.com/">Promises/A+ specification</a></li>
 <li><a href="https://medium.com/@ramsunvtech/promises-of-promise-part-1-53f769245a53">Venkatraman.R - JS Promise (Part 1, Basics)</a></li>
 <li><a href="https://medium.com/@ramsunvtech/js-promise-part-2-q-js-when-js-and-rsvp-js-af596232525c#.dzlqh6ski">Venkatraman.R - JS Promise (Part 2 - Using Q.js, When.js and RSVP.js)</a></li>
 <li><a href="https://tech.io/playgrounds/11107/tools-for-promises-unittesting/introduction">Venkatraman.R - Tools for Promises Unit Testing</a></li>
 <li><a href="http://www.html5rocks.com/en/tutorials/es6/promises/">Jake Archibald: JavaScript Promises: There and Back Again</a></li>
 <li><a href="http://de.slideshare.net/domenicdenicola/callbacks-promises-and-coroutines-oh-my-the-evolution-of-asynchronicity-in-javascript">Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Patterns in JavaScript</a></li>
 <li><a href="http://www.mattgreer.org/articles/promises-in-wicked-detail/">Matt Greer: JavaScript Promises ... In Wicked Detail</a></li>
 <li><a href="https://www.promisejs.org/">Forbes Lindesay: promisejs.org</a></li>
 <li><a href="https://github.com/jakearchibald/es6-promise/">Promise polyfill</a></li>
 <li><a href="https://www.udacity.com/course/javascript-promises--ud898">Udacity: JavaScript Promises</a></li>
</ul>