Symbol

Beschreibung

Um einen neuen primitiven Symbol-Wert zu erstellen, schreiben Sie Symbol() und bergeben optional einen String als Beschreibung:

const sym1 = Symbol();
const sym2 = Symbol("foo");
const sym3 = Symbol("foo");

Der obige Code erstellt drei neue Symbole. Beachten Sie, dass Symbol("foo") den String "foo" nicht in ein Symbol umwandelt. Jeder Aufruf erstellt ein neues Symbol:

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

Die folgende Syntax mit dem Operator new lst einen TypeError aus:

const sym = new Symbol(); // TypeError

Dies verhindert, dass statt eines neuen Symbol-Werts ausdrcklich ein Symbol-Wrapper-Objekt erstellt wird. Das kann berraschen, da sich Wrapper-Objekte fr primitive Datentypen normalerweise ausdrcklich erstellen lassen (beispielsweise mit new Boolean, new String und new Number).

Wenn Sie tatschlich ein Symbol-Wrapper-Objekt erstellen mchten, knnen Sie die Funktion Object() verwenden:

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

Symbole sind der einzige primitive Datentyp mit Referenzidentitt (das heit, Sie knnen dasselbe Symbol nicht zweimal erstellen). Daher verhalten sie sich in mancher Hinsicht wie Objekte. Beispielsweise knnen sie per Garbage Collection entfernt und deshalb in Objekten vom Typ WeakMap, WeakSet, WeakRef und FinalizationRegistry verwendet werden.

Gemeinsam genutzte Symbole in der globalen Symbol-Registry

Die oben gezeigte Syntax mit der Funktion Symbol() erstellt ein Symbol, dessen Wert whrend der gesamten Laufzeit des Programms eindeutig bleibt. Um Symbole zu erstellen, die dateibergreifend und sogar ber verschiedene Realms hinweg verfgbar sind (von denen jeder seinen eigenen globalen Gltigkeitsbereich hat), verwenden Sie die Methoden Symbol.for() und Symbol.keyFor(), um Symbole in der globalen Symbol-Registry abzulegen und daraus abzurufen.

Beachten Sie, dass die globale Symbol-Registry nur ein gedankliches Konzept ist und keiner internen Datenstruktur der JavaScript-Engine entsprechen muss. Selbst wenn eine solche Registry existiert, kann JavaScript-Code nur ber die Methoden for() und keyFor() auf ihren Inhalt zugreifen.

Die Methode Symbol.for(tokenString) nimmt einen String-Key entgegen und gibt einen Symbol-Wert aus der Registry zurck. Symbol.keyFor(symbolValue) nimmt dagegen einen Symbol-Wert entgegen und gibt den zugehrigen String-Key zurck. Die Methoden sind zueinander invers, sodass Folgendes true ergibt:

Symbol.keyFor(Symbol.for("tokenString")) === "tokenString"; // true

Da registrierte Symbole an beliebiger Stelle erstellt werden knnen, verhalten sie sich fast genauso wie die Strings, denen sie zugeordnet sind. Deshalb ist ihre Eindeutigkeit nicht garantiert, und sie knnen nicht per Garbage Collection entfernt werden. Registrierte Symbole sind daher in Objekten vom Typ WeakMap, WeakSet, WeakRef und FinalizationRegistry nicht zulssig.

Bekannte Symbole

Alle statischen Properties des Symbol-Konstruktors sind selbst Symbole, deren Werte ber Realms hinweg konstant sind. Sie werden als bekannte Symbole bezeichnet. Sie dienen als Protokolle fr bestimmte integrierte JavaScript-Operationen und ermglichen es, das Verhalten der Sprache anzupassen. Hat eine Konstruktorfunktion beispielsweise eine Methode mit Symbol.hasInstance als Namen, legt diese Methode ihr Verhalten beim Operator instanceof fest.

