path: root/files/pt-br/web/javascript/reference/global_objects/promise/index.html

---
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>

&lt;div id="log"&gt;&lt;/div&gt;
</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 (&lt;small&gt;Sync code started&lt;/small&gt;)&lt;br/&gt;');

  // 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 (&lt;small&gt;Async code started&lt;/small&gt;)&lt;br/&gt;');
      // 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 (&lt;small&gt;Async code terminated&lt;/small&gt;)&lt;br/&gt;');
    });

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

<pre class="brush:js notranslate" class="hidden">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="Browser_compatibility">Compatibilidade com navegadores</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>