Symbol

La funzione Symbol() restituisce un valore di tipo symbol, dispone di proprietà statiche che espongono diversi membri di oggetti built-in, ha metodi statici che espongono il registro globale dei symbol, ed assomiglia all'oggetto built-in class, ma non dispone di un costruttore e non supporta la sintassi "new Symbol()".  

Ogni valore symbol restituito da Symbol() è unico.  Un valore symbol può essere utilizzato come identificatore per proprietà di un oggetto; questo è lo scopo di tale tipo di dati.  Ulteriori spiegazioni circa il loro scopo ed uso può essere trovato nella pagina: glossary entry for Symbol.

Il tipo di dati symbol è un primitive data type.

Syntax

Symbol([description])

Parametri

description Optional

Opzionale, string. Una descrizione del symbol che può essere usata per il debug ma non per accedere al symbol stesso.

Descrizione

Per creare un nuovo primitive symbol, scrivereSymbol() con una stringa opzionale di descrizione:

var sym1 = Symbol();
var sym2 = Symbol('foo');
var sym3 = Symbol('foo');

Il codice sopra crea tre nuovi symbol. Notare che Symbol("foo") non costringe la stringa "foo" in un symbol. Esso crea un nuovo symbol ogni volta:

Symbol('foo') === Symbol('foo'); // false

La sintassi seguente con l'operatore new genererà un TypeError:

var sym = new Symbol(); // TypeError

Questo previene gli autori dal creare un esplicito oggetto wrapper Symbol invece di un nuovo valore symbol e la cosa può sorprendere in quanto creare un oggetto wrapper esplicito attorno ad un tipo di dati primitivo è generalmente possibile (ad esempio, new Boolean, new String e new Number).

Se veramente si vuole creare un oggetto wrapper Symbol si può usare la funzione Object():

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

Symbols condivisi nel registro globale dei symbol

La sintassi vista sopra che utilizza la funzione Symbol() non crea un symbol globale che sarà disponibile nell'intero codebase. Per creare dei symbol disponibili attraverso diversi files ed anche attraverso diversi realms (ognuno dei quali ha il proprio global scope), usare i metodi Symbol.for() e Symbol.keyFor() per impostare e leggere i symbol dal registro globale.

Cercare le proprietà symbol negli oggetti

Il metodo Object.getOwnPropertySymbols() restituisce un array di symbol e permette di trovare le proprietà symbol di un oggetto. Notare che ogni oggetto è inizializzato senza alcuna proprietà symbol, per cui l'array restituito sarà vuoto a meno che una proprietà symbol non sia stata creata sull'oggetto.

Proprietà

Symbol.length

Proprietà "lunghezza", il cui valore è 0.

Symbol.prototype

Rappresenta il prototype del costruttore Symbol.

Symbols ben noti

In aggiunta ai symbol definiti da voi, JavaScript dispone di alcuni symbol built-in che rappresentano alcuni comportamenti interni del linguaggio che non sono esposti agli sviluppatori in ECMAScript5 e precedenti. A tali symbol si può accedere tramite le seguenti proprietà:

Symbols di iterazione

Symbol.iterator

Un metodo che restituisce l'iteratore di default per un oggetto. Usato da for...of.

Symbol.asyncIterator

Un metodo che restituisce l'iteratore asincrono di default per un oggetto. Usato da for await of.

Symbols per le espressioni regolari

Symbol.match

Un metodo che effettua la corrispondenza su una stringa, usato anche per determinare se un oggetto può essere utilizzato come espressione regolare. Usato da String.prototype.match().

Symbol.replace

Un metodo che sostituisce le sottostringhe di una stringa corrispondenti. Usato da String.prototype.replace().

Symbol.search

Un metodo che restituisce l'indice all'interno di una stringa che corrisponde all'espressione regolare. Usato da String.prototype.search().

Symbol.split

Un metodo che divide una stringa all'indice corrispondente ad una espressione regolare. Usato da String.prototype.split().

Altri symbols

Symbol.hasInstance

Un metodo che determina se un oggetto costruttore riconosce un oggetto come propria istanza. Usato da instanceof.

Symbol.isConcatSpreadable

Un valore booleano indicante se un oggetto deve essere appiattito ai soui elementi array. Usato da Array.prototype.concat().

Symbol.unscopables

An object value of whose own and inherited property names are excluded from the with environment bindings of the associated object.

Symbol.species

