Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Symbol.toPrimitive — conversão personalizada de objeto para primitivo

Symbol.toPrimitive é um símbolo conhecido que identifica o método de conversão de um objeto num valor primitivo. O método recebe a indicação "string", "number" ou "default" e tem precedência sobre a utilização habitual de valueOf() e toString().

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

Sintaxe

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

Symbol.toPrimitive é um símbolo utilizado como chave de método, não uma função de conversão. Define [Symbol.toPrimitive](hint) { ... } para controlar a conversão de um objeto num valor primitivo. O método é chamado com o objeto a converter como this.

O argumento hint é "string" para String(obj), "number" para Number(obj) e "default" na adição em obj + 3. A indicação não impõe o tipo do resultado: o método tem de devolver um valor primitivo, que a operação envolvente pode converter novamente. Devolver um objeto lança TypeError, sem tentar valueOf() nem toString().

Se a propriedade tiver o valor undefined ou null, aplica-se a conversão habitual: com uma indicação de cadeia de caracteres, tenta-se primeiro toString() e depois valueOf(); com uma indicação numérica, a ordem é inversa. Sem indicação, a conversão habitual dá preferência ao número. Qualquer outro valor não invocável da propriedade lança TypeError.

No exemplo, String(amount) produz Amount(7), Number(amount) produz 7 e amount + 3 produz 10. Trata deliberadamente as três indicações para evitar resultados inesperados com o operador +.

Exemplos

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

Resultado

Amount(7)
7
10

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes