Apply your JS skills to key Mozilla projects as an MDN Fellow! http://mzl.la/MDNFellowship

mozilla
Vos résultats de recherche

    Promise

    Cette fonction, proposition pour ECMAScript 6 (Harmony), est expérimentale
    Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
    Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

    Résumé

    L'objet Promise (pour « promesse ») est utilisé pour réaliser des opérations de façon asynchrone. Une promesse est dans un de ces états :

    • en attente : état initial, la promesse n'est ni remplie, ni rompue
    • tenue : l'opération a réussi
    • rompue : l'opération a échoué
    • acquittée : la promesse est tenue ou rompue mais elle n'est plus en attente.

    Syntaxe

    new Promise(exécuteur);
    new Promise(function(resolve, reject) { ... });

    Paramètres

    exécuteur
    Un objet fonction qui prend deux arguments : resolve et reject. Le premier argument tient la promesse et le second la rompt. Cette fonction peut être appelée une fois que l'opération est terminée.

    Description

    L'interface Promise représente un intermédiaire (proxy) vers une valeur qui n'est pas nécessairement connue au moment de sa création. Cela permet de gérer des actions asynchrones et de leur associer des gestionnaires d'erreur. Ainsi, des méthodes asynchrones renvoient des valeurs comme les méthodes synchrones, la seule différence est que la valeur retournée par la méthode asynchrone est une promesse (d'avoir une valeur plus tard).

    Une promise peut être tenue avec une valeur ou refusée avec une raison. Quand on arrive à l'une des deux situations, les gestionnaires associés sont alors appelés. (Si la promesse a déjà été tenue ou refusée lorsque le gestionnaire est attaché à la promesse, le gestionnaire est appelé. Cela permet qu'il n'y ait pas de situation de compétition lorsqu'on attache les gestionnaires aux promesses correspondantes).

    Les méthodes Promise.prototype.then et Promise.prototype.catch renvoient des promesses et peuvent ainsi être chaînées. C'est ce qu'on appelle une composition.

    Propriétés

    Promise.length
    Une propriété de longueur qui vaut 1 (le nombre d'arguments pour le constructeur).
    Promise.prototype
    Cette propriété représente le prototype du constructeur Promise.

    Méthodes

    Promise.all(itérable)
    Renvoie une promesse qui est tenue lorsque toutes les promesses de l'argument itérables sont tenues.
    Promise.race(itérable)
    Renvoie une promesse qui est tenue ou rompue dès que l'une des promesses de l'itérable est tenue ou rompue avec la valeur ou la raison correspondante.
    Promise.reject(raison)
    Renvoie un objet Promise qui est rompu avec la raison donnée.
    Promise.resolve(valeur)
    Renvoie un objet Promise qui est tenue (résolue) avec la valeur donnée. Si la valeur possède une méthode then, la promesse renvoyée « suivra » cette méthode pour arriver dans son état, sinon la promesse renvoyée sera tenue avec la valeur fournie.

    Prototype de Promise

    Propriétés

    Promise.prototype.constructor
    Renvoie la fonction qui a créé le prototype d'une instance. Ce sera la fonction Promise par défaut.

    Méthodes

    Promise.prototype.catch(onRejected)
    Ajoute une fonction callback à utiliser en cas de rejet de la promesse. Elle renvoie une nouvelle promesse qui est résolue avec la valeur de retour du callback s'il est appelé ou avec la valeur de résolution initiale si la promesse est tenue (et non rejetée).
    Promise.prototype.then(onFulfilled, onRejected)
    Ajoute des fonctions à utiliser en cas de résolution ou de rejet de la promesse et renvoie une nouvelle promesse qui est résolue avec la valeur de retour de la fonction utilisée en fonction de la résolution ou non.

    Exemples

    Créer un objet Promise

    Dans le court exemple qui suit, on illustre le mécanisme d'une Promise. La méthode testPromise() est appelée chaque fois qu'on clique sur l'élément <button>. Cette méthode crée une promesse qui sera tenue grâce à la fonction window.setTimeout, et avec la valeur après 1s à 3s (aléatoire).

    Le fait que la promesse soit tenue est enregistré via un callback sur p1.then. Quelques indicateurs illustrent lamanière dont la partie synchrone est découplée de la partie asynchrone.

    var comptePromesse = 0;
    function testPromise() {
      var thisComptePromesse = ++comptePromesse;
    
      var log = document.getElementById('log');
      log.insertAdjacentHTML('beforeend', thisComptePromesse + 
          ') Started (<small>Début du code synchrone</small>)<br/>');
    
      // on crée une nouvelle promesse :
      var p1 = new Promise(
        // La fonction de résolution est appelée avec la capacité de 
        // tenir ou de rompre la promesse
        function(resolve, reject) {       
          log.insertAdjacentHTML('beforeend', thisComptePromesse + 
              ') Promise started (<small>Début du code asynchrone</small>)<br/>');
    
          // Voici un exemple simple pour créer un code asynchrone
          window.setTimeout(
            function() {
              // On tient la promesse !
              resolve(thisCcomptePromesse)
            }, Math.random() * 2000 + 1000);
        });
    
      // On définit ce qui se passe quand la promesse est tenue
      p1.then(
        // On affiche un message avec la valeur
        function(val) {
          log.insertAdjacentHTML('beforeend', val +
              ') Promise fulfilled (<small>Fin du code asynchrone</small>)<br/>');
        });
    
      log.insertAdjacentHTML('beforeend', thisComptePromesse + 
          ') Promise made (<small>Fin du code synchrone</small>)<br/>');
    }
    

    Cet exemple s'exécute lorsqu'on clique sur le bouton. Pour tester cet exemple, il est nécessaire d'utiliser un navigateur qui supporte les objets Promise. En cliquant plusieurs fois sur le bouton en peu de temps, on verra qu'il y a plusieurs promesses tenues les une après les autres.

    Utiliser XMLHttpRequest() avec une promesse

    Dans l'exemple qui suit, on illustre comment utiliser une promesse pour fournir le résultat d'une requête :

    // A-> $http on implémente la fonction pour suivre le patron de conception
    // Adaptateur (Adapter)
    var $http = function(url){
     
      // Un exemple d'objet simple
      var core = {
        
        // La méthode qui effectue la requête AJAX
        ajax : function(method, url, args){
          
              // On établit une promesse pour le résultat
              return new Promise(function(resolve, reject) {
                
                // Instantiates the XMLHttpRequest
                var client = new XMLHttpRequest();
                var uri = '';
                if((args != undefined) && (method == 'POST' || method == 'PUT')) {
                  for (key in args) {
                    uri += encodeURIComponent(key) + '=' + encodeURIComponent(escape(args[key])) + '&';
                  }
                  client.open(method, (method == 'POST' || method == 'PUT')?url: url + '?' + uri, true);
                } else {
                  client.open(method, url, true);
                }
                client.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
                client.setRequestHeader("Cache-Control", "no-cache");
                client.onreadystatechange = function(){
                  if(this.readyState == 4){
                    if(this.status == 200){
                      // On résout la fonction si this.status est 200
                      resolve(JSON.parse(this.response));
                    } else{
                      // Sinon, on a un cas d'erreur pour lequel on rompt
                      // la promesse
                      reject({"error":this.statusText});
                    }
                  }
                };
                client.send(uri);
                
              });
            }
      };
    
      // On finit l'adaptateur
      return {
        'get' : function(args) {
          return core.ajax('GET', url, args);
        },
        'post' : function(args) {
          return core.ajax('POST', url, args);
        },
        'put' : function(args) {
          return core.ajax('PUT', url, args);
        },
        'delete' : function(args) {
          return core.ajax('DELETE', url, args);
        }
      };
    };
    // Fin de A
    
    // B-> Ici on définit les fonctions et la charge utilisée
    var youtubeUri = 'https://developer.mozilla.org/en-US/search.json';
    var payload = {
      'topic' : 'js',
      'q' : 'Promise'
    };
    var callback = {
      success : function(data){
         console.log(1, 'success', data);
      },
      error : function(data){
         console.log(2, 'error', data);
      }
    };
    // Fin de B
    
    // On exécute la méthode
    $http(youtubeUri).get(payload).then(callback.success, callback.error);

    Charger une image en XHR

    Un autre exemple simple utilisant Promise et XMLHttpRequest afin de charger une image est disponible sur le dépôt GitHub MDN promise-test. Vous pouvez également consulter le résultat obtenu sur cette page. Chaque étape est commentée afin de vous permettre de suivre l'état de la promesse et l'architecture utilisée avec XHR.

    Spécifications

    Spécification Statut Commentaires
    domenic/promises-unwrapping Draft Le travail de standardisation est réalisé à cet endroit.
    ECMAScript 6 (ECMA-262)
    La définition de 'Promise' dans cette spécification.
    En cours de validation comme recommandation Définition initiale au sein d'un standard ECMA.

    Compatibilité des navigateurs

    Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Support simple 32 24.0 (24.0) en tant que Future
    25.0 (25.0) en tant que Promise derrière une préférence [1]
    29.0 (29.0) par défaut
    11 19 7.1
    Fonctionnalité Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile Chrome pour Android
    Support simple Pas de support 24.0 (24.0) en tant que Future
    25.0 (25.0) en tant que Promise derrière une préférence [1]
    29.0 (29.0) par défaut
    Pas de support Pas de support iOS 8 32

    [1] Gecko 24 possédait une implémentation expérimentale de l'objet Promise, sous le nom Future. Le nom actuel fut utilisé dans Gecko 25, mais désactivé par défaut avec la préférence dom.promise.enabled. Le bug bug 918806 a permis d'activer les promesses par défaut avec Gecko 29.

    Voir aussi

    Étiquettes et contributeurs liés au document

    Contributors to this page: riplay777, Goofy, nicodel, teoli, SphinxKnight
    Dernière mise à jour par : SphinxKnight,