Date.parse()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Date.parse() 方法解析一表示日期的字串，並回傳自 1970 年 01 月 01 日 00:00:00 UTC 起至該日期共經過的毫秒數；如果字串無法辨識或包含無效值（如：2015-02-31），則回傳 NaN。

只有 ISO 8601 格式（ YYYY-MM-DDTHH:mm:ss.sssZ）為明確指定支援的格式。其餘格式因實作方式而異，不一定跨瀏覽器通用。若需要涵蓋多種格式，可以引入函式庫協助。

嘗試一下

語法

js
Date.parse(dateString)

參數

dateString

一個簡化表示 ISO 8601 日曆日期延伸格式的字串。（亦可使用其他格式，但結果會依實作方式而定。）

返回值

一個自 1970 年 01 月 01 日 00:00:00 UTC 起，至解析字串而得的日期為止，所經過的毫秒數值。如果該參數並非有效日期，則回傳 NaN 。

描述

parse() 方法接受一日期字串（例如： "2011-10-10T14:48:00"）並回傳自 1970 年 01 月 01 日 00:00:00 UTC 至該日期所經過的毫秒數。

此函式實用於設定日期，例如結合使用 setTime() 方法與 Date 物件。

日期字串格式

呈現日期時間的標準字串格式乃 ISO 8601 日曆日期延伸格式的簡化版。（詳細請參見 ECMAScript 規範的 Date Time String Format章節）

例如，"2011-10-10"（只有日期）、"2011-10-10T14:48:00"（日期與時間），或 "2011-10-10T14:48:00.000+09:00"（日期與時間至毫秒級以及時區）皆可作為有效參數傳入並解析。如果沒有指明時差，只有日期的參數會假設為 UTC 時間，而有日期與時間的參數會當作是本地時間。

解析日期字串的過程雖然會加註時區，但回傳值必定是從 1970 年 01 月 01 日 00:00:00 UTC 起至該參數表示的日期為止，所經過的毫秒數；或是 NaN。

因為 parse() 是 Date 的靜態方法，故會以 Date.parse() 而非作為 Date 實例的方法呼叫。

退回至實作定義的日期格式

备注： 此段落包含因實作而異的行為，不同實作間可能不一致。

ECMAScript 規範表明：如果字串不符合標準格式，函式可能會退回至實作定義的啟發式或解析演算法。無法辨識的字串或包含無效值的 ISO 格式字串將使 Date.parse() 回傳 NaN。

不過無效且非 ECMA-262 定義的 ISO 格式的日期字串，其回傳結果會依瀏覽器與實際值而異，不一定回傳 NaN，例如：

js
// 非 ISO 字串且含無效日期值
new Date("23/25/2014");

在 Firefox 30 當中會被視為本地時間的 2015 年 11 月 25 日，而 Safari 7 中則為無效日期。

但如果為 ISO 格式的字串而包含無效值，則會回傳 NaN：

js
// ISO 字串且含無效日期值
new Date("2014-25-23").toISOString();
// throws "RangeError: invalid date"

SpiderMonkey 的實作啟發可見 jsdate.cpp。例如 "10 06 2014" 即不符合 ISO 格式，故會執行自定義解析。參見 rough outline 以瞭解運作原理。

js
new Date("10 06 2014");

會被視為本地時間的 2014 年 10 月 06 日 而非 2014 年 06 月 10 日。

其他範例：

js
new Date("foo-bar 2014").toString();
// returns: "Invalid Date"

Date.parse("foo-bar 2014");
// returns: NaN

假定時區上的差異

备注： 此段落包含因實作而異的行為，不同實作間可能不一致。

給定一非標準的字串 "March 7, 2014"，parse() 會假定為本地時區；但如果是簡化版的 ISO 8601 日曆日期延伸格式的字串，如 "2014-03-07"，則會假定為 UTC 時區。故，除非系統為 UTC 時區，否則依支援的 ECMAScript 版本，由該字串產生的 Date 物件可能呈現不同時間。亦即兩個看似相等的日期字串，依傳入的格式而可能產生不同解析結果。

範例

使用 Date.parse()

下列呼叫皆會回傳 1546300800000。第一個隱含為 UTC 時間，其餘則以 ISO 日期規範（Z 與 +00:00）明確表示 UTC 時區。

js
Date.parse("2019-01-01");
Date.parse("2019-01-01T00:00:00.000Z");
Date.parse("2019-01-01T00:00:00.000+00:00");

以下呼叫並未指明時區，將會設定為使用者系統時區的 2019-01-01 00:00:00。

js
Date.parse("2019-01-01T00:00:00");

非標準的日期字串

备注： 此段落包含因實作而異的行為，不同實作間可能不一致。

若 ipoDate 為既有的 Date 物件，可將其設定為本地時間的 1995-08-09，如下：

js
ipoDate.setTime(Date.parse("Aug 9, 1995"));

其他解析非標準日期字串的範例：

js
Date.parse("Aug 9, 1995");

因為此字串未指明時區、且並非 ISO 格式，故預設為本地時區。如在 GMT-0300 時區回傳 807937200000，其他時區另計。

js
Date.parse("Wed, 09 Aug 1995 00:00:00 GMT");

因為已指明 GMT (UTC) 時區，不論本地時區為何，皆回傳 807926400000。

js
Date.parse("Wed, 09 Aug 1995 00:00:00");

因為參數內沒有指明時區，而且並非 ISO 格式，因此視為本地時間。在 GMT-0300 時區會回傳 807937200000，其他時區另計。

js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT");

因為已指明 GMT (UTC) 時區，不論本地時區為何，皆回傳 0。

js
Date.parse("Thu, 01 Jan 1970 00:00:00");

因為此字串未指明時區、且並非 ISO 格式，故預設為本地時區。如在 GMT-0400 回傳 14400000，其他時區另計。

js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT-0400");

因為已指明 GMT (UTC) 時區，不論本地時區為何，皆回傳 14400000。

規範

Specification
ECMAScript Language Specification
# sec-date.parse

瀏覽器相容性

BCD tables only load in the browser

相容性資訊

  • Firefox 49 將解析兩位數年份的方式從與 Internet Explorer 改為與 Google Chrome 一致。現在小於 50 的兩位數年份會解析為 21 世紀年份。例如 04/16/17，先前會視為 1917 年 04 月 16 日；現在則解析為 2017 年 04 月 16 日。建議使用 ISO 8601 格式如 "2017-04-16"，以避免任何互通性問題或不明確的年份。（bug 1265136）
  • Google Chrome 視數字字串為有效的 dateString 參數。例如 !!Date.parse("42") 在 Firefox 會評估為 false，而在 Google Chrome 會評估為 true；因為 "42" 被當作是 2042 年 01 月 01 日。

參見