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 | |
---|---|
Schreibbar | nein |
Aufzählbar | nein |
Konfigurierbar | nein |
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.
// 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 GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
toPrimitive |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support