Date.prototype[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 July 2015.

[Symbol.toPrimitive]()Date インスタンスのメソッドで、この日付を表すプリミティブ値を返します。返される値は、指定されたヒントに応じて文字列または数値となります。

試してみましょう

// Depending on timezone, your results will vary
const date = new Date("20 December 2019 14:48");

console.log(date[Symbol.toPrimitive]("string"));
// Expected output: "Fri Dec 20 2019 14:48:00 GMT+0530 (India Standard Time)"

console.log(date[Symbol.toPrimitive]("number"));
// Expected output: 1576833480000

構文

js
date[Symbol.toPrimitive](hint)

引数

hint

文字列で、返すプリミティブ値の型を表します。以下の値が有効です。

  • "string" または "default": このメソッドは文字列を返さなければなりません。
  • "number": このメソッドは数値を返さなければなりません。

返値

hint"string" または "default" の場合、このメソッドは、this 値を文字列に変換して文字列を返します(最初に toString() を、次に valueOf() を試します)。

hint"number" の場合、このメソッドは、this 値を数値に変換して数値を返します(最初に valueOf() を試み、次に toString() を試みます)。

例外

TypeError

hint 引数が有効な値の 3 つのうちのどれでもない場合に発生します。

解説

[Symbol.toPrimitive]() メソッドは、型変換プロトコルの一部です。JavaScript は、オブジェクトをプリミティブ値に変換する際に、常に [Symbol.toPrimitive]() メソッドを優先的に呼び出します。[Symbol.toPrimitive]() メソッドを自分で呼び出す必要があることはほとんどありません。JavaScript は、プリミティブ値が期待されるオブジェクトに遭遇した際に、自動的にこのメソッドを呼び出します。

Date オブジェクトの [Symbol.toPrimitive]() メソッドは、this.valueOf() を呼び出して数値を返すか、または this.toString() を呼び出して文字列を返すことで、プリミティブ値を返します。これは、既定のプリミティブ変換処理を上書きして、数値ではなく文字列を返すために存在します。既定では、プリミティブ変換は valueOf()toString() の前に呼び出します。独自の [Symbol.toPrimitive]() により、new Date(0) + 11(数値)ではなく "Thu Jan 01 1970 09:00:00 GMT+0900 (日本標準時)1"(文字列)を返します。

[Symbol.toPrimitive]() の使用

js
const d = new Date(0); // 1970-01-01T00:00:00.000Z

d[Symbol.toPrimitive]("string"); // "Thu Jan 01 1970 09:00:00 GMT+0900 (日本標準時)"
d[Symbol.toPrimitive]("number"); // 0
d[Symbol.toPrimitive]("default"); // "Thu Jan 01 1970 09:00:00 GMT+0900 (日本標準時)"

仕様書

Specification
ECMAScript® 2025 Language Specification
# sec-date.prototype-%symbol.toprimitive%

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.toPrimitive]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報