萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

JavaScript Date 物件完整 API 參考與避坑指南

建構函式多載

new Date()                          // 現在
new Date(milliseconds)              // 自 1970-01-01 UTC 毫秒數
new Date(dateString)                // 解析字串(格式差異大,見下)
new Date(year, monthIndex, day, hour, minute, second, ms)
// monthIndex: 0=1月 ... 11=12月

靜態方法

  • Date.now():當前時間毫秒數(ES5+,IE9+)。
  • Date.parse(str):解析字串回傳毫秒數,依本地時區。
  • Date.UTC(y, m, d, h, min, s, ms):依 UTC 回傳毫秒數。

日期字串解析大坑

new Date('2012/03/13') // 本地午夜
new Date('2012-03-13') // ISO 格式 → 視為 UTC,轉本地顯示可能時差 8 小時
new Date('2012-3-13')  // 非標準,瀏覽器表現不一

鐵律: 只用 YYYY/MM/DD 或 YYYY-MM-DDTHH:mm:ss.sssZ(ISO 8601)格式;避免連字號無時區字串;四位數年份;Chrome 相容最好但不可當標準。

取值方法(get / getUTC)

本地UTC說明
getFullYear()getUTCFullYear()四位數年份
getMonth()getUTCMonth()0-11
getDate()getUTCDate()1-31
getDay()getUTCDay()0-6 (週日-週六)
getHours()getUTCHours()0-23
getMinutes()getUTCMinutes()0-59
getSeconds()getUTCSeconds()0-59
getMilliseconds()getUTCMilliseconds()0-999
getTime()-毫秒數(等同 valueOf())
getTimezoneOffset()-本地與 UTC 分鐘差

設值方法(set / setUTC)

對應上表各 get,如 setFullYear()、setMonth()、setDate()... 參數超出範圍會自動進位(如 setMonth(12) → 明年 1 月)。

格式化輸出

const d = new Date();
d.toString()            // "Tue Sep 17 2013 13:37:04 GMT+0800"
d.toISOString()         // "2013-09-17T05:37:04.000Z" (ES5+, 標準交換格式)
d.toLocaleString()      // "2013/9/17 下午1:37:04" (依瀏覽器語系)
d.toLocaleString('zh-TW', { dateStyle: 'full', timeStyle: 'long' }) // 客製化
d.toLocaleDateString()  // 只日期
d.toLocaleTimeString()  // 只時間

現代替代方案:Temporal API(Stage 3)

新一代 Temporal 物件解決 Date 設計缺陷(不可變、時區支援、解析嚴格),未來將取代 Date。目前可用 polyfill 體驗。

總結

Date 物件歷史包袱重,核心記住:內部儲存 UTC 毫秒數、月份 0-based、字串解析極不穩定。嚴格使用 ISO 8601 字串、善用 toISOString 交換資料、格式化用 toLocaleString 並指定 locale/options,即可避開 90% 的坑。

copyright © 萬盛學電腦網 all rights reserved