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 ⁨2017年4月⁩.

Symbol.toPrimitive は静的データプロパティで、ウェルノウンシンボルのSymbol.toPrimitive を表します。すべての型変換アルゴリズムにおいて、オブジェクト上でこのシンボルを使って、そのvalueOf() やtoString() メソッドを使用する前に、望ましい型を受け入れ、オブジェクトのプリミティブ表現を返すメソッドを調べます。

試してみましょう

const object = {  [Symbol.toPrimitive](hint) {    if (hint === "number") {      return 42;    }    return null;  },};console.log(+object);// 予想される結果: 42

値

ウェルノウンシンボル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); // NaNconsole.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"