Non standard
Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.
La propriété non-standard stack des objets Error fournit le déroulé des fonctions qui ont été appelées, dans l'ordre, depuis quel ligne de quel fichier, et avec quels arguments. Cette chaine de caractères représente la pile d'appels, commençant avec les appels les plus récents, et remontant jusqu'à l'appel original de la portée globale.
Description
Chaque étape sera séparée par une nouvelle ligne. La première partie de la ligne est le nom de la fonction (si l'appel n'est pas effectué depuis la portée globale), suivi du signe @, la position du fichier (sauf si la fonction est le constructeur d'erreur lorsque l'erreur est levée), un double point, et, s'il y a une position de fichier, un numéro de ligne. (On notera que l'objet Error possède aussi les propriétés fileName, lineNumber et columnNumber afin de récupérer ces informations à partir de l'erreur déclenchée).
Le format décrit ici est le format utilisé par Firefox. Il n'y a aucun formatage standard. Cependant Safari 6+ et Opera 12- utilisent un format très proche. Les navigateurs utilisant le moteur de JavaScript V8 (tel que Chrome, Opera 15+, Navigateur Android) et IE10+, utilisent un format différent (voir la documentation MSDN error.stack).
Valeurs des arguments dans la pile : Avant Firefox 14 (bug 744842), les noms de fonction étaient suivis par les valeurs des arguments converties en une chaine de caractères dans des parenthèses, avant le signe @. Bien qu'un objet (ou un tableau, etc.) apparaissait sous une forme "[object Object]", et ne pouvait pas être réévalué en de vrai objets, des valeurs scalaires pouvaient être récupérées (Bien qu'il soit plus facile — et cela est encore possible dans Firefox 14 — d'utiliser arguments.callee.caller.arguments, tout comme le nom de la fonction peut être récupéré avec arguments.callee.caller.name). "undefined" est listé comme "(void 0)". Si des chaines de caractères étaient passées en arguments avec des valeurs comme "@", "(", ")" (ou dans le nom des fichiers), on ne pouvait pas découper la ligne en composants de façon simple. De fait, dans Firefox 14 (et les versions plus récentes), ceci est moins un problème.
Les différents navigateurs fixent cette valeur à différents moments. Par exemple, Firefox la définit lorsqu'il crée l'objet Error. PhantomJS, en revanche, ne la définit qu'au moment où il lève l'exception. La documentation présente sur MSDN indique le même comportemant que PhantomJS.
Exemple
Le code HTML suivant démontre l'utilisation de la propriété stack.
<!DOCTYPE HTML>
<meta charset="UTF-8">
<title>Exemple Stack Trace</title>
<body>
<script>
function trace() {
try {
throw new Error("myError");
}
catch(e) {
alert(e.stack);
}
}
function b() {
trace();
}
function a() {
b(3, 4, "\n\n", undefined, {});
}
a("first call, firstarg");
</script>
Si, par exemple, ce code a été enregistré sous C:\exemple.html sur un système de fichier Windows, il renverra un message d'erreur dans une nouvelle fenêtre avec un certain texte.
À partir de Firefox 30, ce message contiendra le numéro de colonne (position du caractère sur un ligne du fichier) (bug 762556) :
trace@file:///C:/exemple.html:9:17 b@file:///C:/exemple.html:16:13 a@file:///C:/exemple.html:19:13 @file:///C:/exemple.html:21:9
Pour les versions de Firefox comprises entre les versions 14 et 29 :
trace@file:///C:/exemple.html:9 b@file:///C:/exemple.html:16 a@file:///C:/exemple.html:19 @file:///C:/exemple.html:21
Firefox 13 et ses versions antérieures auraient produit le texte suivant :
Error("myError")@:0
trace()@file:///C:/exemple.html:9
b(3,4,"\n\n",(void 0),[object Object])@file:///C:/exemple.html:16
a("first call, firstarg")@file:///C:/exemple.html:19
@file:///C:/exemple.html:21
Pile pour du code évalué
À partir de Firefox 30 (Firefox 30 / Thunderbird 30 / SeaMonkey 2.27 / Firefox OS 1.4), la pile d'erreurs pour du code appelant les fonctions Function() et eval()produit désormais des informations plus détaillées sur les numéros de lignes et de colonnes provenant de ces appels. Les appels de Function sont indiqués avec "> Function" et les appels d'eval avec "> eval". Voir bug 332176 pour plus d'informations.
try {
new Function('throw new Error()')();
} catch (e) {
console.log(e.stack);
}
// anonymous@file:///C:/exemple.html line 7 > Function:1:1
// @file:///C:/exemple.html:7:6
try {
eval("eval('ÉCHEC')");
} catch (x) {
console.log(x.stack);
}
// @file:///C:/exemple.html line 7 > eval line 1 > eval:1:1
// @file:///C:/exemple.html line 7 > eval:1:1
// @file:///C:/exemple.html:7:6
Il est aussi possible d'utiliser la directive //# sourceURL pour nommer une source d'évaluation. Sur ce sujet, voir la page sur le débogueur ainsi que ce billet (en anglais).
Spécifications
Cette propriété ne fait partie d'aucune spécification. Elle est considérée comme non-standard.
Compatibilité des navigateurs
| Fonctionnalité | Chrome | Firefox (Gecko) | Edge | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|---|
| Support simple | (Oui) | (Oui) | (Oui) | 10 | (Oui) | 6 |
| Fonctionnalité | Android | Chrome pour Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Support simple | 4.0 | ? | ? | ? | ? | 6 |
Voir aussi
- Components.stack
- Projets externes : TraceKit et javascript-stacktrace
- Documentation MSDN sur error.stack
- Aperçu de l'API sur les piles d'appels avec V8 (en anglais)