mozilla
Vos résultats de recherche

    Symbol

    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.

    Un symbole est un type de données uniques et inchangeables 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. ECMAScript 6 ne permet plus la création de conteneurs explicites pour les types de données primitifs. Malgré cela, il est toujours possible d'utiliser new Boolean, new String et new Number afin d'assurer une certaine rétrocompatibilité.

    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'à 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 1.
    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érations

    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.

    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 tableau (Array) de chaînes de caractères qui sont des valeurs de propriétés. Ces propriétés sont exclues lors de la liaison d'environnement via 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

    Symbol.prototype.constructor
    Cette propriété correspond à la fonction qui a crée l'instance du prototype. Par défaut, c'est la fonction Symbol qui est renvoyée.

    Méthodes

    Symbol.prototype.toSource()
    Cette méthode renvoie une chaîne de caractères contenant la source de l'objet Symbol. Cette méthode surcharge la méthode Object.prototype.toSource().
    Symbol.prototype.toString()
    Cette méthode renvoie une chaîne de caractères contenant la description du symbole. Cette méthode surcharge la méthode Object.prototype.toString().
    Symbol.prototype.valueOf()
    Cette méthode renvoie la valeur primitive de l'objet Symbol. Cette méthode surcharge la méthode Object.prototype.valueOf().

    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 sont pas visibles 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 Statut Commentaires
    ECMAScript 6 (ECMA-262)
    La définition de 'Symbol' dans cette spécification.
    En cours de validation comme recommandation Définition initiale.

    Compatibilité des navigateurs

    Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Support simple 38 36.0 (36.0) Pas de support 25 Pas de support
    Symbol.iterator (@@iterator) 38 36.0 (36.0) Pas de support 25 Pas de support
    Symbol.unscopables (@@unscopables) 38 Pas de support Pas de support 25 Pas de support
    Symbol.match (@@match) Pas de support 40.0 (40.0) Pas de support Pas de support Pas de support
    Symbol.species (@@species) Pas de support 41.0 (41.0) Pas de support Pas de support Pas de support
    Autres symboles connus Pas de support Pas de support Pas de support Pas de support Pas de support
    Fonctionnalités Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    Support simple Pas de support 38 36.0 (36.0) Pas de support 25 Pas de support
    Symbol.iterator (@@iterator) Pas de support 38 36.0 (36.0) Pas de support 25 Pas de support
    Symbol.unscopables (@@unscopables) Pas de support 38 Pas de support Pas de support 25 Pas de support
    Symbol.match (@@match) Pas de support Pas de support 40.0 (40.0) Pas de support Pas de support Pas de support
    Symbol.species (@@species) Pas de support Pas de support 41.0 (41.0) Pas de support Pas de support Pas de support
    Autres symboles connus Pas de support Pas de support Pas de support Pas de support Pas de support Pas de support


    Voir aussi

    Étiquettes et contributeurs liés au document

    Contributors to this page: SphinxKnight
    Dernière mise à jour par : SphinxKnight,