Una funzione costruttore utilizzata per creare oggetti derivati.

Symbol.toPrimitive

Un metodo che converte un oggetto in un valore primitivo.

Symbol.toStringTag

Una stringa usata per la descizione di default di un oggetto. Usato da Object.prototype.toString().

Metodi

Symbol.for(key)

Cerca la "key" fornita tra i symbol esistenti e la restituisce nel caso in cui venga trovata. In caso contrario un nuovo symbol viene creato nel registro globale dei symbol con la "key" indicata.

Symbol.keyFor(sym)

Trova una chiave symbol condivisa dal registro globale dei symbol per il symbol fornito.

Symbol prototype

Tutti i simboli ereditano da Symbol.prototype.

Proprietà

Symbol.length

Length property, whose value is 0.

Symbol.prototype

Represents the prototype for the Symbol constructor.

Well-known symbols

In addition to your own symbols, JavaScript has some built-in symbols which represent internal language behaviors which were not exposed to developers in ECMAScript 5 and before. These symbols can be accessed using the following properties:

Iteration symbols

Symbol.iterator

A method returning the default iterator for an object. Used by for...of.

Symbol.asyncIterator

A method that returns the default AsyncIterator for an object. Used by for await...of.

Regular expression symbols

Symbol.match

A method that matches against a string, also used to determine if an object may be used as a regular expression. Used by String.prototype.match().

Symbol.matchAll

A method that returns an iterator, that yields matches of the regular expression against a string. Used by String.prototype.matchAll().

Symbol.replace

A method that replaces matched substrings of a string. Used by String.prototype.replace().

Symbol.search

A method that returns the index within a string that matches the regular expression. Used by String.prototype.search().

Symbol.split

A method that splits a string at the indices that match a regular expression. Used by String.prototype.split().

Other symbols

Symbol.hasInstance

A method determining if a constructor object recognizes an object as its instance. Used by instanceof.

Symbol.isConcatSpreadable

A Boolean value indicating if an object should be flattened to its array elements. Used by Array.prototype.concat().

Symbol.unscopables

An object value of whose own and inherited property names are excluded from the with environment bindings of the associated object.

Symbol.species

A constructor function that is used to create derived objects.

Symbol.toPrimitive

A method converting an object to a primitive value.

Symbol.toStringTag

A string value used for the default description of an object. Used by Object.prototype.toString().

Metodi

Symbol.for(key)

Searches for existing symbols with the given key and returns it if found. Otherwise a new symbol gets created in the global symbol registry with key.

Symbol.keyFor(sym)

Retrieves a shared symbol key from the global symbol registry for the given symbol.

Esempi

Using the typeof operator with symbols

L'operatore typeof può aiutare ad identificare i symbol.

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

Conversioni di tipo dei symbol

Alcune cose da notare quando si lavora con le conversioni di tipo dei symbol.

• Quando si prova a convertire un symbol in un numero, un TypeError verrà generato
  (e.g. +sym or sym | 0).
• Quando si usa l'uguaglianza non stretta, Object(sym) == sym restituisce true.
• Symbol("foo") + "bar" lancia un TypeError (non si può convertire un symbol in stringa). Questo previene, ad esempio, la creazione silenziosa di un nuovo nome di proprietà stringa da un symbol.
• La "safer" String(sym) conversion funziona come una chiamata a Symbol.prototype.toString() con symbol, ma notare che new String(sym) genererà un errore.

Symbols ed iterazione for...in

I symbol non sono enumerabili in un'iterazione for...in. In aggiunta, Object.getOwnPropertyNames() non restituirà le proprietà symbol dell'oggetto, tuttavia, si puù usare Object.getOwnPropertySymbols() per ottenerle.

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); // logs "c" and "d"
}

Symbols e JSON.stringify()

Le proprietà le cui chiavi sono symbol vengono completamente ignorate da JSON.stringify():

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

Per ulteriori dettagli, vedere JSON.stringify().

Symbol wrapper objects come chiavi per le proprietà

Quando un oggetto wrapper symbol viene usato come chiave di una proprietà, tale oggetto verrà costretto al suo wrapped symbol:

var sym = Symbol('foo');
var obj = {[sym]: 1};
obj[sym];            // 1
obj[Object(sym)];    // still 1

Specificazioni

Browser compatibility

Vedere anche

• Glossary: Symbol data type
• typeof
• Data types and data structures
• "ES6 In Depth: Symbols" on hacks.mozilla.org