Bevor es bekannte Symbole gab, verwendete JavaScript normale Properties, um bestimmte integrierte Operationen zu implementieren. Beispielsweise versucht die Funktion JSON.stringify, die Methode toJSON() jedes Objekts aufzurufen. Die Funktion String ruft die Methoden toString() und valueOf() des Objekts auf. Wenn der Sprache weitere Operationen hinzugefgt werden, kann jedoch die Zuweisung einer magischen Property fr jede Operation die Abwrtskompatibilitt beeintrchtigen und das Verhalten der Sprache schwerer nachvollziehbar machen. Bekannte Symbole ermglichen Anpassungen, die fr normalen Code unsichtbar sind, da dieser blicherweise nur auf Properties mit String-Keys zugreift.

Bei bekannten Symbolen stellt sich die Frage der Entfernbarkeit per Garbage Collection nicht: Sie bilden eine feste Menge und bleiben whrend der gesamten Laufzeit des Programms eindeutig, hnlich wie intrinsische Objekte wie Array.prototype. Daher sind sie auch in Objekten vom Typ WeakMap, WeakSet, WeakRef und FinalizationRegistry zulssig.

Symbol-Properties auf Objekten finden

Die Methode Object.getOwnPropertySymbols() gibt ein Array von Symbolen zurck und ermglicht es Ihnen, Symbol-Properties eines bestimmten Objekts zu finden. Beachten Sie, dass jedes Objekt zunchst keine eigenen Symbol-Properties besitzt. Das Array ist daher leer, solange Sie dem Objekt keine Symbol-Properties hinzugefgt haben.

Konstruktor

Symbol()

Gibt primitive Werte vom Typ Symbol zurck. Wird die Funktion mit new aufgerufen, lst sie einen Fehler aus.

Statische Properties

Alle statischen Properties sind bekannte Symbole. In ihren Beschreibungen verwenden wir Formulierungen wie Symbol.hasInstance ist eine Methode, die bestimmt . Gemeint ist damit das Verhalten einer Objektmethode, die dieses Symbol als Methodennamen verwendet (da bekannte Symbole als Protokolle dienen), nicht der Wert des Symbols selbst.

Symbol.asyncDispose

Eine Methode, die Ressourcen des Objekts asynchron freigibt, wenn das Objekt seinen Gltigkeitsbereich verlsst. Wird von der Deklaration await using verwendet.

Symbol.asyncIterator

Eine Methode, die den standardmigen AsyncIterator eines Objekts zurckgibt. Wird von for await...of verwendet.

Symbol.dispose

Eine Methode, die Ressourcen des Objekts freigibt, wenn das Objekt seinen Gltigkeitsbereich verlsst. Wird von der Deklaration using verwendet.

Symbol.hasInstance

Eine Methode, die bestimmt, ob ein Konstruktorobjekt ein Objekt als seine Instanz erkennt. Wird von instanceof verwendet.

Symbol.isConcatSpreadable

Ein Boolean-Wert, der angibt, ob ein Objekt in seine Array-Elemente aufgefchert werden soll. Wird von Array.prototype.concat() verwendet.

Symbol.iterator

Eine Methode, die den standardmigen Iterator eines Objekts zurckgibt. Wird von for...of verwendet.

Symbol.match

Eine Methode, die bereinstimmungen mit einem String ermittelt. Sie wird auch verwendet, um festzustellen, ob ein Objekt als regulrer Ausdruck verwendet werden kann. Wird von String.prototype.match() verwendet.

Symbol.matchAll

Eine Methode, die einen Iterator zurckgibt, der bereinstimmungen eines regulren Ausdrucks mit einem String liefert. Wird von String.prototype.matchAll() verwendet.

Symbol.replace

Eine Methode, die passende Teilstrings eines Strings ersetzt. Wird von String.prototype.replace() verwendet.

Symbol.search

Eine Methode, die den Index der Stelle in einem String zurckgibt, an der eine bereinstimmung mit dem regulren Ausdruck gefunden wird. Wird von String.prototype.search() verwendet.

Symbol.species

Eine Konstruktorfunktion, mit der abgeleitete Objekte erstellt werden.

Symbol.split

Eine Methode, die einen String an den Stellen aufteilt, die einem regulren Ausdruck entsprechen. Wird von String.prototype.split() verwendet.

Symbol.toPrimitive

Eine Methode, die ein Objekt in einen primitiven Wert umwandelt.

