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 April 2017.
Symbol.toPrimitive 是内置的 symbol 属性，其指定了一种接受首选类型并返回对象原始值的表示的方法。它被所有的强类型转换制算法优先调用。
尝试一下
const object1 = {
[Symbol.toPrimitive](hint) {
if (hint === "number") {
return 42;
}
return null;
},
};
console.log(+object1);
// Expected output: 42
Symbol.toPrimitive 的属性特性 | |
|---|---|
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |
描述
在 Symbol.toPrimitive 属性（用作函数值）的帮助下，对象可以转换为一个原始值。该函数被调用时，会被传递一个字符串参数 hint，表示要转换到的原始值的预期类型。hint 参数的取值是 "number"、"string" 和 "default" 中的任意一个。
"number" hint 用于强制数字类型转换算法。"string" hint 用于强制字符串类型转换算法。"default" hint 用于强制原始值转换算法。hint 仅是作为首选项的偏弱的信号提示，实现时，可以自由忽略它（就像 Symbol.prototype[Symbol.toPrimitive]() 一样）。该语言不会在 hint 和结果类型之间强制校正，尽管 [Symbol.toPrimitive]() 必须返回一个原始值，否则将抛出 TypeError。
没有 Symbol.toPrimitive 属性的对象通过以不同的顺序调用 valueOf() 和 toString() 方法将其转换为原始值，这在强制类型转换部分进行了更详细的解释。Symbol.toPrimitive 允许完全控制原始转换过程。例如，Date.prototype[Symbol.toPrimitive] 将 "default" 视为 "string" 并且调用 toString() 而不是 valueOf()。Symbol.prototype[Symbol.toPrimitive] 忽略 hint，并总是返回一个 symbol，这意味着即使在字符串上下文中，也不会调用 Symbol.prototype.toString()，并且 Symbol 对象必须始终通过 String() 显式转换为字符串。
示例
修改从对象转换的原始值
以下示例描述了 Symbol.toPrimitive 属性如何修改从对象转换的原始值。
// 一个没有提供 Symbol.toPrimitive 属性的对象，参与运算时的输出结果。
const obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"
// 接下面声明一个对象，手动赋予了 Symbol.toPrimitive 属性，再来查看输出结果。
const obj2 = {
[Symbol.toPrimitive](hint) {
if (hint === "number") {
return 10;
}
if (hint === "string") {
return "hello";
}
return true;
},
};
console.log(+obj2); // 10 — hint 参数值是 "number"
console.log(`${obj2}`); // "hello" — hint 参数值是 "string"
console.log(obj2 + ""); // "true" — hint 参数值是 "default"
规范
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-symbol.toprimitive |