diff options
Diffstat (limited to 'files/pl/web/javascript/reference/global_objects/promise/index.html')
| -rw-r--r-- | files/pl/web/javascript/reference/global_objects/promise/index.html | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/files/pl/web/javascript/reference/global_objects/promise/index.html b/files/pl/web/javascript/reference/global_objects/promise/index.html new file mode 100644 index 0000000000..3da2498ca1 --- /dev/null +++ b/files/pl/web/javascript/reference/global_objects/promise/index.html @@ -0,0 +1,256 @@ +--- +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 = () => <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) => { + // 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) => { + const xhr = new XMLHttpRequest(); + xhr.open("GET", url); + xhr.onload = () => resolve(xhr.responseText); + xhr.onerror = () => 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) => { + // 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); +}); +</pre> + +<h3 id="Zaawansowany_Przykład">Zaawansowany Przykład</h3> + +<pre class="brush: html hidden notranslate"><button id="btn">Make a promise!</button> +<div id="log"></div> +</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 (<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/>'); +}</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 <code>Promise<code> 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> |