Symbol.toStringTag

Ein String-Wert, der fr die Standardbeschreibung eines Objekts verwendet wird. Wird von Object.prototype.toString() verwendet.

Symbol.unscopables

Ein Objektwert, dessen eigene und geerbte Property-Namen aus den Umgebungsbindungen von with fr das zugehrige Objekt ausgeschlossen werden.

Statische Methoden

Symbol.for()

Sucht in der globalen Symbol-Registry nach einem bereits registrierten Symbol mit dem angegebenen key und gibt es zurck, falls es gefunden wird. Andernfalls wird ein neues Symbol erstellt und unter key registriert.

Symbol.keyFor()

Ruft fr das angegebene Symbol den Key eines gemeinsam genutzten Symbols aus der globalen Symbol-Registry ab.

Instanz-Properties

Diese Properties sind auf Symbol.prototype definiert und werden von allen Symbol-Instanzen gemeinsam genutzt.

Symbol.prototype.constructor

Die Konstruktorfunktion, die das Instanzobjekt erstellt hat. Bei Symbol-Instanzen ist der Anfangswert der Konstruktor Symbol.

Symbol.prototype.description

Ein schreibgeschtzter String, der die Beschreibung des Symbols enthlt.

Symbol.prototype[Symbol.toStringTag]

Der Anfangswert der Property [Symbol.toStringTag] ist der String "Symbol". Diese Property wird von Object.prototype.toString() verwendet. Da Symbol jedoch auch eine eigene Methode toString() besitzt, wird diese Property nur verwendet, wenn Sie Object.prototype.toString.call() mit einem Symbol als thisArg aufrufen.

Instanzmethoden

Symbol.prototype.toString()

Gibt einen String zurck, der die Beschreibung des Symbols enthlt. berschreibt die Methode Object.prototype.toString().

Symbol.prototype.valueOf()

Gibt das Symbol zurck. berschreibt die Methode Object.prototype.valueOf().

Symbol.prototype[Symbol.toPrimitive]()

Gibt das Symbol zurck.

Beispiele

Den Operator typeof mit Symbolen verwenden

Mit dem Operator typeof knnen Sie Symbole erkennen.

typeof Symbol() === "symbol";
typeof Symbol("foo") === "symbol";
typeof Symbol.iterator === "symbol";

Typkonvertierungen von Symbolen

Bei der Typkonvertierung von Symbolen sollten Sie Folgendes beachten:

• Der Versuch, ein Symbol in eine Zahl umzuwandeln, lst einen TypeError aus (beispielsweise +sym oder sym | 0).
• Bei einem Vergleich mit lockerer Gleichheit gibt Object(sym) == sym den Wert true zurck.
• Symbol("foo") + "bar" lst einen TypeError aus (ein Symbol kann nicht in einen String umgewandelt werden). Das verhindert beispielsweise, dass aus einem Symbol unbemerkt ein neuer String-Property-Name entsteht.
• Die sicherere Konvertierung mit String(sym) funktioniert bei Symbolen wie ein Aufruf von Symbol.prototype.toString(). Beachten Sie jedoch, dass new String(sym) einen Fehler auslst.

Symbole und for...in-Iteration

Symbole werden bei Iterationen mit for...in nicht aufgezhlt. Auch Object.getOwnPropertyNames() gibt keine Symbol-Properties eines Objekts zurck. Mit Object.getOwnPropertySymbols() knnen Sie diese jedoch abrufen.

const obj = {};

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

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

Symbole und JSON.stringify()

Properties mit Symbol-Keys werden bei der Verwendung von JSON.stringify() vollstndig ignoriert:

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

Weitere Einzelheiten finden Sie unter JSON.stringify().

Symbol-Wrapper-Objekte als Property-Keys

Wird ein Symbol-Wrapper-Objekt als Property-Key verwendet, wird dieses Objekt in das enthaltene Symbol umgewandelt:

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

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Polyfill fr Symbol in core-js
• typeof
• JavaScript-Datentypen und -Datenstrukturen
• ES6 im Detail: Symbole auf hacks.mozilla.org (2015)