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 プロパティがオブジェクトから変換されたプリミティブ値を修正する方法を説明します。

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