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 bekannte Symbol Symbol.toPrimitive. Alle Typumwandlungs- Algorithmen suchen auf Objekten nach diesem Symbol für die Methode, die einen bevorzugten Typ akzeptiert und eine primitive Darstellung des Objekts zurückgibt, bevor zurückgegriffen wird auf die Methoden valueOf() und toString() des Objekts.

Probieren Sie es aus

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

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

Wert

Das bekannte 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, das den bevorzugten Typ des resultierenden primitiven Werts angibt. Das hint-Argument kann eines von "number", "string" und "default" sein.

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

Objekte ohne die [Symbol.toPrimitive]-Eigenschaft werden in primitive Werte umgewandelt, indem die Methoden valueOf() und toString() in verschiedenen Reihenfolgen aufgerufen werden, was ausführlicher im Abschnitt Typumwandlung erklärt wird. [Symbol.toPrimitive]() ermöglicht die volle Kontrolle über den primitiven Umwandlungsprozess. Beispielsweise 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, was bedeutet, dass selbst in String-Kontexten Symbol.prototype.toString() nicht aufgerufen wird und Symbol-Objekte immer explizit in Strings umgewandelt werden müssen durch String().

Beispiele

Modifizieren von primitiven Werten, die aus einem Objekt umgewandelt wurden

Das folgende Beispiel beschreibt, wie die Eigenschaft Symbol.toPrimitive den primitiven Wert, der aus einem Objekt umgewandelt wurde, ä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

BCD tables only load in the browser

Siehe auch