Un symbole est un type de données primitif représentant une donnée unique et inchangeable qui peut être utilisée afin de 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.
Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !
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
ousym | 0
). - L'égalité faible permet d'obtenir
true
avecObject(sym) == sym
.
Symbol("toto") + "truc"
lève une exceptionTypeError
(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.matchAll
- Une méthode qui renvoie un itérateur permettant de parcourir l'ensemble des correspondances entre une chaîne de caractères et une expression rationnelle. Ce symbole est utilisé par
String.prototype.matchAll()
. 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
Ordinateur | Mobile | Serveur | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Symbol | Chrome Support complet 38 | Edge
Support complet
12
| Firefox Support complet 36 | IE Aucun support Non | Opera Support complet 25 | Safari Support complet 9 | WebView Android Support complet 38 | Chrome Android Support complet 38 | Firefox Android Support complet 36 | Opera Android Support complet 25 | Safari iOS Support complet 9 | Samsung Internet Android Support complet 3.0 | nodejs Support complet Oui |
asyncIterator | Chrome Support complet 63 | Edge Aucun support Non | Firefox Support complet 57 | IE Aucun support Non | Opera Support complet 50 | Safari Support complet 11.1 | WebView Android Support complet 63 | Chrome Android Support complet 63 | Firefox Android Aucun support Non | Opera Android Support complet 46 | Safari iOS Aucun support Non | Samsung Internet Android Support complet 8.0 | nodejs Support complet 10.0.0 |
description | Chrome Support complet 70 | Edge Aucun support Non | Firefox Support complet 63 | IE Aucun support Non | Opera Support complet 57 | Safari
Support complet
12.1
| WebView Android Support complet 70 | Chrome Android Support complet 70 | Firefox Android Support complet 63 | Opera Android Support complet 49 | Safari iOS
Support complet
12.2
| Samsung Internet Android Support complet 10.0 | nodejs Support complet 11.0.0 |
for | Chrome Support complet 40 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet 9 | WebView Android Support complet 40 | Chrome Android Support complet 40 | Firefox Android Support complet 36 | Opera Android Support complet Oui | Safari iOS Support complet 9 | Samsung Internet Android Support complet 4.0 | nodejs Support complet Oui |
hasInstance | Chrome Support complet 50 | Edge Support complet 15 | Firefox Support complet 50 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 50 | Chrome Android Support complet 50 | Firefox Android Support complet 50 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs
Support complet
6.5.0
|
isConcatSpreadable | Chrome Support complet 48 | Edge Support complet 15 | Firefox Support complet 48 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 48 | Chrome Android Support complet 48 | Firefox Android Support complet 48 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
iterator | Chrome Support complet 43 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet 30 | Safari Support complet 10 | WebView Android Support complet 43 | Chrome Android Support complet 43 | Firefox Android Support complet 36 | Opera Android Support complet Oui | Safari iOS Support complet 10 | Samsung Internet Android Support complet 4.0 | nodejs Support complet 0.12 |
keyFor | Chrome Support complet 40 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet 9 | WebView Android Support complet 40 | Chrome Android Support complet 40 | Firefox Android Support complet 36 | Opera Android Support complet Oui | Safari iOS Support complet 9 | Samsung Internet Android Support complet 4.0 | nodejs Support complet Oui |
match | Chrome Support complet 50 | Edge Aucun support Non | Firefox Support complet 40 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 50 | Chrome Android Support complet 50 | Firefox Android Support complet 40 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
matchAll | Chrome Support complet 73 | Edge Aucun support Non | Firefox Support complet 67 | IE Aucun support Non | Opera Support complet 60 | Safari Aucun support Non | WebView Android Support complet 73 | Chrome Android Support complet 73 | Firefox Android Support complet 67 | Opera Android Support complet Oui | Safari iOS Aucun support Non | Samsung Internet Android Aucun support Non | nodejs Support complet 12.0.0 |
prototype | Chrome Support complet 38 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet 25 | Safari Support complet 9 | WebView Android Support complet 38 | Chrome Android Support complet 38 | Firefox Android Support complet 36 | Opera Android Support complet 25 | Safari iOS Support complet 9 | Samsung Internet Android Support complet 3.0 | nodejs Support complet Oui |
replace | Chrome Support complet 50 | Edge Aucun support Non | Firefox Support complet 49 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 50 | Chrome Android Support complet 50 | Firefox Android Support complet 49 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
search | Chrome Support complet 50 | Edge Aucun support Non | Firefox Support complet 49 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 50 | Chrome Android Support complet 50 | Firefox Android Support complet 49 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
species | Chrome Support complet 51 | Edge Support complet 13 | Firefox Support complet 41 | IE Aucun support Non | Opera Support complet 38 | Safari Support complet 10 | WebView Android Support complet 51 | Chrome Android Support complet 51 | Firefox Android Support complet 41 | Opera Android Support complet 41 | Safari iOS Support complet 10 | Samsung Internet Android Support complet 5.0 | nodejs
Support complet
6.5.0
|
split | Chrome Support complet 50 | Edge Aucun support Non | Firefox Support complet 49 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 50 | Chrome Android Support complet 50 | Firefox Android Support complet 49 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
toPrimitive | Chrome Support complet 47 | Edge Support complet 15 | Firefox Support complet 44 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 47 | Chrome Android Support complet 47 | Firefox Android Support complet 44 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs Support complet 6.0.0 |
toSource | Chrome Aucun support Non | Edge Aucun support Non | Firefox Support complet 36 | IE Aucun support Non | Opera Aucun support Non | Safari Aucun support Non | WebView Android Aucun support Non | Chrome Android Aucun support Non | Firefox Android Support complet 36 | Opera Android Aucun support Non | Safari iOS Aucun support Non | Samsung Internet Android Aucun support Non | nodejs Aucun support Non |
toString | Chrome Support complet 38 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet 25 | Safari Support complet 9 | WebView Android Support complet 38 | Chrome Android Support complet 38 | Firefox Android Support complet 36 | Opera Android Support complet 25 | Safari iOS Support complet 9 | Samsung Internet Android Support complet 3.0 | nodejs Support complet Oui |
toStringTag | Chrome Support complet 49 | Edge Support complet 15 | Firefox Support complet 51 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet 49 | Chrome Android Support complet 49 | Firefox Android Support complet 51 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet 5.0 | nodejs
Support complet
6.0.0
|
unscopables | Chrome Support complet 45 | Edge Support complet 12 | Firefox Support complet 48 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet 9 | WebView Android Support complet 45 | Chrome Android Support complet 45 | Firefox Android Support complet 48 | Opera Android Support complet Oui | Safari iOS Support complet 9 | Samsung Internet Android Support complet 5.0 | nodejs Support complet 0.12 |
valueOf | Chrome Support complet 38 | Edge Support complet 12 | Firefox Support complet 36 | IE Aucun support Non | Opera Support complet 25 | Safari Support complet 9 | WebView Android Support complet 38 | Chrome Android Support complet 38 | Firefox Android Support complet 36 | Opera Android Support complet 25 | Safari iOS Support complet 9 | Samsung Internet Android Support complet 3.0 | nodejs Support complet Oui |
@@toPrimitive | Chrome Support complet 47 | Edge Support complet 15 | Firefox Support complet 44 | IE Aucun support Non | Opera Support complet 34 | Safari ? | WebView Android Support complet 47 | Chrome Android Support complet 47 | Firefox Android Support complet 44 | Opera Android Support complet 34 | Safari iOS ? | Samsung Internet Android Support complet 5.0 | nodejs ? |
Légende
- Support complet
- Support complet
- Aucun support
- Aucun support
- Compatibilité inconnue
- Compatibilité inconnue
- 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é.