Symbol.toPrimitive

¥Value

众所周知的符号 @@toPrimitive。

¥The well-known symbol @@toPrimitive.

¥Description

借助 Symbol.toPrimitive 属性（用作函数值），可以将对象转换为原始值。使用字符串参数 hint 调用该函数，该参数指定结果原始值的首选类型。hint 参数可以是 "number"、"string" 和 "default" 之一。

¥With the help of the Symbol.toPrimitive property (used as a function value), an object can be converted to a primitive value. The function is called with a string argument hint, which specifies the preferred type of the result primitive value. The hint argument can be one of "number", "string", and "default".

"number" 提示由 数字强制 算法使用。"string" 提示由 字符串强制 算法使用。"default" 提示由 原始强制 算法使用。hint 仅充当微弱的偏好信号，并且实现可以自由地忽略它（就像 Symbol.prototype[@@toPrimitive]() 一样）。该语言不强制 hint 和结果类型之间的对齐，尽管 [@@toPrimitive]() 必须返回原语，否则会抛出 TypeError。

¥The "number" hint is used by numeric coercion algorithms. The "string" hint is used by the string coercion algorithm. The "default" hint is used by the primitive coercion algorithm. The hint only acts as a weak signal of preference, and the implementation is free to ignore it (as Symbol.prototype[@@toPrimitive]() does). The language does not enforce alignment between the hint and the result type, although [@@toPrimitive]() must return a primitive, or a TypeError is thrown.

没有 @@toPrimitive 属性的对象通过以不同顺序调用 valueOf() 和 toString() 方法来转换为基元，这在 类型强制 部分中有更详细的解释。@@toPrimitive 允许完全控制原始转换过程。例如，Date.prototype[@@toPrimitive] 将 "default" 视为 "string"，并调用 toString() 而不是 valueOf()。Symbol.prototype[@@toPrimitive] 忽略提示并始终返回一个符号，这意味着即使在字符串上下文中，也不会调用 Symbol.prototype.toString()，并且 Symbol 对象必须始终通过 String() 显式转换为字符串。

¥Objects without the @@toPrimitive property are converted to primitives by calling the valueOf() and toString() methods in different orders, which is explained in more detail in the type coercion section. @@toPrimitive allows full control over the primitive conversion process. For example, Date.prototype[@@toPrimitive] treats "default" as if it's "string" and calls toString() instead of valueOf(). Symbol.prototype[@@toPrimitive] ignores the hint and always returns a symbol, which means even in string contexts, Symbol.prototype.toString() won't be called, and Symbol objects must always be explicitly converted to strings through String().

¥Examples

¥Modifying primitive values converted from an object

以下示例描述了 Symbol.toPrimitive 属性如何修改从对象转换而来的原始值。

¥Following example describes how Symbol.toPrimitive property can modify the primitive value converted from an object.

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

¥See also

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