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 |
瀏覽器相容性
載入中…