Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Symbol.toPrimitive — conversione personalizzata da oggetto a primitivo

Symbol.toPrimitive è un simbolo noto che identifica il metodo di conversione di un oggetto in un valore primitivo. Il metodo riceve l’indicazione "string", "number" o "default" e ha la precedenza sull’uso ordinario di valueOf() e toString().

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

Sintassi

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

Symbol.toPrimitive è un simbolo usato come chiave di un metodo, non una funzione di conversione. Definisci [Symbol.toPrimitive](hint) { ... } per controllare la conversione di un oggetto in un valore primitivo. Il metodo viene chiamato con l’oggetto da convertire come this.

L’argomento hint è "string" per String(obj), "number" per Number(obj) e "default" per l’addizione in obj + 3. L’indicazione non impone il tipo del risultato: il metodo deve restituire un valore primitivo, che l’operazione circostante può convertire ulteriormente. Restituire un oggetto genera TypeError, senza provare valueOf() o toString().

Se la proprietà vale undefined o null, si applica la conversione ordinaria: con un’indicazione di stringa si prova prima toString() e poi valueOf(); con un’indicazione numerica l’ordine è inverso. In assenza di indicazioni, la conversione ordinaria privilegia il numero. Qualsiasi altro valore non richiamabile della proprietà genera TypeError.

Nell’esempio, String(amount) produce Amount(7), Number(amount) produce 7 e amount + 3 produce 10. Gestisci consapevolmente tutte e tre le indicazioni per evitare risultati sorprendenti con l’operatore +.

Esempi

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);

Risultato

Amount(7)
7
10

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti