Date 是 JavaScript 內建的資料型別,負責提供日期與時間的操作介面。它沿用了早期 Java 中 java.util.Date 的設計思路,以「自 UTC 1970 年 1 月 1 日 0 點起經過的毫秒數」來保存時間,可表達的範圍相當寬廣。以下完整梳理它的用法。
先看靜態方法,因為它與建構函式有著密切關聯——用建構函式建立 Date 物件的過程,幾乎就是「披著外套的靜態方法」。Date 共有三個靜態方法:Date.now()、Date.parse()、Date.UTC(),都由建構函式本身呼叫,而非透過實例。
ECMAScript 5 新增,回傳當前時刻距 1970-01-01T00:00Z 的毫秒數,不接受參數,回傳型別為 Number。
console.log(Date.now()); // 1468297046050
console.log(Date.now('2016,1,1')); // 1468297046050(參數被忽略)
console.log(typeof Date.now()); // 'number'
在不支援此方法的舊環境中,可以用一元 + 把 Date 物件轉成數字來達到同樣效果:
console.log(new Date()); // Tue Jul 12 2016 12:21:33 GMT+0800 (中國標準時間) console.log(+new Date()); // 1468297293433 console.log(+new Date(2000, 1, 1)); // 949334400000
最典型的用途是計算一段程式碼的耗時:
var start = Date.now(); doSomething(); var stop = Date.now(); result = stop - start;
解析一個日期字串,回傳自 1970-01-01T00:00Z 到該日期的毫秒數。它依日期時間字串格式規則解析,除標準格式外也支援以下寫法;若無法辨識則回傳 NaN。
'月/日/年',例如 6/13/2004'月 日,年',例如 January 12,2004 或 Jan 12,2004'星期 月 日 年 時:分:秒 時區',例如 Tue May 25 2004 00:00:00 GMT-0700注意:瀏覽器不支援只有時間沒有日期的字串格式。
console.log(Date.parse('6/13/2004')); // 1087056000000
console.log(Date.parse('January 12,2004')); // 1073836800000
console.log(Date.parse('Tue May 25 2004 00:00:00 GMT-0700')); // 1085468400000
console.log(Date.parse('2004-05-25T00:00:00')); // 1085443200000
console.log(Date.parse('2016')); // 1451606400000
console.log(Date.parse('T00:00:00')); // NaN
console.log(Date.parse()); // NaN
另一個容易忽略的規則:在 ECMAScript 5 中,若標準格式的字串有前置 0,會被解析為 UTC 時間;沒有前置 0 則解析為本地時間。其他情況一般也視為本地時間。
console.log(Date.parse('7/12/2016')); // 1468252800000
console.log(Date.parse('2016-7-12')); // 1468252800000
console.log(Date.parse('2016-07-12')); // 1468281600000
三個寫法只差了一個 0,結果卻相差 8 小時——這是時區相關 bug 的常見來源。
同樣回傳毫秒數,但參數是分別代表年、月、日、時、分、秒、毫秒的數字:
Date.UTC(year, month, day, hours, minutes, seconds, ms)
其中 year 與 month 為必要參數,其餘可選。由於有 7 個形參,length 值為 7:
console.log(Date.UTC.length); // 7
注意此方法使用的是 UTC 時間,而非本地時間。
console.log(Date.UTC(1970)); // NaN console.log(Date.UTC(1970, 0)); // 0 console.log(Date.UTC(1970, 0, 2)); // 86400000 console.log(Date.UTC(1970, 0, 1, 1)); // 3600000 console.log(Date.UTC(1970, 0, 1, 1, 59)); // 714000 console.log(Date.UTC(1970, 0, 1, 1, 59, 30));// 717000
可以不加 new,像普通函式一樣呼叫。它會忽略所有傳入參數,回傳當前日期時間的字串表示。
console.log(Date()); // "Tue Jul 12 2016 13:38:41 GMT+0800 (中國標準時間)"
console.log(Date('2016/1/1')); // "Tue Jul 12 2016 13:38:41 GMT+0800 (中國標準時間)"
console.log(typeof Date()); // 'string'
嚴格說,因為沒有使用 new,這種呼叫形式並不算是建立物件。
不帶參數時,依當前時間建立物件。
console.log(new Date()); // Tue Jul 12 2016 13:41:45 GMT+0800 (中國標準時間) console.log(new Date); // 同上(省略括號亦可) console.log(typeof new Date()); // 'object'
傳入一個數字,代表距 1970-01-01T00:00Z 的毫秒數。
console.log(new Date(0)); // Thu Jan 01 1970 08:00:00 GMT+0800 (中國標準時間) console.log(new Date(86400000)); // Fri Jan 02 1970 08:00:00 GMT+0800 (中國標準時間)
傳入字串,格式規則近似 Date.parse()。差別在於 parse() 回傳數字,而此用法回傳物件。
console.log(new Date('6/13/2004')); // Sun Jun 13 2004 00:00:00 GMT+0800 (中國標準時間)
console.log(Date.parse('6/13/2004')); // 1087056000000
console.log(typeof new Date('6/13/2004')); // 'object'
console.log(typeof Date.parse('6/13/2004')); // 'number'
前置 0 的處理規則同 Date.parse():
console.log(new Date('7/12/2016')); // Tue Jul 12 2016 00:00:00 GMT+0800
console.log(new Date('2016-7-12')); // Tue Jul 12 2016 00:00:00 GMT+0800
console.log(new Date('2016-07-12')); // Tue Jul 12 2016 08:00:00 GMT+0800
參數形式近似 Date.UTC(),但結果是本地時間的物件,而非 UTC 的毫秒數。
console.log(new Date(2016, 7, 12)); // Fri Aug 12 2016 00:00:00 GMT+0800 console.log(+new Date(2016, 7, 12)); // 1470931200000 console.log(Date.UTC(2016, 7, 12)); // 1470960000000
一個實用差異:使用類似 Date.parse() 的字串參數時,若日期超出範圍,瀏覽器會自動把日期滾動到範圍內的有效值;使用類似 Date.UTC() 的數字參數時,超出範圍會得到 Invalid Date。
console.log(new Date(2016, 7, 32)); // Thu Sep 01 2016 00:00:00 GMT+0800(自動滾動)
console.log(new Date(2016, 8, 1)); // Thu Sep 01 2016 00:00:00 GMT+0800
console.log(new Date('2016-8-32'));// Invalid Date
console.log(new Date('2016-9-1')); // Thu Sep 01 2016 00:00:00 GMT+0800
Date 物件沒有可直接讀寫的屬性,所有存取都必須透過方法。多數方法都有兩種形式:使用本地時間與使用 UTC 時間,以下以 get[UTC]Day() 同時代表 getDay() 與 getUTCDay()。總計 46 個實例方法,可分為 to 類、get 類、set 類。
toString():本地時區的日期時間字串。toUTCString():UTC 時間的字串。toISOString():標準日期時間格式字串。toDateString():日期部分。toTimeString():時間部分。toJSON():符合 JSON 格式的字串,結果與 toISOString() 相同。console.log(new Date('2016-7-12').toString()); // Tue Jul 12 2016 00:00:00 GMT+0800 (中國標準時間)
console.log(new Date('2016-7-12').toUTCString()); // Mon, 11 Jul 2016 16:00:00 GMT
console.log(new Date('2016-7-12').toISOString()); // 2016-07-11T16:00:00.000Z
console.log(new Date('2016-7-12').toDateString()); // Tue Jul 12 2016
console.log(new Date('2016-7-12').toTimeString()); // 00:00:00 GMT+0800 (中國標準時間)
console.log(new Date('2016-7-12').toJSON()); // 2016-07-11T16:00:00.000Z
另有三個本地化版本:toLocaleString()、toLocaleTimeString()、toLocaleDateString(),分別是 toString()、toTimeString()、toDateString() 的在地化輸出。
console.log(new Date('2016-7-12').toString()); // Tue Jul 12 2016 00:00:00 GMT+0800
console.log(new Date('2016-7-12').toLocaleString()); // 2016/7/12 上午12:00:00
console.log(new Date('2016-7-12').toDateString()); // Tue Jul 12 2016
console.log(new Date('2016-7-12').toLocaleDateString());// 2016/7/12
console.log(new Date('2016-7-12').toTimeString()); // 00:00:00 GMT+0800
console.log(new Date('2016-7-12').toLocaleTimeString());// 上午12:00:00
注意輸出格式會隨瀏覽器與系統地區設定而異,因此若要顯示給使用者,toLocale* 系列較合適;若要給程式處理或做為資料傳輸,toISOString() 才是可靠選擇。
先說明 valueOf():它回傳距 1970-01-01T00:00Z 的毫秒數,因此可以直接用比較運算子比大小的日期。
var date1 = new Date(2007, 0, 1); var date2 = new Date(2007, 1, 1); console.log(date1 > date2); // false console.log(date1 < date2); // true
getTime() 同樣回傳毫秒數,效果等同 valueOf()。在 ECMAScript 5 之前,可以用它來自行實作 Date.now():
Date.now = function () {
return (new Date()).getTime();
}
getTimezoneOffset() 回傳本地時間與 UTC 的時區差異(以分鐘表示,東八區為 -480),且已將日光節約時間納入考量。
console.log(new Date('2016-7-12').valueOf()); // 1468252800000
console.log(new Date('2016-7-12').getTime()); // 1468252800000
console.log(new Date('2016-7-12').getTimezoneOffset());// -480
其餘 get 方法:
getYear():距 1900 的年數(已過時,勿用)。get[UTC]FullYear():四位數年份。get[UTC]Month():月份,0–11。get[UTC]Date():月份中的第幾天,1–31。get[UTC]Day():星期幾,0–6。get[UTC]Hours():小時,0–23。get[UTC]Minutes():分鐘,0–59。get[UTC]Seconds():秒,0–59。get[UTC]Milliseconds():毫秒,0–999。同樣地,若使用標準格式且有前置 0 的字串來建立物件,得到的是 UTC 時間:
console.log(new Date('2016-07-12T10:00').getFullYear()); // 2016
console.log(new Date('2016-07-12T10:00').getUTCFullYear()); // 2016
console.log(new Date('2016-07-12T10:00').getMonth()); // 6
console.log(new Date('2016-07-12T10:00').getDate()); // 12
console.log(new Date('2016-07-12T10:00').getDay()); // 2
console.log(new Date('2016-07-12T10:00').getHours()); // 18
console.log(new Date('2016-07-12T10:00').getUTCHours()); // 10
console.log(new Date('2016-07-12T10:00').getMinutes()); // 0
console.log(new Date('2016-07-12T10:00').getSeconds()); // 0
console.log(new Date('2016-07-12T10:00').getMilliseconds()); // 0
// 假設當前本地時間為 16:35 console.log(new Date().getHours()); // 16 console.log(new Date().getUTCHours()); // 8
set 方法大致與 get 方法一一對應,傳入的參數形式近似 Date.UTC(),回傳值則是調整後該日期內部的毫秒數。注意星期只能讀取,無法設定。
setTime() 以毫秒設定整個時間值:
var d = new Date('2016-07-12T10:00');
console.log(d.setTime(86400000), d);
// 86400000 Fri Jan 02 1970 08:00:00 GMT+0800
setYear() 已過時,不建議使用:
var d = new Date('2016-07-12T10:00');
console.log(d.setYear(2000), d, d.getYear());
// 963396000000 Wed Jul 12 2000 18:00:00 GMT+0800 100
其餘 set 方法:
set[UTC]FullYear():設定年份,可選帶月份與日期。set[UTC]Month():設定月份(0–11),可選帶日期。set[UTC]Date():設定第幾天(1–31)。var d = new Date('2016-07-12T10:00');
console.log(d.setFullYear(2015, 1, 1), d.getFullYear()); // 1422784800000 2015
console.log(d.setMonth(2), d.getMonth()); // 1425204000000 2
console.log(d.setDate(20), d.getDate()); // 1426845600000 20
console.log(d.toLocaleString()); // 2015/3/20 下午6:00:00
set[UTC]Hours():設定小時(0–23),可選帶分鐘、秒、毫秒。set[UTC]Minutes():設定分鐘(0–59),可選帶秒與毫秒。set[UTC]Seconds():設定秒(0–59),可選帶毫秒。set[UTC]Milliseconds():設定毫秒(0–999)。var d = new Date('2016-07-12T10:20:30');
console.log(d.setHours(1, 2, 3), d.getHours()); // 1468256523000 1
console.log(d.setMinutes(2, 3), d.getMinutes()); // 1468256523000 2
console.log(d.setSeconds(3), d.getSeconds()); // 1468256523000 3
console.log(d.toLocaleTimeString()); // 上午1:02:03
var d = new Date('2016-07-12T10:20:30');
console.log(d.setUTCHours(1, 2, 3), d.getHours()); // 1468285323000 9
console.log(d.setUTCMinutes(2, 3), d.getMinutes()); // 1468285323000 2
console.log(d.setUTCSeconds(3), d.getSeconds()); // 1468285323000 3
console.log(d.toLocaleTimeString()); // 上午9:02:03
最後一個實務提醒:涉及跨時區的應用(例如後端與前端位於不同時區),一律在內部以毫秒數或 ISO 字串傳遞,只在顯示的瞬間才轉成本地時間,可以避開絕大多數時區相關的錯誤。