Symbol.toPrimitive

尝试一下

const object1 = {
  [Symbol.toPrimitive](hint) {
    if (hint === "number") {
      return 42;
    }
    return null;
  },
};

console.log(+object1);
// Expected output: 42

描述

在 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"

规范

浏览器兼容性

参见

• core-js 中 Symbol.toPrimitive 的 polyfill
• Date.prototype[Symbol.toPrimitive]()
• Symbol.prototype[Symbol.toPrimitive]()
• Object.prototype.toString()
• Object.prototype.valueOf()