Date 是 JavaScript 裡最容易踩雷的內建物件之一:月份從 0 起算、日期字串解析跨瀏覽器不一致、時區處理反直覺。本文把建構方式、靜態方法與各系列實例方法完整梳理一遍,並標出實務上的注意事項。
// 1. 無參數:以當前日期時間為初始值 new Date(); // 2. 毫秒數:自 1970-01-01T00:00:00Z 起的毫秒數 new Date(value); // 3. 日期字串:格式必須能被 parse 方法識別 new Date(dateString); // 4. 各欄位分別指定 new Date(year, month, day [, hour, minute, second, millisecond]);
第 4 種形式有兩個務必牢記的規則:year 請給四位數(0~99 會被解讀為 1900~1999),month 從 0 起算(0 是一月,11 是十二月)。這兩點是新手最常寫錯的地方。
注意不加 new 直接呼叫 Date(),回傳的是字串而非物件:
console.log(Date()); // "Tue Sep 17 2013 12:22:55 GMT+0800 (中國標準時間)"
解析日期時間字串,回傳距 1970-01-01 零時的毫秒數。
Date.parse(datestring)
參數 datestring 為日期時間字串。這是 Date 的靜態方法,應以 Date.parse() 呼叫。解析結果基於本地時區。
console.log(Date.parse(Date())); // 1379392301000
console.log(Date.parse("Aug 9, 1995")); // 807897600000
同樣是靜態方法,但參數被視為 UTC 時間,回傳毫秒數。
Date.UTC(year, month, day, hours, minutes, seconds, ms)
year(四位數)與 month(0~11)為必需;其餘 day(1~31)、hours(0~23)、minutes(0~59)、seconds(0~59)、ms(0~999)皆為選填。
parse 與 UTC 的關鍵差異:兩者的參數形式相同,但 parse() 把字串當本地時間解讀,UTC() 則當 GMT 解讀。同一個時刻用兩種方式算出來的毫秒數會相差一個時區偏移量:
var d = new Date(); console.log(Date.parse(d)); // 1379393562000 console.log(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds())); // 1379422362020 (相差 8 小時 = 28800000 毫秒)
GMT 即格林威治標準時間。ECMAScript 的 Date 型別沿用自 Java 的 java.util.Date,內部以「距 UTC 1970-01-01 零時的毫秒數」儲存,因此可表示的範圍可精確到 1970 年前後約 285616 年。
ES5 新增,回傳當前毫秒數,比 +new Date() 更直觀。IE9 起支援。若需相容更舊的環境,可用位元運算的 +new Date() 寫法取得相同結果。
var d1 = Date.now(); var d2 = + new Date(); console.log(d1); // 1379393793104 console.log(d2); // 1379393793104
同樣是 2012 年 3 月 13 日,三種寫法結果不同:
var d1 = new Date("2012/03/13");
var d2 = new Date("2012-03-13");
var d3 = new Date("2012-3-13");
console.log(d1); // Tue Mar 13 2012 00:00:00 GMT+0800
console.log(d2); // Tue Mar 13 2012 08:00:00 GMT+0800 <-- 少了 8 小時
console.log(d3); // Tue Mar 13 2012 00:00:00 GMT+0800
d2 之所以偏移,是因為 YYYY-MM-DD 是 ISO 8601 格式,標準要求當作 UTC 解讀;而 YYYY/MM/DD 不在 ISO 規格內,各瀏覽器一律當本地時間處理。各瀏覽器接受的格式差異可参考 dygraphs 的日期格式比較表。
為了避開這些問題,請遵守:
1. 統一使用 YYYY/MM/DD 格式
2. 避免帶連字號的 YYYY-MM-DD
3. 年份一律給四位數
4. Chrome 能接受的格式比其他瀏覽器寬鬆得多,在 Chrome 跑通不代表其他瀏覽器沒問題
ES5 之後,YYYY-MM-DDTHH:mm:ss 這種完整的 ISO 8601 格式是跨瀏覽器最可靠的選擇;只有日期時請補上 T00:00:00 並明確標示時區(例如加 Z),語意才不會有歧義。
getDate() 月中的第幾天(1~31)|getDay() 週中第幾天(0~6)|getMonth() 月份(0~11)|getFullYear() 四位數年份(勿用 getYear)|getHours()(0~23)|getMinutes()(0~59)|getSeconds()(0~59)|getMilliseconds()(0~999)|getTime() 距 1970 的毫秒數|getTimezoneOffset() 本地與 GMT 的分鐘差。
對應的 UTC 版本為:getUTCDate()、getUTCDay()、getUTCMonth()、getUTCFullYear()、getUTCHours()、getUTCMinutes()、getUTCSeconds()、getUTCMilliseconds()。
setDate()(1~31)|setMonth()(0~11)|setFullYear()(勿用 setYear)|setHours()|setMinutes()|setSeconds()|setMilliseconds()|setTime() 以毫秒設定。UTC 版本依序為 setUTCDate()、setUTCMonth()、setUTCFullYear()、setUTCHours()、setUTCMinutes()、setUTCSeconds()、setUTCMilliseconds()。
toString() 轉字串(美式英語格式)|toTimeString() 只取時間部分|toDateString() 只取日期部分|toUTCString() 依 GMT 輸出|toLocaleString() 依本地格式輸出|toLocaleTimeString() 本地時間部分|toLocaleDateString() 本地日期部分。
var d = new Date(); console.log(d); // Tue Sep 17 2013 13:37:04 GMT+0800 (中國標準時間) console.log(d.toString()); // 同上 console.log(d.toTimeString()); // 13:37:04 GMT+0800 (中國標準時間) console.log(d.toDateString()); // Tue Sep 17 2013 console.log(d.toUTCString()); // Tue, 17 Sep 2013 05:37:04 GMT console.log(d.toLocaleString()); // 2013年9月17日 下午1:37:04 console.log(d.toLocaleTimeString()); // 下午1:37:04 console.log(d.toLocaleDateString()); // 2013年9月17日
toLocaleString() 系列可接收 locale 與 options 參數,指定輸出慣例:
console.log(new Date().toLocaleString("ko-KR"));
// 2013년 9월 17일 오후 1:48:24
格式化日期時,Intl.DateTimeFormat 比 toLocaleString() 效能好得多(後者每次呼叫都要重新初始化格式化器),也更可控:
const fmt = new Intl.DateTimeFormat('zh-TW', {
dateStyle: 'medium', timeStyle: 'long', timeZone: 'Asia/Taipei'
});
console.log(fmt.format(new Date()));
而若專案涉及跨時區運算、日期加法、月末處理等複雜邏輯,強烈建議引入 dayjs、date-fns 或 Luxon。原生的 Date 只有「時間戳」一個維度,無法表達「只有日期沒有時區」這種常見需求,硬用 Date 處理只會累積 bug。ES2020 提案中的 Temporal 就是為了解決這個問題而出現的,環境支援成熟後可優先採用。