Symbol.toPrimitive

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.

Die statische Dateneigenschaft Symbol.toPrimitive repräsentiert das wohlbekannte Symbol Symbol.toPrimitive. Alle Typumwandlungs- Algorithmen suchen dieses Symbol in Objekten, um die Methode zu finden, die einen bevorzugten Typ akzeptiert und eine primitive Darstellung des Objekts zurückgibt, bevor auf die Methoden valueOf() und toString() des Objekts zurückgegriffen wird.

Probieren Sie es aus

const object1 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 42;
    }
    return null;
  },
};

console.log(+object1);
// Expected output: 42

Wert

Das wohlbekannte Symbol Symbol.toPrimitive.

Eigenschaften von Symbol.toPrimitive
Schreibbarnein
Aufzählbarnein
Konfigurierbarnein

Beschreibung

Mit Hilfe der Eigenschaft Symbol.toPrimitive (verwendet als Funktionswert) kann ein Objekt in einen primitiven Wert umgewandelt werden. Die Funktion wird mit einem String-Argument hint aufgerufen, der den bevorzugten Typ des resultierenden primitiven Wertes angibt. Das Argument hint kann einer der Werte "number", "string" oder "default" sein.

Der "number"-Hinweis wird von numerischen Umwandlungs- Algorithmen verwendet. Der "string"-Hinweis wird vom String-Umwandlungs- Algorithmus genutzt. Der "default"-Hinweis wird vom primitiven Umwandlungs- Algorithmus genutzt. Der hint fungiert nur als schwaches Signal der Präferenz, und die Implementierung kann ihn ignorieren (wie beispielsweise Symbol.prototype[Symbol.toPrimitive]()). Die Sprache erzwingt keine Übereinstimmung zwischen dem hint und dem Resultat-Typ, obwohl [Symbol.toPrimitive]() einen primitiven Wert zurückgeben muss, andernfalls wird ein TypeError ausgelöst.

Objekte ohne die [Symbol.toPrimitive]-Eigenschaft werden in primitive Werte umgewandelt, indem die Methoden valueOf() und toString() in unterschiedlicher Reihenfolge aufgerufen werden. Dies wird detailliert im Abschnitt Typumwandlung erklärt. [Symbol.toPrimitive]() ermöglicht eine vollständige Kontrolle über den Umwandlungsprozess in primitive Werte. Zum Beispiel behandelt Date.prototype[Symbol.toPrimitive]() "default" so, als wäre es "string", und ruft toString() anstelle von valueOf() auf. Symbol.prototype[Symbol.toPrimitive]() ignoriert den Hinweis und gibt immer ein Symbol zurück. Das bedeutet, dass auch in String-Kontexten Symbol.prototype.toString() nicht aufgerufen wird, und Symbol-Objekte immer explizit durch String() in Strings konvertiert werden müssen.

Beispiele

Ändern von primitiven Werten, die aus einem Objekt umgewandelt werden

Das folgende Beispiel beschreibt, wie die Symbol.toPrimitive-Eigenschaft den aus einem Objekt umgewandelten primitiven Wert ändern kann.

js
// An object without Symbol.toPrimitive property.
const obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"

// An object with Symbol.toPrimitive property.
const obj2 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 10;
    }
    if (hint === "string") {
      return "hello";
    }
    return true;
  },
};
console.log(+obj2); // 10        — hint is "number"
console.log(`${obj2}`); // "hello"   — hint is "string"
console.log(obj2 + ""); // "true"    — hint is "default"

Spezifikationen

Specification
ECMAScript® 2025 Language Specification
# sec-symbol.toprimitive

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
toPrimitive

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

Siehe auch