MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-dev-survey

建立一個  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 timestampsversion 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 2017 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。

瀏覽器相容性

平台 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

文件標籤與貢獻者

標籤: 
 此頁面的貢獻者: ddtet
 最近更新: ddtet,