Un symbole est un type de données unique et inchangeable qui peut être utilisé pour représenter des identifiants pour des propriétés d'un objet. L'objet Symbol est un conteneur objet implicite pour le type de données primitif symbole.

Syntaxe

Symbol([description])

Paramètres

description Facultatif
Une chaîne de caractères optionnelle. Correspond à une description du symbole, elle peut être utile pour déboguer (mais pas pour accéder au symbole).

Description

Pour créer un nouveau symbole, il suffit d'appeler Symbol(), éventuellement avec une chaîne de caractère descriptive :

var sym1 = Symbol();
var sym2 = Symbol("toto");
var sym3 = Symbol("toto");

Le fragment de code ci-dessus permet de créer trois nouveaux symboles. On notera que l'instruction Symbol("toto") ne convertit pas la chaîne "toto" en un symbole. On crée bien un nouveau symbole pour chaque instruction ci-avant.

Symbol("toto") === Symbol("toto"); // false

La syntaxe suivante, utilisant l'opérateur new, entraînera une exception TypeError:

var sym = new Symbol(); // TypeError

Cela est fait pour empêcher d'écrire un conteneur (wrapper) explicite de Symbol plutôt qu'une nouvelle valeur, cela peut être surprenant car généralement, on peut créer des objets « autour » de types primitifs (par exemple avec new Boolean, new String et new Number).

Si on souhaite obtenir un object contenant un symbole, on pourra toujours utiliser la fonction Object() :

var sym = Symbol("toto");
typeof sym;     // "symbol"
var symObj = Object(sym);
typeof symObj;  // "object"

Symboles partagés et registre global des symboles

La syntaxe manipulée ci-avant, utilisant la fonction Symbol(), ne crée pas un symbole global, disponible partout dans votre code. Pour créer des symboles qui soient disponibles pour différents fichiers et appartiennent à l'environnement global, il faut utiliser les méthodes Symbol.for() et Symbol.keyFor() afin de définir et de récupérer les symboles listés dans le registre global.

Trouver les propriétés identifiées par des symboles pour un objet

La méthode Object.getOwnPropertySymbols() renvoie un tableau de symboles, permettant ainsi de connaître les propriétés identifiées par un symbole pour un objet donné. À l'initialisation, un objet ne contient aucune propriété propre identifiée par un symbole, ce tableau sera donc vide jusqu'à ce qu'une propriété, identifiée par un symbole, lui soit ajoutée.

Les symboles et les conversions

Lorsqu'on utilise des mécanismes de conversion de types avec les symboles, on aura le comportement suivant :

  • Lorsqu'on tente de convertir un symbole en un nombre, cela provoquera une exception TypeError (par exemple avec +sym ou sym | 0).
  • L'égalité faible permet d'obtenir true avec Object(sym) == sym.
  • Symbol("toto") + "truc" lève une exception TypeError (le symbole ne peut pas être converti en une chaîne de caractères), cela permet par exemple d'éviter de créer (sans s'en rendre compte) des noms de propriétés basés sur des symboles.
  • La méthode utilisant la conversion avec String() fonctionnera comme un appel à Symbol.prototype.toString(). En revanche, new String(sym) renverra une erreur.

Propriétés

Symbol.length
La propriété length dont la valeur est 0.
Symbol.prototype
Cette propriété représente le prototype du constructeur Symbol.

Symboles connus

En plus des symboles que vous pouvez créer, JavaScript possède certains symboles natifs représentant des aspects internes du langages qui, pour ECMAScript 5 et les versions précédentes, n'étaient pas exposées aux développeurs. Il est possible d'accéder à ces symboles en utilisant les propriétés suivantes :

Symboles d'itération

Symbol.iterator
Une méthode qui renvoie l'itérateur par défaut d'un objet. Ce symbole est utilisé par la boucle for...of.
Symbol.asyncIterator
Une méthode qui renvoie l'itérateur asynchrone par défaut d'un objet. Ce symbole est utilisé par la boucle for await of.

Symboles liés aux expressions rationnelles

Symbol.match
Une méthode qui fait correspondre une expression rationnelle avec une chaîne de caractères. Elle est aussi utilisée pour déterminer si un objet peut être utilisé comme une expression rationnelle.
Symbol.replace
Une méthode qui remplace les sous-chaînes correspondantes dans une chaîne de caractères. Utilisée par String.prototype.replace().
Symbol.search
Une méthode qui renvoie l'indice d'une chaîne de caractères pour lequel on a une correspondance avec une expression rationnelle. Utilisée par String.prototype.search().
Symbol.split
Une méthode qui découpe la chaîne à l'indice donné par la correspondance avec une expression rationnelle. Utilisée par String.prototype.split().

Autres symboles

Symbol.hasInstance
Une méthode qui permet de déterminer si un constructeur reconnaît un objet comme son instance. Utilisé par instanceof.
Symbol.isConcatSpreadable
Une valeur booléenne qui indique si un objet devrait être réduit à la concaténation des éléments de son tableau via  Array.prototype.concat().
Symbol.unscopables
Un objet dont les noms des propriétés propres et héritées sont exclues de l'objet associé lors de l'utilisation de with.
Symbol.species
Un constructeur utilisé pour construire des objets dérivés.
Symbol.toPrimitive
Spécifié comme @@toPrimitive. Une méthode qui convertit un objet en sa valeur primitive.
Symbol.toStringTag
Spécifié comme @@toStringTag. Une chaîne de caractères utilisée pour la description d'un objet. Ce symbole est utilisé par Object.prototype.toString().

Méthodes

Symbol.for(key)
Recherche parmi les symboles existants un symbole désigné par cette clé. S'il est trouvé, le symbole est renvoyé, sinon un nouveau symbole est créé et enregistré avec cette clé dans le registre global des symboles.
Symbol.keyFor(sym)
Pour un symbole donné, récupère la clé d'un symbole partagé depuis le registre global.

Prototype Symbol

Tous les symboles héritent de Symbol.prototype.

Propriétés

Méthodes

Exemples

Utiliser l'opérateur typeof avec des symboles

L'opérateur typeof permet d'identifier des symboles :

typeof Symbol() === 'symbol'
typeof Symbol('toto') === 'symbol'
typeof Symbol.iterator === 'symbol'

Les symboles et les boucles for...in

Les symboles ne peuvent pas être énumérés dans les boucles for...in. De plus, la méthode Object.getOwnPropertyNames() ne renverra pas les propriétés identifiées par des symboles. La méthode Object.getOwnPropertySymbols() permet d'avoir accès à ces propriétés.

var obj = {};

obj[Symbol("a")] = "a";
obj[Symbol.for("b")] = "b";
obj["c"] = "c";
obj.d = "d";

for (var i in obj) {
   console.log(i); // enregistre "c" et "d"
}

Les symboles et JSON.stringify()

Les propriétés identifiées par des symboles seront totalement ignorées par JSON.stringify():

JSON.stringify({[Symbol("toto")]: "toto"});                 
// '{}'

Pour plus de détails, voir la page JSON.stringify().

Utiliser les symboles enveloppés dans un objet

Lors qu'on on utilise un objet pour contenir la valeur du symbole et faire référence à une propriété, l'objet sera ramené au symbole d'origine :

var sym = Symbol("toto")
var obj = {[sym]: 1};
obj[sym];              // 1
obj[Object(sym)];      // toujours 1

Spécifications

