【Node.js24.x】Date::setTime()メソッドの使い方
setTimeメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
setTimeメソッドは、Dateオブジェクトの時刻を指定したミリ秒値に設定するメソッドです。このメソッドは、1970年1月1日0時0分0秒UTC（協定世界時）からの経過ミリ秒数、いわゆるUNIXタイムスタンプを用いて、Dateオブジェクトが内部で保持する日時情報を変更します。
引数には、設定したい時刻をミリ秒単位の数値で指定します。例えば、new Date().setTime(1678886400000) のように呼び出すことで、既存のDateオブジェクトが表す日時を、指定されたタイムスタンプに対応する日時に変更できます。このメソッドを呼び出すと、対象のDateオブジェクト自体の値が直接変更されます。また、setTimeメソッドは、設定後のDateオブジェクトが保持するミリ秒数を数値として返します。
主に、特定の日時をミリ秒値で直接指定してDateオブジェクトを初期化したり、既に存在するDateオブジェクトの時刻を別のタイムスタンプに基づいて更新したりする場合に利用されます。特に、異なる日時を効率的に比較したり、過去や未来の特定時点へ移動させたりする際に有用です。
引数に有効な数値以外の値（例えば、nullやundefined、または数値に変換できない文字列など）を渡すと、Dateオブジェクトは「無効な日付」（Invalid Date）の状態となり、その内部時刻はNaN（Not-a-Number）として扱われますので、引数の型と値には注意が必要です。このように、setTimeメソッドは、Dateオブジェクトの時刻をミリ秒単位で効率的かつ直接的に制御したい場合に非常に便利な機能を提供します。
構文(syntax)
1const dateObject = new Date(); 2dateObject.setTime(1678886400000);
引数(parameters)
timeValue
- timeValue: number: Unixエポック（1970年1月1日 00:00:00 UTC）からの経過ミリ秒数
戻り値(return)
number
Dateオブジェクトの時刻をミリ秒単位で設定します。設定後の時刻をエポックからのミリ秒数（数値）で返します。