Date - JavaScript

建立一個 JavaScript Date 物件來指向某一個時間點。Date 物件是基於世界標準時間（UTC） 1970 年 1 月 1 日開始的毫秒數值來儲存時間。

語法

new Date();
new Date(value);
new Date(dateString);
new Date(year, month[, day[, hour[, minutes[, seconds[, milliseconds]]]]]);

附註： JavaScript Date 物件只能由以 Date 作為建構子來產生，如果把 Date 作為一般的函數來呼叫（省略掉 new 運算子）將會得到一個字串而非 Date 物件；與其它 JavaScript 物件不同，它並沒有物件實體語法（例如：以中刮號 [ ] 表示陣列的宣告方式）。

參數

附註：當傳入超過一個參數到 Date 建構子，若參數值超過它的合理範圍（例如：傳數值 13 到月份，或傳數值 70 給分鐘），相鄰的參數值將會被調整。例如： new Date(2013, 13, 1) 將等同於 new Date(2014, 1, 1) 都會建立代表 2014-02-01 的物件（注意月份值由 0 開始）。同樣的， new Date(2013, 2, 1, 0, 70) 與 new Date(2013, 2, 1, 1, 10) 一樣會建立代表 2013-03-01T01:10:00 的 Date 物件。

附註：當傳入超過一個參數到 Date 建構子，所指定的參數值會視為本地時間。如果希望指定的值為世界標準時間（UTC），則應使用 new Date(Date.UTC(...)) 語法，傳入一樣格式的參數。

value: 自世界標準時間（UTC） 1970 年 1 月 1 日 00:00:00 開始的毫秒整數（Integer）值（Unix 紀元；但要注意到大多 Unix 時間戳記是以秒而非毫秒為單位）。
dateString: 表示時間日期的字串。這個字串應該要能被 Date.parse() 方法解析（符合 IETF-compliant RFC 2822 timestamps 及 version of ISO8601 格式要求).

附註： 由於各家瀏覽器有所不同且具有差異性，因此非常不鼓勵使用 Date 建構子（或 Date.parse 方法，它們是同等的）來解析時間日期字串。
year: 表示年份的整數。當數值落在 0 到 99 之間，表示 1900 到 1999 之間的年份。參考下面的範例.
month: 表示月份的整數。由 0 開始（一月）到 11 （十二月）。
day: 選用。表示月份中第幾天的整數值。
hour: 選用。表示小時數的整數值。
minute: 選用。表示分鐘數的整數值。
second: 選用。表示秒數的整數值。
millisecond: 選用。表示毫秒數的整數值。

描述

如果沒有傳入任務參數到建構子，會依系統設定建立出代表當下時間的 Date 物件。
如果傳入至少兩個參數，缺少日期的話會設為 1，其它參數則會被設定為 0。
JavaScript 的 date 基於世界標準時間（UTC）1970 年 1 月 1 日午夜的毫秒數。一天有 86,400,000 毫秒。JavaScript Date 物件可表示的範圍由世界標準時間（UTC） 1970 年 1 月 1 日為基準的 -100,000,000 天到 100,000,000 天。
JavaScript Date 物件提供跨平台一致的行為。這個時間數值可以在系統之間傳遞表示相同的時間，如果建立本地的時間物件，其表現將會與本地習慣相對應。
JavaScript Date 物件提供了若干 UTC (通用的) 以及本地時間方法。UTC，也被稱為格林威治標準時間（GMT）被指定作為世界時間的標準。本地時間指的是被設定在執行 JavaScript 電腦上的時間。
以函數方式呼叫 Date （也就是省略 new 建構子）將會回傳一個表示當下時間日期的字串。

屬性

Date.prototype: 允許填加屬於到 JavaScript Date 物件。
Date.length: Date.length 的值為 7。這是建構子能夠處理的參數數量。

方法

Date.now(): 回傳對應於當下時間的數值 - 1970/01/01 00:00:00 (UTC) 到當下的毫秒數。
Date.parse(): 解析字串所表示的時間，回傳由 1970/01/01 00:00:00 (UTC) 到該時間的毫秒數值。

附註：由於瀏覽器之間的不同與差異，強烈不建議使用 Date.parse 。
Date.UTC(): 需要傳入與建構子相同的參數數目（即 2 到 7 個），會得到由 1970-01-01 00:00:00 UTC 到該日期時間的毫秒數。（輸入的參數會視為世界標準時間，而非本地時間）

JavaScript `Date` 物件實體

所有 Date 物件實體繼承自 Date.prototype 。這個 Date 建構子的 prototype 物件可以被修改以影響所有 Date 物件實體。

Date.prototype 方法

Getter

Date.prototype.getDate(): 回傳本地時間月份中的日期（1-31）。
Date.prototype.getDay(): 回傳本地時間星期中的日子（0-6）。
Date.prototype.getFullYear(): 回傳本地時間的年份（以 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(): 回傳由 1970-01-01 00:00:00 UTC 開始，到代表時間經過的毫秒數（以負值表示 1970 年之前的時間）。
Date.prototype.getTimezoneOffset(): 回傳本地時差為多少分鐘。
Date.prototype.getUTCDate(): 回傳標準時間的在月份中的日期（1-31）。
Date.prototype.getUTCDay(): 回傳標準時間在星期中的日子（0-6）。
Date.prototype.getUTCFullYear(): 回傳標準時間的年份（以 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() 取代。

Setter

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 物件距 1970-01-01 00:00:00 UTC 的毫秒數，允許使用負值表示之前的時間。
Date.prototype.setUTCDate(): 設定標準時間月份中的日期。
Date.prototype.setUTCFullYear(): 設定標準時間的完整年份（以 4 位數表示 4 位數年分）。
Date.prototype.setUTCHours(): 設定標準時間的小時數。
Date.prototype.setUTCMilliseconds(): 設定標準時間的毫秒數。
Date.prototype.setUTCMinutes(): 設定標準時間的分鐘數。
Date.prototype.setUTCMonth(): 設定標準時間的月份數。
Date.prototype.setUTCSeconds(): 設定標準時間的秒數。
Date.prototype.setYear(): 設定本地時間的年份（使用 2-3 位數）。使用 setFullYear() 取代。

Conversion getter

Date.prototype.toDateString(): 以可閱讀的字串型式，回傳 Date 的部分資訊。
Date.prototype.toISOString(): 將日期時間轉換成 ISO 8601 格式的字串回傳。
Date.prototype.toJSON(): 回傳等義於 Date 物件使用 toISOString() 方法的結果。特別使用 JSON.stringify() 處理。
Date.prototype.toGMTString(): 回傳 Date 以 GMT (UT) 時區基準代表的時間字串。使用 toUTCString() 方法來取代。
Date.prototype.toLocaleDateString(): 依照系統的時間地區設定，回傳日期字串。
Date.prototype.toLocaleFormat(): 傳入格式化字串參數，將日期時間轉換成指定格式的字串。
Date.prototype.toLocaleString(): 回傳依系統的地區設定導出的日期時間字串。覆寫自 Object.prototype.toLocaleString() 方法。
Date.prototype.toLocaleTimeString(): 回傳依系統的地區設定導出的時間字串。
Date.prototype.toSource(): 回傳一個建立相同 Date 物件的程式碼字串；你可以拿這個結果來建立新物件。覆寫自 Object.prototype.toSource() 方法。
Date.prototype.toString(): 回傳代表此 Date 物件的字串。覆寫自 Object.prototype.toString() 方法。
Date.prototype.toTimeString(): 以人類可讀的格式，回傳時間部分的字串。
Date.prototype.toUTCString(): 依 UTC 時區，轉換出時間日期字串。
Date.prototype.valueOf(): 回傳 Date 物件的原始數值。覆寫自 Object.prototype.valueOf() 方法。

範例

幾種建立 Date 物件的方式

接下來的幾個範例，展示幾種建立 Date 物件的方式：

附註： 由於瀏覽器之間的不同與差異，強烈不建議使用解析字串的方式建立 Date 物件。

var today = new Date();
var birthday = new Date('December 17, 1995 03:24:00');
var birthday = new Date('1995-12-17T03:24:00');
var birthday = new Date(1995, 11, 17);
var birthday = new Date(1995, 11, 17, 3, 24, 0);

兩位數的年份對應到 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)

計算執行時間

下面的例子展示如何使用兩個 Date 物件來求得執行程式所花費毫秒數。

由於日（在夏令時轉換時）、月及年的長度並非固定，如果表示經過時間採用時、分、秒以外的單位，需要對這些差異作深入的研究，以處理可能發生的問題。

// 使用 Date 物件
var start = Date.now();

// 要計算執行時間的程式放在這裡
doSomethingForALongTime();
var end = Date.now();
var elapsed = end - start; // 執行程式經過的毫秒數

// 使用內建方法
var start = new Date();

// 要計算執行時間的程式放在這裡
doSomethingForALongTime();
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // 執行程式經過的毫秒數

// 測試一個函數執行時間，並返回其回傳值
function printElapsedTime(fTest) {
  var nStartTime = Date.now(),
      vReturn = fTest(),
      nEndTime = Date.now();

  console.log('Elapsed time: ' + String(nEndTime - nStartTime) + ' milliseconds');
  return vReturn;
}

yourFunctionReturn = printElapsedTime(yourFunction);

附註：在瀏覽器支援 Web Performance API 高精度特性下， Performance.now() 可以提供比 Date.now() 更可靠、精確的執行時間測試結果。

規範

規範	狀態	註
ECMAScript Latest Draft (ECMA-262) The definition of 'Date' in that specification.	Draft
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Date' in that specification.	Standard
ECMAScript 5.1 (ECMA-262) The definition of 'Date' in that specification.	Standard
ECMAScript 1st Edition (ECMA-262)	Standard	初步定義。實作在 JavaScript 1.1。

瀏覽器相容性

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

Desktop
Mobile

平台	Chrome	Firefox (Gecko)	Internet Explorer	Opera	Safari
基本支援	(Yes) [1]	(Yes) [1]	(Yes) [2]	(Yes) [1]	(Yes) [1]

平台	Android	Chrome for Android	Firefox Mobile (Gecko)	IE Mobile	Opera Mobile	Safari Mobile
基本支援	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)	(Yes)

[1] 一些瀏覽器在解析日期時間會發生問題： 3/14/2012 blog from danvk Comparing FF/IE/Chrome on Parsing Date Strings

[2] ISO8601 Date Format is not supported in Internet Explorer 8, and other version can have issues when parsing dates

最近修改: Mar 23, 2019, 由 MDN 貢獻者

語法

參數

描述

屬性

方法

JavaScript Date 物件實體