WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Symbol.toPrimitive — benutzerdefinierte Umwandlung eines Objekts in einen primitiven Wert

Symbol.toPrimitive ist ein bekanntes Symbol, das die Methode zur Umwandlung eines Objekts in einen primitiven Wert kennzeichnet. Die Methode erhält den Hinweis "string", "number" oder "default" und hat Vorrang vor der gewöhnlichen Verwendung von valueOf() und toString().

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

const value = { [Symbol.toPrimitive](hint) { return hint === "string" ? "label" : 10; } };

Symbol.toPrimitive ist ein Symbol, das als Methodenschlüssel verwendet wird, keine Umwandlungsfunktion. Definiere [Symbol.toPrimitive](hint) { ... }, um zu steuern, wie ein Objekt in einen primitiven Wert umgewandelt wird. Die Methode wird mit dem umzuwandelnden Objekt als this aufgerufen.

Das Argument hint ist bei String(obj) "string", bei Number(obj) "number" und bei der Addition in obj + 3 "default". Der Hinweis erzwingt keinen bestimmten Ergebnistyp: Die Methode muss einen primitiven Wert zurückgeben, den die umgebende Operation weiter umwandeln kann. Wird ein Objekt zurückgegeben, wird TypeError ausgelöst, ohne valueOf() oder toString() auszuprobieren.

Wenn die Eigenschaft den Wert undefined oder null hat, gilt die gewöhnliche Umwandlung: Bei einem String-Hinweis wird zuerst toString() und dann valueOf() versucht; bei einem Zahlen-Hinweis ist die Reihenfolge umgekehrt. Ohne Hinweis verwendet die gewöhnliche Umwandlung die Zahlenpräferenz. Jeder andere nicht aufrufbare Eigenschaftswert löst TypeError aus.

Im Beispiel ergibt String(amount) den Wert Amount(7), Number(amount) den Wert 7 und amount + 3 den Wert 10. Behandle alle drei Hinweise bewusst, um überraschende Ergebnisse mit dem Operator + zu vermeiden.

Beispiele

const amount = {
  value: 7,
  [Symbol.toPrimitive](hint) {
    if (hint === "string") return `Amount(${this.value})`;
    return this.value;
  }
};

console.log(String(amount));
console.log(Number(amount));
console.log(amount + 3);

Ergebnis

Amount(7)
7
10

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen