Date

JavaScript の Date オブジェクトは、単一の瞬間の時刻をプラットフォームに依存しない形式で表します。 Date オブジェクトは協定世界時 (UTC) の1970年1月1日からの経過ミリ秒数を表現する Number の値を含んでいます。

解説

ECMAScript Epoch とタイムスタンプ

JavaScript の日時は、基本的に協定世界時 (UTC) の1970年1月1日深夜0時からの経過ミリ秒数で指定されます。この日付と時刻は、コンピューターに記録される日付と時刻の値の主な基準値である UNIX Epoch と同じです。

注: Date オブジェクトの中心となる時間値は UTC ですが、日付と時刻、またはその一部を取得する基本的なメソッドは、すべて地方時 (ホストシステムなど) のタイムゾーンとオフセットで動作することを覚えておくことが重要です。

Date の最大値は、確実な整数の最大値 (Number.MAX_SAFE_INTEGER、9,007,199,254,740,991) と同じ値ではないことに注意が必要です。代わりに ECMA-262 では、 UTC の 1970年1月1日から前後 ±100,000,000 (1億) 日 (つまり、紀元前271821年4月20日 - 紀元275760年9月13日) を標準の Date オブジェクトで表すことができると定義しています。

日時形式とタイムゾーンの変換

様々な形式で日時を取得したり、タイムゾーンの変換を行ったりすることができる方法はたくさんあります。特に便利なのは、世界時標準 (World Time Standard) で定義されている世界標準時である協定世界時 (UTC) で日付と時刻を出力する関数です。 (この時間は歴史的にグリニッジ標準時として知られており、 UTC はイギリスのロンドンとその近くのグリニッジを含む子午線に沿って位置しています。) ユーザーの端末は現地時間を提供します。

地方時の日付と時刻の個々の部分を読み書きするメソッド (getDay() や setHours() など) に加えて、 UTC を使用して日付と時刻を読み書きする同等のメソッド (getUTCDay() や setUTCHours() など) もあります。

コンストラクター

Date(): 新たな Date オブジェクトを生成します。

静的メソッド

Date.now(): 現在の時刻に対応する数値、すなわち UTC の 1970 年 1 月 1 日 00:00:00 から経過したミリ秒 (閏秒は無視) を表す数値を返します。
Date.parse(): JavaScript で日付を表す文字列を解釈して、地方時で 1970 年 1 月 1 日 00:00:00 から経過したミリ秒 (閏秒は無視) を表す数値を返します。

注: ブラウザーごとに動作が異なり一貫性がないため、 Date.parse で文字列を解釈しないように強くすすめます。
Date.UTC(): コンストラクターですべての引数を与えて呼び出したのと同じように、 UTC の 1970 年 1 月 1 日 00:00:00 から経過したミリ秒数 (閏秒は無視) を返します。

インスタンスメソッド

Date.prototype.getDate(): 地方時に基づき、指定された日時の「日」 (1–31) を返します。
Date.prototype.getDay(): 地方時に基づき、指定された日時の「曜日」 (0–6) を返します。
Date.prototype.getFullYear(): 地方時に基づき、指定された日時の「年」 (4桁の年であれば4桁) を返します。
Date.prototype.getHours(): 地方時に基づき、指定された日時の「時」 (0–23) を返します。
Date.prototype.getMilliseconds(): 地方時に基づき、指定された日時の「ミリ秒」 (0–999) を返します。
Date.prototype.getMinutes(): 地方時に基づき、指定された日時の「分」 (0–59) を返します。
Date.prototype.getMonth(): 地方時に基づき、指定された日時の「月」 (0–11) を返します。
Date.prototype.getSeconds(): 地方時に基づき、指定された日時の「秒」 (0–59) を返します。
Date.prototype.getTime(): 指定された日時を協定世界時 (UTC) の 1970 年 1 月 1 日 00:00:00 からの経過ミリ秒単位の数値で返します。 (それ以前の時刻では負の数を返します。)
Date.prototype.getTimezoneOffset(): 現地の時間帯のオフセットを分で返します。
Date.prototype.getUTCDate(): 協定世界時に基づき、指定された日時の「日」 (1–31) を返します。
Date.prototype.getUTCDay(): 協定世界時に基づき、指定された日時の「曜日」 (0–6) を返します。
Date.prototype.getUTCFullYear(): 協定世界時に基づき、指定された日時の「年」 (4桁の年であれば4桁) を返します。
Date.prototype.getUTCHours(): 協定世界時に基づき、指定された日時の「時」 (0–23) を返します。
Date.prototype.getUTCMilliseconds(): 協定世界時に基づき、指定された日時の「ミリ秒」 (0–999) を返します。
Date.prototype.getUTCMinutes(): 協定世界時に基づき、指定された日時の「分」 (0–59) を返します。
Date.prototype.getUTCMonth(): 協定世界時に基づき、指定された日時の「月」 (0–11) を返します。
Date.prototype.getUTCSeconds(): 協定世界時に基づき、指定された日時の「秒」 (0–59) を返します。
Date.prototype.getYear(): 地方時に基づき、指定された日時の「年」 (ふつうは2–3桁) を返します。代わりに getFullYear() を使用してください。
Date.prototype.setDate(): 地方時に基づき、指定された日時の「日」を設定します。
Date.prototype.setFullYear(): 地方時に基づき、指定された日時の「年」を完全な形 (例えば、4桁の年であれば4桁) で設定します。
Date.prototype.setHours(): 地方時に基づき、指定された日時の「時」を設定します。
Date.prototype.setMilliseconds(): 地方時に基づき、指定された日時の「ミリ秒」を設定します。
Date.prototype.setMinutes(): 地方時に基づき、指定された日時の「分」を設定します。
Date.prototype.setMonth(): 地方時に基づき、指定された日時の「月」を設定します。
Date.prototype.setSeconds(): 地方時に基づき、指定された日時の「秒」を設定します。
Date.prototype.setTime(): Date オブジェクトを協定世界時(UTC) の 1970 年 1 月 1 日 00:00:00 からのミリ秒単位の数で表された時刻に設定します。
Date.prototype.setUTCDate(): 協定世界時に基づき、指定された日時の「日」を設定します。
Date.prototype.setUTCFullYear(): 協定世界時に基づき、指定された日時の「年」を完全な形で設定します。
Date.prototype.setUTCHours(): 協定世界時に基づき、指定された日時の「時」を設定します。
Date.prototype.setUTCMilliseconds(): 協定世界時に基づき、指定された日時の「ミリ秒」を設定します。
Date.prototype.setUTCMinutes(): 協定世界時に基づき、指定された日時の「分」を設定します。
Date.prototype.setUTCMonth(): 協定世界時に基づき、指定された日時の「月」を設定します。
Date.prototype.setUTCSeconds(): 協定世界時に基づき、指定された日時の「秒」を設定します。
Date.prototype.setYear(): 協定地方時に基づき、指定された日時の「年」 (ふつうは2–3桁) を設定します。代わりに setFullYear() を使用してください。
Date.prototype.toDateString(): Date の「日付」部を、 'Thu Apr 12 2018' のように人間が読みやすい形式の文字列にして返します。
Date.prototype.toISOString(): 日付を ISO 8601 Extended Format に準じた文字列に変換します。
Date.prototype.toJSON(): toISOString() を使用して Date を表す文字列を返します。JSON.stringify() の代わりに使用してください。
Date.prototype.toGMTString(): GMT (UTC) タイムゾーンを基準にした Date を表す文字列を返します。代わりに toUTCString() を使用してください。
Date.prototype.toLocaleDateString(): システム設定の日時の「日付」部を、地域の日付書式に従った文字列に変換して返します。
Date.prototype.toLocaleFormat(): 書式化された文字列を使って、日時を文字列に変換します。
Date.prototype.toLocaleString(): 日付を地域の日付書式に従った文字列に変換して返します。Object.prototype.toLocaleString() メソッドを上書きします。
Date.prototype.toLocaleTimeString(): システム設定の日時の「時刻」部を、地域の日付書式に従った文字列に変換して返します。
Date.prototype.toString(): 指定された Date オブジェクトを表す文字列を返します。 Object.prototype.toString() メソッドを上書きします。
Date.prototype.toTimeString(): Date の「時刻」部を人間が読みやすい形式の文字列にして返します。
Date.prototype.toUTCString(): 日時を UTC タイムゾーンを使用する文字列に変換します。
Date.prototype.valueOf(): Date オブジェクトのプリミティブ値を返します。Object.prototype.valueOf() メソッドを上書きします。

例

Date オブジェクトを生成するいくつかの方法

以下の例で、 JavaScript の日時を生成するいくつかの方法を示します。

注: Date コンストラクター (または同等の Date.parse) で日付文字列を解釈することは、ブラウザーごとに動作が異なり一貫性がないため、避けるように強くすすめます。

let today = new Date()
let birthday = new Date('December 17, 1995 03:24:00')
let birthday = new Date('1995-12-17T03:24:00')
let birthday = new Date(1995, 11, 17)            // 月は 0 起点
let birthday = new Date(1995, 11, 17, 3, 24, 0)

2桁の年は1900–1999年に対応付けられる

西暦 0 年から 99 年までの間の年を生成および取得するには、Date.prototype.setFullYear() メソッドと Date.prototype.getFullYear() メソッドを使用してください。

var date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

// 非推奨のメソッド。この 98 は1998年に対応付けられます。
date.setYear(98)            // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98)        // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)

経過時間の計算

以下の例で、2 つの JavaScript の日付の間で経過した時間を計る方法を示します。

日 (サマータイム切り替えによる)、月、年の長さが異なるため、経過時間を時、分、秒以上の単位で表現するには、いくつかの問題に対処する必要がありますので、事前によく調べて使用してください。

// Date オブジェクトを使用
let start = Date.now()

// 時間を計りたいイベントをここに置く:
doSomethingForALongTime()
let end = Date.now()
var elapsed = end - start // ミリ秒単位の経過時間

// 組み込みメソッドを使用
var start = new Date()

// 時間を計りたいイベントをここに置く
doSomethingForALongTime()
let end = new Date()
let elapsed = end.getTime() - start.getTime() // ミリ秒単位の経過時間

// 関数をテストして戻り値を取得する
function printElapsedTime(fTest) {
  let nStartTime = Date.now(),
      vReturn = fTest(),
      nEndTime = Date.now()

  console.log(`Elapsed time: ${ String(nEndTime - nStartTime) } milliseconds`)
  return vReturn
}

let yourFunctionReturn = printElapsedTime(yourFunction)

注: Web Performance API の高精度時刻機能に対応しているブラウザーでは、 Performance.now() で、 Date.now() よりも高信頼かつ高精度な経過時間の測定が可能です。

ECMAScript Epoch からの経過秒数を取得する

let seconds = Math.floor(Date.now() / 1000)

この場合、整数だけを返すことが重要です (単純な除算ではできません)。また、実際に経過した秒数を返すことも重要です (ですから、上の例では Math.round() ではなく Math.floor() を使っています)。

仕様書

仕様書
ECMAScript (ECMA-262) Date の定義

ブラウザーの互換性

BCD tables only load in the browser