
El objeto Promise en javascript representa la finalización (o el fracaso) de una operación asincrónica y el resultado que devuelve. Esta página explica el constructor, las funciones Promise
y las propiedades de estos objetos. Para obtener más información sobre cómo funcionan las promesas y cómo puede usarlas, le recomendamos que lea primero la página » Uso de promesas «.
El constructor se utiliza principalmente para encapsular funciones que no admiten promesas. A continuación, se muestra un ejemplo del uso del Promise
constructor de objetos para crear una promesa simple:
var promise1 = new Promise(function(resolve, reject) { setTimeout(function() { resolve('foo'); }, 300); }); promise1.then(function(value) { console.log(value); // "foo" salida esperada }); console.log(promise1); // [object Promise] Resultado esperado</em>
Característica generales
Un objeto Promise javascript es un proxy de un valor que no se conoce exactamente cuando se crea la promesa, lo que nos permite vincular funciones para manejar eventos asincrónicos cuyo final es el éxito o el fracaso. Esto permite que las funciones asíncronas devuelvan valores al igual que las funciones síncronas. Pero en lugar de devolver el valor final directamente, las funciones asincrónicas devuelven una «promesa» de que el valor se proporcionará en algún momento en el futuro.
El objeto Promise se encuentra en uno de los siguientes casos:
- pendiente: el estado inicial, es decir, la promesa no se cumplió o se rechazó.
- cumplido: significa que el proceso se ha completado con éxito.
- rechazado: la operación falló.
- liquidado: esto es lo opuesto a pendiente, lo que significa que la promesa se ha liquidado en uno de dos estados: cumplida o rechazada.
Una promesa que está «en espera» puede «realizarse» y devuelve un valor, o «rechazada» con una razón (falsa). Cuando ocurre cualquiera de las situaciones anteriores, se llamará a una de las funciones de procesamiento utilizando la función secundaria then
del objeto Promise en javascript.
Si una promesa es verdadera o rechazada cuando la función de procesamiento está vinculada a ella, se llamará a la función de procesamiento, por lo que no se producirá ninguna «condición de carrera» entre la finalización de la operación asincrónica y las funciones de procesamiento vinculadas a la promesa.
Dado que tanto las funciones Promise.prototype.then()
como los retornos Promise.prototype.catch()
son promesas, se pueden usar en una cadena.
Nota: Algunos otros lenguajes de programación tienen mecanismos para retrasar la evaluación del valor de una expresión o retrasar una operación aritmética, que luego se denominan «promesas» (como Scheme). Las promesas en JavaScript representan procesos que realmente están teniendo lugar, que se pueden asociar con funciones de devolución de llamada. Si está buscando una forma de retrasar la evaluación del valor de una expresión, considere usar flechas sin argumentos f = () => expression
para retrasar la evaluación del valor de una expresión y utilicelas f()
para evaluar su valor.
Estructura Promise javascript
new Promise(executor /*function(resolve, reject) { ... } */);
executor
La función que se va a pasar al constructor tiene dos argumentos resolve
y reject
. La función executor
se ejecutará directamente desde el mecanismo de ejecución de promesas del navegador, y las funciones se pasarán a resolve
y reject
(la función se llamará executor
directamente antes de que el constructor devuelva Promise
un objeto).
Cuando se llama a la función resolve
o reject
, la promesa será aceptada (resuelta) o rechazada, respectivamente y en orden. La función executor
normalmente tendrá alguna operación asincrónica y, una vez finalizada, llamará a la función resolve
para aceptar la promesa o reject
si se produce un error.
Si se produce un error en la función executor
, la promesa se rechazará y el valor devuelto por la función se ignorará executor
.
Propiedades Promise
Promise.length
El valor de la propiedad length
es siempre 1, que es el número de argumentos de la función constructora.
Promise.prototype
Esta propiedad representa una cadena prototype
para la función constructora Promise
.
Principales funciones
Promise.all(iterable)
Devuelve una promesa que se puede cumplir cuando se cumplen todas las promesas del corredor iterable
, o se rechaza cuando una de las promesas del corredor se rechaza por primera vez iterable
.
Si las promesas son verdaderas en esta función, entonces esta función será verdadera, devolviendo una matriz en la que los valores de las promesas cumplidas están en el mismo orden en que están definidos en el argumento iterable
. Si se rechaza una promesa, esta función se rechazará junto con la razón para rechazar la primera promesa definida en el argumento iterable
. Esta función se puede utilizar para agrupar los resultados de varias promesas.
Promise.race(iterable)
Devuelve una promesa que se cumple o se rechaza cuando una de las promesas en ella es aceptada o rechazada iterable
, devolviendo el valor o la razón de esa promesa.
Promise.reject(reason)
Devuelve un objeto Promise
rechazado, especificando el motivo del rechazo.
Promise.resolve(value)
Devuelve un objeto Promise aceptado con el valor especificado en javascript. Si este valor está asociado con la función then
(), entonces (siga) la promesa devuelta seguirá a la función asociada con la función then
(), o la promesa devuelta será verdadera con el valor value
.
Si no sabe si el valor es una value
promesa, utilice la función Promise.resolve(value)
correspondiente y trate la devolución como una promesa.
Características Promise prototype
Promise.prototype.constructor
La función que crea una copia del objeto Promise
es el constructor.
Promise.prototype.catch(onRejected)
Agrega una devolución de llamada para manejar un caso de rechazo y devuelve una nueva promesa para resolver al valor de retorno de la devolución de llamada si se llama, o al valor de la promesa cumplida si la promesa se cumple en lugar de rechazarse.
Promise.prototype.then(onFulfilled, onRejected)
Agrega funciones para manejar el caso de cumplimiento y rechazo de una promesa, y devuelve una nueva promesa aceptada al valor de retorno de la función de procesamiento, o al valor original de la promesa si no se procesa (es decir, el argumento es onFulfilled
o onRejected
no es una función).
Promise.prototype.finally(onFinally)
Agrega una función de procesamiento a la promesa y devuelve una nueva promesa que se resolverá cuando se acepte la promesa original. La función de procesamiento será llamada onFinally
cuando la promesa haya terminado de ejecutarse, ya sea validada o rechazada.
Creando una Promise
Un objeto puede ser creado Promise
por su palabra clave new
y su constructor. Esta función constructora toma un argumento, que es una función llamada función ejecutora. Esta función debe tomar dos funciones como parámetros, la primera función (resolver) se llamará cuando la tarea asincrónica se haya completado con éxito y devolverá los resultados de la tarea como un valor, y la segunda función (rechazar) se llamará cuando la tarea falle, devolviendo la causa de la falla, generalmente el objeto de error.
const myFirstPromise = new Promise((resolve, reject) => { // realizar el proceso hasta que una función asincrónica llame: // Resolver (SomeValue); => Admisión // o // rechazar ("motivo de falla ") ; = > rechazar });
Para proporcionar una función con las posibilidades de promesas, haz que devuelva una promesa:
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(); }); }
Ejemplos y aplicaciones en código
Ejemplo simple
Llamaremos a la función resolve()
cuando la tarea asincrónica sea exitosa y a la función reject()
cuando falle la tarea asincrónica. En el siguiente ejemplo, usaremos la función setTimeout()
para simular un código asincrónico. De hecho, utilizará algo como Ajax (objeto XHR
) o API HTML5 .
Luego usaremos la función then()
para procesar el valor devuelto por la promesa, y el valor del parámetro será successMessage
igual a la cadena que le pasamos a la función resolve()
:
let myFirstPromise = new Promise((resolve, reject) => { setTimeout(function(){ resolve("Success!"); // todo salió bien }, 250); }); myFirstPromise.then((successMessage) => { console.log("Yay! " + successMessage); });
Ejemplo avanzado
Este pequeño ejemplo muestra cómo funciona el objeto Promise
. La función se llamará testPromise()
cada vez que se presione el elemento <button>
, una promesa que será validada y devuelve el número de promesas (contando desde 1) cada 1-3 segundos (aleatoriamente) usando la función setTimeout()
. El constructor se utiliza Promise()
para crear esa promesa.
Registraremos el cumplimiento de una promesa cada vez, utilizando el then()
. Habrá registros que muestran cómo el código síncrono en una función se puede combinar con la finalización de la promesa en código asincrónico:
'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/>'); // crearemos una nueva promesa let p1 = new Promise( // esta función es capaz de cumplir o rechazar la promesa // rechazar la promesa (resolve, reject) => { log.insertAdjacentHTML('beforeend', thisPromiseCount + ') Promise started (<small>Async code started</small>)<br/>'); // Este es un ejemplo simple de creación de una window.setTimeout( function() { // Cumplimos con la promesa resolve(thisPromiseCount); }, Math.random() * 2000 + 1000); } ); // then definiremos lo que sucederá cuando la promesa sea aceptada // catch sabremos qué sucederá cuando la promesa sea rechazada usando p1.then( // function(val) { log.insertAdjacentHTML('beforeend', val + ') Promise fulfilled (<small>Async code terminated</small>)<br/>'); }).catch( // registrando el motivo del rechazo (reason) => { console.log('Handle rejected promise ('+reason+') here.'); }); log.insertAdjacentHTML('beforeend', thisPromiseCount + ') Promise made (<small>Sync code terminated</small>)<br/>'); }
Soporte de navegadores
Característica | Chrome | Firefox | IE | Opera | Safari |
---|---|---|---|---|---|
Soporte básico | 32 | 29 | No soportado | 19 | 8 |
constructor ( Promise() ) | 32 | 29 * | No soportado | 19 | 8 ** |
all | 32 | 29 | No soportado | 19 | 8 |
prototype | 32 | 29 | No soportado | 19 | 8 |
catch | 32 | 29 | No soportado | 19 | 8 |
finally | 63 | 58 | No soportado | 50 | 11,1 |
then | 32 | 29 | No soportado | 19 | 8 |
race | 32 | 29 | No soportado | 19 | 8 |
reject | 32 | 29 | No soportado | 19 | 8 |
resolve | 32 | 29 | No soportado | 19 | 8 |
* El constructor ahora requiere que se use un operando a new
partir de la versión 37.
** El constructor ahora requiere que se usen operandos new
con él a partir de la versión 10.
- Expresión const en JavaScript
- Expresión let en JavaScript
- Expresión var en JavaScript
- Expresión try…catch en JavaScript
- Expresión throw en JavaScript
- Continue en JavaScript
- Switch en JavaScript
- Expresiones if…else en JavaScript
- Declaración vacía o empty en JavaScript
- Break en JavaScript
- Sentencia block en JavaScript
- Arguments en JavaScript
- Promise en JavaScript
- Number en JavaScript
- Características JSON en JavaScript
- Array en JavaScript
- RegExp en JavaScript
- String en JavaScript
- Date en JavaScript
- Math en JavaScript
- URIError en JavaScript
- TypeError en JavaScript
- SyntaxError en JavaScript
- ReferenceError en JavaScript
- RangeError en JavaScript
- EvalError en JavaScript
- Características Boolean en JavaScript
- Error en JavaScript
- Función Symbol en JavaScript
- Constructor Function en JavaScript
- Constructor Object en JavaScript
- Función unescape() en JavaScript
- Función eval() en JavaScript
- Valor null en JavaScript
- Características Undefined en JavaScript
- Características NaN en JavaScript
- Características Infinity en JavaScript
- Función parseFloat() en JavaScript
- Función isNaN() en JavaScript
- Función isFinite() en JavaScript
- Función escape() en JavaScript
- Función encodeURIComponent() en JavaScript