Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Symbol.toPrimitive — conversion personnalisée d’un objet en valeur primitive

Symbol.toPrimitive est un symbole bien connu qui désigne la méthode de conversion d’un objet en valeur primitive. La méthode reçoit l’indication "string", "number" ou "default" et a priorité sur l’utilisation ordinaire de valueOf() et de 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

Syntaxe

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

Symbol.toPrimitive est un symbole utilisé comme clé de méthode, et non une fonction de conversion. Définissez [Symbol.toPrimitive](hint) { ... } pour contrôler la conversion d’un objet en valeur primitive. La méthode est appelée avec l’objet converti comme this.

L’argument hint vaut "string" pour String(obj), "number" pour Number(obj) et "default" lors de l’addition dans obj + 3. L’indication n’impose pas le type du résultat : la méthode doit renvoyer une valeur primitive, que l’opération englobante peut convertir davantage. Renvoyer un objet déclenche TypeError, sans essayer valueOf() ni toString().

Si la propriété vaut undefined ou null, la conversion ordinaire s’applique : avec une indication de chaîne, toString() est essayé avant valueOf() ; avec une indication numérique, l’ordre est inversé. En l’absence d’indication, la conversion ordinaire privilégie le nombre. Toute autre valeur non appelable de la propriété déclenche TypeError.

Dans l’exemple, String(amount) produit Amount(7), Number(amount) produit 7 et amount + 3 produit 10. Traitez délibérément les trois indications pour éviter les résultats surprenants de l’opérateur +.

Exemples

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

Résultat

Amount(7)
7
10

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources