Symbol.toPrimitive
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2015.
Symbol.toPrimitive
は静的データプロパティで、ウェルノウンシンボルである Symbol.toPrimitive
を表します。すべての型変換アルゴリズムにおいて、すべての型変換アルゴリズムにおいて、オブジェクト上でこのシンボルを使って、その valueOf()
や toString()
メソッドを使用する前に、望ましい型を受け入れ、オブジェクトのプリミティブ表現を返すメソッドを調べます。
試してみましょう
値
ウェルノウンシンボル Symbol.toPrimitive
です。
Symbol.toPrimitive のプロパティ属性 | |
---|---|
書込可能 | 不可 |
列挙可能 | 不可 |
設定可能 | 不可 |
解説
Symbol.toPrimitive
プロパティにより(関数値として使用することで)、オブジェクトをプリミティブ値に変換することができるようになります。関数は、プリミティブ値の結果として好ましい型を指定する文字列引数の hint
と一緒に呼び出されます。hint
引数は、 "number
", "string
", "default
" のいずれかになります。
"number"
ヒントは、数値変換アルゴリズムで使用されます。"string"
ヒントは、文字列変換アルゴリズムで使用されます。"default"
ヒントは、プリミティブ変換アルゴリズムで使用されます。ヒントは、優先順位の弱いシグナルとしてのみ機能し、実装でそれを無視するのは自由です(Symbol.prototype[Symbol.toPrimitive]()
がそうであるように)。[Symbol.toPrimitive]()
はプリミティブを返さなければなりません。そうでない場合は TypeError
が発生します。
[Symbol.toPrimitive]
プロパティを持たないオブジェクトは、valueOf()
メソッドと toString()
メソッドを異なる順序で呼び出すことでプリミティブに変換されますが、これについては型変換の節で詳しく説明します。[Symbol.toPrimitive]()
では、プリミティブ変換処理を完全に制御できます。例えば、Date.prototype[Symbol.toPrimitive]()
は、"default"
を "string"
であるかのように扱い、 valueOf()
の代わりに toString()
を呼び出します。Symbol.prototype[Symbol.toPrimitive]()
はヒントを無視し、常にシンボルを返します。つまり、文字列コンテキストでも 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"
仕様書
Specification |
---|
ECMAScript Language Specification # sec-symbol.toprimitive |
ブラウザーの互換性
BCD tables only load in the browser