JavaScript 的 Symbol.toPrimitive 怎么使用

Symbol.toPrimitive 是用于自定义对象转原始值行为的内置 Symbol，当对象参与类型转换（如 +、==、String()、Number()）时触发，需定义为接收 hint 参数并返回原始值的函数。

Symbol.toPrimitive 是一个内置的 Symbol 值，用于指定对象在需要转为原始值（如字符串、数字或布尔值）时，应该调用哪个方法来完成转换。它让开发者能自定义对象参与类型转换的行为，比如出现在 +、==、String()、Number() 等上下文中时的表现。

什么时候会触发 Symbol.toPrimitive

当 JavaScript 引擎需要把一个对象转成原始类型时，会按顺序尝试以下步骤：

• 先检查对象是否有 [Symbol.toPrimitive](hint) 方法；
• 如果有，就调用它，并传入 hint 参数（值为 "string"、"number" 或 "default"）；
• 如果没有该方法，才退回到 toString() 和 valueOf() 的老规则。

常见触发场景包括：obj + ""、Number(obj)、String(obj)、obj == 123、console.log(obj)（隐式转字符串）等。

如何定义 Symbol.toPrimitive 方法

给对象设置 [Symbol.toPrimitive] 属性，它必须是一个函数，接收一个 hint 字符串参数，并返回一个原始值（否则会报错）。

立即学习“Java免费学习笔记（深入）”；

例如，定义一个表示温度的对象，让它在不同上下文中返回不同含义的原始值：

const temp = {
  celsius: 25,
  [Symbol.toPrimitive](hint) {
    switch (hint) {
      case 'string':
        return `${this.celsius}°C`;
      case 'number':
        return this.celsius;
      case 'default':
        return this.celsius; // 或返回更合适的默认值，比如带单位的字符串
      default:
        return this.celsius;
    }
  }
};
<p>console.log(String(temp)); // "25°C"
console.log(Number(temp)); // 25
console.log(temp + "");    // "25°C"（hint 是 "default"，但 + "" 实际倾向 string）
console.log(temp == 25);   // true（hint 是 "default"，返回 25，与 25 比较）

hint 参数的实际取值逻辑

hint 并不总是严格对应操作，而是由引擎根据上下文“建议”一个转换倾向：

• "string"：明确要求字符串，如 String(obj)、obj.toString() 被间接调用时（如模板字符串 `${obj}`）；
• "number"：明确要求数字，如 Number(obj)、+obj、obj - 1；
• "default"：模糊上下文，如 obj == 123、obj + 1（若另一操作数不是字符串）、console.log(obj)（部分环境）。

注意：== 和加法 + 在涉及对象时，规范中对 hint 的指定有细节差异，实践中以实际运行结果为准，不要过度依赖 "default" 的行为。

注意事项和常见陷阱

使用 Symbol.toPrimitive 时需留意几点：

• 返回值必须是原始类型（string / number / boolean / null / undefined / symbol），返回对象会抛出 TypeError；
• 不能用箭头函数定义，因为需要访问 this；
• 如果没定义该方法，JS 会回退到 toString() → valueOf() 链（或反过来，取决于 hint），所以仍要确保这两个方法合理；
• 它不会影响 === 或 Object.is()，这些是严格相等比较，不触发类型转换。