Symbol.toPrimitive
Symbol.toPrimitive 静态数据属性表示 知名 Symbol Symbol.toPrimitive。所有 类型强制转换 算法都会在对象上查找此 Symbol，以获取接受首选类型并返回对象的原始表示形式的方法，然后再回退使用对象的 valueOf() 和 toString() 方法。
试一试
const object = {
[Symbol.toPrimitive](hint) {
if (hint === "number") {
return 42;
}
return null;
},
};
console.log(+object);
// Expected output: 42
值
知名 Symbol Symbol.toPrimitive。
Symbol.toPrimitive 的属性特性 | |
|---|---|
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |
描述
借助 Symbol.toPrimitive 属性（用作函数值），对象可以转换为原始值。该函数以字符串参数 hint 调用，该参数指定结果原始值的首选类型。hint 参数可以是 "number"、"string" 和 "default" 之一。
"number" 提示由 数字强制转换 算法使用。"string" 提示由 字符串强制转换 算法使用。"default" 提示由 原始值强制转换 算法使用。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]() 会忽略提示并始终返回一个 Symbol，这意味着即使在字符串上下文中，也不会调用 Symbol.prototype.toString()，并且 Symbol 对象必须始终通过 String() 显式转换为字符串。
示例
修改从对象转换的原始值
以下示例描述了 Symbol.toPrimitive 属性如何修改从对象转换的原始值。
// An object without Symbol.toPrimitive property.
const obj1 = {};
console.log(+obj1); // NaN
console.log(`${obj1}`); // "[object Object]"
console.log(obj1 + ""); // "[object Object]"
// An object with Symbol.toPrimitive property.
const obj2 = {
[Symbol.toPrimitive](hint) {
if (hint === "number") {
return 10;
}
if (hint === "string") {
return "hello";
}
return true;
},
};
console.log(+obj2); // 10 — hint is "number"
console.log(`${obj2}`); // "hello" — hint is "string"
console.log(obj2 + ""); // "true" — hint is "default"
规范
| 规范 |
|---|
| ECMAScript® 2026 语言规范 # sec-symbol.toprimitive |
浏览器兼容性
加载中…