Symbol.prototype.valueOf() — Methode · JavaScript-Referenz

Signatur

Symbol.prototype.valueOf()

Beschreibung

Die Methode valueOf() von Symbol.prototype gibt den primitiven Symbolwert zurück. Wird sie auf einem primitiven Symbol aufgerufen, kommt genau dieses Symbol zurück. Bei einem Symbol-Wrapper-Objekt, etwa aus Object(sym), liefert sie das darin gespeicherte primitive Symbol.

Im Alltag ruft man valueOf() selten direkt auf. Nützlich ist die Methode vor allem, wenn man aus einem Wrapper-Objekt wieder das primitive Symbol braucht, zum Beispiel für einen strikten Vergleich mit === oder als Eigenschaftsschlüssel.

Wichtig: Wenn JavaScript Werte automatisch umwandelt, wird nicht valueOf(), sondern zuerst Symbol.prototype[Symbol.toPrimitive] aufgerufen. Außerdem lassen sich Symbole weder automatisch in Zahlen noch in Zeichenketten umwandeln: sym + 1 oder `${sym}` werfen einen TypeError, egal ob man valueOf() nutzt oder nicht.

Rückgabewert

Typ

symbol

Beschreibung

Der primitive Symbolwert des angegebenen Symbol-Werts bzw. Wrapper-Objekts.

Beispiele

Primitives Symbol gibt sich selbst zurück

const id = Symbol('id');

console.log(id.valueOf() === id);
console.log(typeof id.valueOf());

true symbol

Primitives Symbol aus einem Wrapper-Objekt holen

const sym = Symbol('token');
const wrapper = Object(sym);

console.log(typeof wrapper);           // Wrapper ist ein Objekt
console.log(wrapper === sym);          // Objekt ≠ Primitiv
console.log(wrapper.valueOf() === sym); // primitives Symbol zurückgewonnen

object false true

Symbol-Schlüssel aus einem Wrapper verwenden

const secret = Symbol('secret');
const config = { [secret]: 'geheim' };

// z. B. aus einer API, die Werte als Objekte kapselt
const boxed = Object(secret);
console.log(config[boxed.valueOf()]);

geheim

Automatische Umwandlung wirft trotzdem einen Fehler

const sym = Symbol('x');

try {
  console.log(sym.valueOf() + '');
} catch (err) {
  console.log(err instanceof TypeError, err.message);
}

// Richtig: ausdrücklich umwandeln
console.log(String(sym.valueOf()));

true Cannot convert a Symbol value to a string Symbol(x)

// Wichtig · Fallstricke

Automatische Umwandlung: Wandelt JavaScript ein Symbol automatisch in einen primitiven Wert um, wird Symbol.prototype[Symbol.toPrimitive] aufgerufen, nicht valueOf(). Wer valueOf überschreibt, ändert dieses Verhalten also nicht.
Kein automatisches Umwandeln in Text oder Zahl: sym + '', `${sym}` und +sym werfen einen TypeError. Zum Umwandeln in Text String(sym), sym.toString() oder sym.description verwenden.
Falscher this-Wert: Ruft man die Methode mit einem this auf, das weder ein Symbol noch ein Symbol-Wrapper ist, etwa Symbol.prototype.valueOf.call('abc'), wird ein TypeError geworfen.
Kein new Symbol(): new Symbol() wirft einen TypeError. Ein Wrapper-Objekt entsteht nur über Object(sym).
Kompatibilität: Wird seit ES2015 von allen modernen Browsern und von Node.js unterstützt.

Siehe auch

Symbol Symbol.prototype.toString() Symbol.prototype.description Object.prototype.valueOf() Symbol.prototype[Symbol.toPrimitive]()