1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
---
title: Promise.prototype.catch()
slug: Web/JavaScript/Reference/Global_Objects/Promise/catch
tags:
- ECMAScript 2015
- JavaScript
- Méthode
- Promise
- Prototype
- Reference
translation_of: Web/JavaScript/Reference/Global_Objects/Promise/catch
original_slug: Web/JavaScript/Reference/Objets_globaux/Promise/catch
---
{{JSRef}}
La méthode **`catch()`** renvoie un objet {{jsxref("Promise")}} et ne traite que des cas où la promesse initiale est rejetée. Elle a le même effet qu'un appel à {{jsxref("Promise.then", "Promise.prototype.then(undefined, siRejetée)")}} (c'est en fait ce qui se passe dans le moteur, `obj.catch(onRejected)` est traduit en `obj.then(undefined, onRejected)`). Cela signifie qu'il est nécessaire de fournir une fonction `onRejected`, même si on souhaite avoir une valeur de secours qui est `undefined` (par exemple avec `obj.catch(() => {})`.
{{EmbedInteractiveExample("pages/js/promise-catch.html")}}
## Syntaxe
p.catch(siRejetée);
p.catch(function(raison) {
// rejet
});
### Paramètres
- `siRejetée`
- : Une {{jsxref("Function","fonction","",1)}} à appeler si la `Promise` est rejetée (i.e. n'est pas tenue). Cette fonction possède un argument :
- `raison`
- : Une chaîne de caractères qui indique pourquoi la promesse n'est pas tenue.
La promesse renvoyée par la méthode `catch()` est rompue si `siRejetée` lève une erreur ou si elle renvoie une promesse rompue. Dans les autres cas, elle est tenue.
### Valeur de retour
Une promesse ({{jsxref("Promise")}}).
## Description
La méthode `catch()` est utile pour gérer les cas d'erreur en cas de compositions de plusieurs promesses. Elle renvoie elle-même une promesse et peut donc être utilisée lorsqu'on [chaîne des promesses](/fr/docs/Web/JavaScript/Guide/Utiliser_les_promesses#Chaînage_après_un_catch), à l'instar de la méthode sœur qu'est {{jsxref("Promise.prototype.then()")}}.
## Exemples
### Utilisation de la méthode `catch`
```js
var p1 = new Promise(function(resolve, reject) {
resolve("Succès");
});
p1.then(function(value) {
console.log(value); // "Succès!"
throw new Error("zut !");
}).catch(function(e) {
console.error(e.message); // "zut !"
}).then(function(e) {
console.log('après le catch, la chaîne est restaurée');
});
// Le code qui suit est équivalent :
p1.then(function(value) {
console.log(value); // "Succès!"
return Promise.reject('zut !');
}).catch(function(e) {
console.log(e); // "zut !"
}).then(function(e){
console.log('après le catch, la chaîne est restaurée');
});
```
### Les promesses n'interceptent pas les exceptions levées de façon asynchrone
```js
var p1 = new Promise(function(resolve, reject) {
throw new Error('Oh oh!');
});
p1.catch(function(e) {
console.log(e.message); // "Oh oh!"
});
var p2 = new Promise(function(resolve, reject) {
setTimeout(function() {
throw new Error('Exception invisible !');
}, 1000);
});
p2.catch(function(e) {
console.log(e.message); // Cela n'est jamais appelé
});
```
### Démonstration de l'appel interne à `then`
```js
// On surcharge Promise.prototype.then/catch
// pour y ajouter des logs
(function(Promise){
var originalThen = Promise.prototype.then;
var originalCatch = Promise.prototype.catch;
Promise.prototype.then = function(){
console.log('> > > > > > appel de .then sur %o avec les arguments: %o', this, arguments);
return originalThen.apply(this, arguments);
};
Promise.prototype.catch = function(){
console.log('> > > > > > appel de .catch sur %o avec les arguments: %o', this, arguments);
return originalCatch.apply(this, arguments);
};
})(this.Promise);
// On appelle catch sur une promesse déjà résolue
Promise.resolve().catch(function XXX(){});
// Dans la console, on aura :
// > > > > > > appel de .catch sur Promise{} avec les arguments: Arguments{1} [0: function XXX()]
// > > > > > > appel de .then sur Promise{} avec les arguments: Arguments{2} [0: undefined, 1: function XXX()]
```
## Spécifications
| Spécification | État | Commentaires |
| ------------------------------------------------------------------------------------------------------------ | ---------------------------- | ----------------------------------------------- |
| {{SpecName('ES2015', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}} | {{Spec2('ES2015')}} | Définition initiale au sein d'un standard ECMA. |
| {{SpecName('ESDraft', '#sec-promise.prototype.catch', 'Promise.prototype.catch')}} | {{Spec2('ESDraft')}} | |
## Compatibilité des navigateurs
{{Compat("javascript.builtins.Promise.catch")}}
## Voir aussi
- {{jsxref("Promise")}}
- {{jsxref("Promise.prototype.then()")}}
|