Spécification État Commentaires
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Symbol' dans cette spécification.
Standard Définition initiale.
ECMAScript Latest Draft (ECMA-262)
La définition de 'Symbol' dans cette spécification.
Projet  

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidEdge MobileFirefox pour AndroidOpera pour AndroidSafari pour iOSSamsung InternetNode.js
Support simpleChrome Support complet 38Edge Support complet 12
Notes
Support complet 12
Notes
Notes Edge 12 included Symbol properties in JSON.stringify() output.
Firefox Support complet 36IE Aucun support NonOpera Support complet 25Safari Support complet 9WebView Android Support complet OuiChrome Android Support complet 38Edge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet 25Safari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
asyncIterator
Expérimentale
Chrome Aucun support NonEdge Aucun support NonFirefox Aucun support Non
Notes
Aucun support Non
Notes
Notes Available in Firefox Nightly.
IE Aucun support NonOpera Aucun support NonSafari Aucun support NonWebView Android Aucun support NonChrome Android Aucun support NonEdge Mobile Aucun support NonFirefox Android Aucun support NonOpera Android Aucun support NonSafari iOS Aucun support NonSamsung Internet Android Aucun support Nonnodejs Aucun support Non
descriptionChrome Support complet 70Edge Aucun support NonFirefox Support complet 63IE Aucun support NonOpera Support complet 57Safari Aucun support NonWebView Android Support complet 70Chrome Android Support complet 70Edge Mobile Aucun support NonFirefox Android Support complet 63Opera Android Support complet 57Safari iOS Aucun support NonSamsung Internet Android Aucun support Nonnodejs Aucun support Non
forChrome Support complet 40Edge Support complet OuiFirefox Support complet 36IE Aucun support NonOpera Support complet OuiSafari Support complet 9WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet OuiSafari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
hasInstanceChrome Support complet 51Edge Support complet 15Firefox Support complet 50IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 50Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.5.0
Support complet 6.5.0
Support complet 6.0.0
Désactivée
Désactivée From version 6.0.0: this feature is behind the --harmony runtime flag.
isConcatSpreadableChrome Support complet 48Edge Support complet 15Firefox Support complet 48IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 48Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
iteratorChrome Support complet 43Edge Support complet OuiFirefox Support complet 36IE Aucun support NonOpera Support complet 30Safari Support complet 10WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet OuiSafari iOS Support complet 10Samsung Internet Android Support complet Ouinodejs Support complet 0.12
keyForChrome Support complet 40Edge Support complet OuiFirefox Support complet 36IE Aucun support NonOpera Support complet OuiSafari Support complet 9WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet OuiSafari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
matchChrome Support complet 50Edge Support complet OuiFirefox Support complet 40IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 40Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
prototypeChrome Support complet 38Edge Support complet 12Firefox Support complet 36IE Aucun support NonOpera Support complet 25Safari Support complet 9WebView Android Support complet OuiChrome Android Support complet 38Edge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet 25Safari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
replaceChrome Support complet 50Edge Support complet OuiFirefox Support complet 49IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 49Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
searchChrome Support complet 50Edge Support complet OuiFirefox Support complet 49IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 49Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
speciesChrome Support complet 51Edge Support complet 14Firefox Support complet 41IE Aucun support NonOpera Support complet 38Safari Support complet 10WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet 14Firefox Android Support complet 41Opera Android Support complet 38Safari iOS Support complet 10Samsung Internet Android Support complet Ouinodejs Support complet 6.5.0
Support complet 6.5.0
Support complet 6.0.0
Désactivée
Désactivée From version 6.0.0: this feature is behind the --harmony runtime flag.
splitChrome Support complet 50Edge Support complet OuiFirefox Support complet 49IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 49Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
toPrimitiveChrome Support complet 48Edge Support complet 15Firefox Support complet 44IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 44Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
toSource
Non-standard
Chrome Aucun support NonEdge Aucun support NonFirefox Support complet 36IE Aucun support NonOpera Aucun support NonSafari Aucun support NonWebView Android Aucun support NonChrome Android Aucun support NonEdge Mobile Aucun support NonFirefox Android Support complet 36Opera Android Aucun support NonSafari iOS Aucun support NonSamsung Internet Android Aucun support Nonnodejs Aucun support Non
toStringChrome Support complet 38Edge Support complet 12Firefox Support complet 36IE Aucun support NonOpera Support complet 25Safari Support complet 9WebView Android Support complet OuiChrome Android Support complet 38Edge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet 25Safari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
toStringTagChrome Support complet 49Edge Support complet 15Firefox Support complet 51IE Aucun support NonOpera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 51Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Ouinodejs Support complet 6.0.0
Support complet 6.0.0
Support complet 4.0.0
Désactivée
Désactivée From version 4.0.0: this feature is behind the --harmony runtime flag.
unscopablesChrome Support complet 38Edge Support complet OuiFirefox Support complet 48IE Aucun support NonOpera Support complet OuiSafari Support complet 9WebView Android Support complet OuiChrome Android Support complet OuiEdge Mobile Support complet OuiFirefox Android Support complet 48Opera Android Support complet OuiSafari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet 0.12
valueOfChrome Support complet 38Edge Support complet 12Firefox Support complet 36IE Aucun support NonOpera Support complet 25Safari Support complet 9WebView Android Support complet OuiChrome Android Support complet 38Edge Mobile Support complet OuiFirefox Android Support complet 36Opera Android Support complet 25Safari iOS Support complet 9Samsung Internet Android Support complet Ouinodejs Support complet Oui
@@toPrimitiveChrome ? Edge ? Firefox Support complet 44IE Aucun support NonOpera ? Safari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android Support complet 44Opera Android ? Safari iOS ? Samsung Internet Android ? nodejs ?

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité expérimentale. Celle-ci peut être amenée à changer par la suite.
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Fonctionnalité non-standard. Celle-ci peut être incorrectement supportée par les autres navigateurs.
Voir les notes d'implémentation.
Voir les notes d'implémentation.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.
Une action explicite de l'utilisateur est nécessaire pour activer cette fonctionnalité.

Voir aussi

Étiquettes et contributeurs liés au document

Contributeurs à cette page : SphinxKnight, fscholz, mo0z, kdex
Dernière mise à jour par : SphinxKnight,