diff options
Diffstat (limited to 'files/pt-br/web/javascript/reference/global_objects/promise/index.html')
| -rw-r--r-- | files/pt-br/web/javascript/reference/global_objects/promise/index.html | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/files/pt-br/web/javascript/reference/global_objects/promise/index.html b/files/pt-br/web/javascript/reference/global_objects/promise/index.html new file mode 100644 index 0000000000..d3d0e76322 --- /dev/null +++ b/files/pt-br/web/javascript/reference/global_objects/promise/index.html @@ -0,0 +1,174 @@ +--- +title: Promise +slug: Web/JavaScript/Reference/Global_Objects/Promise +tags: + - ECMAScript6 + - JavaScript + - Promise +translation_of: Web/JavaScript/Reference/Global_Objects/Promise +--- +<div>{{JSRef("Global_Objects", "Promise")}}</div> + +<p><strong><code>Promise</code></strong> é um objeto usado para processamento assíncrono. Um <code>Promise</code> (<em>de "promessa"</em>) representa um valor que pode estar disponível agora, no futuro ou nunca.</p> + +<div class="note"> +<p><strong>Nota:</strong> Esse artigo descreve o construtor <code>Promise,</code>os métodos e propriedades de tais objetos. Para aprender sobre como promises funcionam e como utilizá-los, é aconselhavel a leitura de <a href="/pt-BR/docs/Web/JavaScript/Guide/Usando_promises">utilizando promises</a>. O construtor é utilizado para embrulhar funções sem suporte ao conceito "promise".</p> +</div> + +<h2 id="Descrição">Descrição</h2> + +<p>Uma <code><strong>Promise</strong></code> representa um proxy para um valor que não é necessariamente conhecido quando a promessa é criada. Isso permite a associação de métodos de tratamento para eventos da ação assíncrona num caso eventual de sucesso ou de falha. Isto permite que métodos assíncronos retornem valores como métodos síncronos: ao invés do valor final, o método assíncrono retorna uma <em>promessa</em> ao valor em algum momento no futuro.</p> + +<p>Um <strong><code>Promise</code></strong> está em um destes estados: </p> + +<ul> + <li><em>pending (</em>pendente<em>)</em>: Estado inicial, que não foi realizada nem rejeitada.</li> + <li><em>fulfilled (</em>realizada): sucesso na operação.</li> + <li><em>rejected (</em>rejeitado): falha na operação.</li> +</ul> + +<p>Uma promessa pendente pode se tornar <em>realizada</em> com um valor ou <em>rejeitada</em> por um motivo (erro). Quando um desses estados ocorre, o método <code>then</code> do <code>Promise</code> é chamado, e ele chama o método de tratamento associado ao estado (<code>rejected</code> ou <code>resolved</code>). Se a promessa foi realizada ou rejeitada quando o método de tratamento correspondente for associado, o método será chamado, deste forma não há uma condição de competição entre uma operação assíncrona e seus manipuladores que estão sendo associados.</p> + +<p>Como os métodos <code>Promise.prototype.then</code> e <code>Promise.prototype.catch</code> retornam promises, eles podem ser encadeados — uma operação chamada <em>composição</em>.</p> + +<p><img alt="" src="https://mdn.mozillademos.org/files/8633/promises.png" style="height: 297px; width: 801px;"></p> + +<h2 id="Propriedades">Propriedades</h2> + +<dl> + <dt><code>Promise.length</code></dt> + <dd>Propriedade length cujo valor é sempre 1 (número de argumentos do método construtor).</dd> + <dt>{{jsxref("Promise.prototype")}}</dt> + <dd>Representa o protótipo para o método construtor da <code>Promise</code>.</dd> +</dl> + +<h2 id="Métodos">Métodos</h2> + +<dl> + <dt>{{jsxref("Promise.all", "Promise.all(lista)")}}</dt> + <dd>Retorna uma promise que é resolvida quando todas as promises no argumento <em>lista</em> forem resolvidas ou rejeitada assim que uma das promises da lista for rejeitada. Se a promise retornada for resolvida, ela é resolvida com um array dos valores das promises resolvidas da lista. Se a promise for rejeitada, ela é rejeitada com o motivo da primeira promise que foi rejeitada na lista. Este método pode ser útil para agregar resultados de múltiplas promises.</dd> + <dt>{{jsxref("Promise.race", "Promise.race(lista)")}}</dt> + <dd>Retorna uma promise que resolve ou rejeita assim que uma das promises do argumento lista resolve ou rejeita, com um valor ou o motivo daquela promise.</dd> +</dl> + +<dl> + <dt>{{jsxref("Promise.reject", "Promise.reject(motivo)")}}</dt> + <dd>Retorna um objeto <code>Promise</code> que foi rejeitado por um dado motivo.</dd> +</dl> + +<dl> + <dt>{{jsxref("Promise.resolve", "Promise.resolve(valor)")}}</dt> + <dd>Retorna um objeto <code>Promise</code> que foi resolvido com um dado valor. Se o valor é <code>thenable</code> (possui um método <code>then</code>), a promise retornada "seguirá" este método, adotando esse estado eventual; caso contrário a promise retornada será realizada com o valor. Geralmente, se você quer saber se um valor é uma promise ou não, utilize {{jsxref("Promise.resolve", "Promise.resolve(valor)")}} e trabalhe com a valor de retorno que é sempre uma promise.</dd> +</dl> + +<h2 id="Protótipo_Promise">Protótipo Promise</h2> + +<h3 id="Propriedades_2">Propriedades</h3> + +<p>{{page('pt-BR/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Propriedades')}}</p> + +<h3 id="Métodos_2">Métodos</h3> + +<p>{{page('pt-BR/Web/JavaScript/Reference/Global_Objects/Promise/prototype','Métodos')}}</p> + +<h2 id="Exemplos">Exemplos</h2> + +<h3 id="Criando_uma_Promise">Criando uma Promise</h3> + +<pre class="brush: html notranslate" style="display: none;"><button id="btn">Make a promise!</button> +<div id="log"></div> +</pre> + +<p>Este pequeno exemplo mostra o mecanismo de uma <code>Promise</code>. O método <code>testPromise()</code> é chamado cada vez que {{HTMLElement("button")}} é clicado. Isso cria uma promise que resolverá, usando {{domxref("window.setTimeout()")}}, o contador de promise <code>promiseCount</code> (iniciando em 1) a cada 1 a 3s randomicamente. O construtor <code>Promise()</code> é usado para criar a promise.</p> + +<p>A realização da promise é simplesmente registrada, por meio de configuração na função callback de realização usando {{jsxref("Promise.prototype.then()","p1.then()")}}. Alguns logs mostram como a parte síncrona do método é desacoplada da conclusão assíncrona da promise.</p> + +<pre class="brush: js notranslate">var promiseCount = 0; +function testPromise() { + var thisPromiseCount = ++promiseCount; + + var log = document.getElementById('log'); + log.insertAdjacentHTML('beforeend', thisPromiseCount + + ') Started (<small>Sync code started</small>)<br/>'); + + // Criamos uma nova promise: prometemos a contagem dessa promise (após aguardar 3s) + var p1 = new Promise( + // a função resolve() é chamada com a capacidade para resolver ou + // rejeitar a promise + function(resolve, reject) { + log.insertAdjacentHTML('beforeend', thisPromiseCount + + ') Promise started (<small>Async code started</small>)<br/>'); + // Isto é apenas um exemplo para criar assincronismo + window.setTimeout( + function() { + // Cumprimos a promessa ! + resolve(thisPromiseCount) + }, Math.random() * 2000 + 1000); + }); + + // definimos o que fazer quando a promise for realizada + p1.then( + // apenas logamos a mensagem e o valor + function(val) { + log.insertAdjacentHTML('beforeend', val + + ') Promise fulfilled (<small>Async code terminated</small>)<br/>'); + }); + + log.insertAdjacentHTML('beforeend', thisPromiseCount + + ') Promise made (<small>Sync code terminated</small>)<br/>'); +} +</pre> + +<pre class="brush:js notranslate" style="display: none;">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."; +} +</pre> + +<p>Este exemplo é executado pelo click do botão. Você precisa de uma versão de navegedor com suporte a <code>Promise</code>. Clicando algumas vezes no botão num curto intervalo de tempo, você verá as diferentes promises sendo realizadas uma após a outra.</p> + +<p>{{EmbedLiveSample("Criando_uma_Promise", "500", "200")}}</p> + +<h3 id="Carregando_uma_imagem_com_XHR">Carregando uma imagem com XHR</h3> + +<p>Outro simples exemplo usando <code>Promise</code> e <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHTTPRequest</a></code> para carregar imagens está disponível no repositório GitHub MDN<a href="https://github.com/mdn/js-examples/blob/master/promises-test/index.html"> promise-test</a>. Você também pode <a href="https://mdn.github.io/js-examples/promises-test/">vê-lo em ação</a>. Cada passo é comentado e lhe permite acompanhar de perto a arquitetura de Promise e XHR.</p> + +<h2 id="Especificações">Especificações</h2> + +<table class="standard-table"> + <tbody> + <tr> + <th scope="col">Especificação</th> + <th scope="col">Status</th> + <th scope="col">Comentário</th> + </tr> + <tr> + <td><a href="https://github.com/domenic/promises-unwrapping">domenic/promises-unwrapping</a></td> + <td>Draft</td> + <td>Standardization work is taking place here.</td> + </tr> + <tr> + <td>{{SpecName('ES2015', '#sec-promise-objects', 'Promise')}}</td> + <td>{{Spec2('ES2015')}}</td> + <td>Initial definition in an ECMA standard.</td> + </tr> + </tbody> +</table> + +<h2 id="Compatibilidade_de_Navegador">Compatibilidade de Navegador</h2> + +<p>{{Compat("javascript.builtins.Promise")}}</p> + +<p>Veja também</p> + +<ul> + <li><a href="http://promisesaplus.com/">Promises/A+ specification</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 Patter 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> +</ul> |