HOWTO · JavaScript

在 JavaScript 中將字串轉換為日期

本教程列出了使用 JavaScript 將字串轉換為日期的各種方法。

本頁內容

資料庫或 API 傳來的日期字串仍然是字串,因此日期選擇器或計算可能需要 JavaScript Date 物件。適合的轉換方式取決於輸入格式,以及是否明確指定時區。將字串傳入 new Date(dateString),可解析受支援的標準格式;不帶引數的 new Date() 則會建立代表目前時間的 Date。需要毫秒數時可使用 Date.parse();若格式已知且為自訂格式,也可以自行解析各個組成部分。

本指南介紹三種實用做法:

  • 將受支援的日期字串傳入 new Date(dateString),建立 Date 物件。
  • 需要數值形式的毫秒數時,呼叫 Date.parse()。
  • 先將已知的自訂格式拆分成各個組成部分,再建立 Date。

在 JavaScript 中使用 new Date() 將字串轉換為 Date

new Date(dateString) 建構函式接受受支援的日期字串,並回傳 Date 物件。這個 ISO 8601 時間戳包含 Z,表示 UTC。無論機器採用哪個本地時區,呼叫 toISOString() 都會回傳該 UTC 時間。

const dateString = '2024-05-23T14:30:00Z';
const date = new Date(dateString);

console.log(date instanceof Date);
console.log(date.toISOString());

只有日期的字串,例如 2024-05-23,會以 UTC 解讀;不含時區偏移量的日期時間字串則會以本地時間解讀。若來源代表特定時刻,請使用明確標示時區偏移量的標準格式字串,避免解讀結果受到機器本地時區影響。

JavaScript 各種實作對標準日期時間格式以外的解析方式沒有一致規範。某個瀏覽器或執行環境接受的字串,在其他環境中可能會有不同解讀。使用結果前,請以 Number.isNaN(date.getTime()) 檢查產生的物件。解析成功也不代表字串符合應用程式要求的格式或日曆規則;這些條件仍須另外驗證。

在 JavaScript 中使用 Date.parse() 解析日期字串

Date.parse() 會回傳解析所得日期距離 Unix 紀元的毫秒數;若無法解析輸入內容,則會回傳 NaN。它回傳的是數字,而不是 Date 物件。處理 API 值時,可以先解析,再於需要物件時使用數值結果建立日期:

const apiValue = '2019-01-01T12:30:00.000Z';
const milliseconds = Date.parse(apiValue);

console.log(typeof milliseconds);
console.log(Number.isNaN(milliseconds) ? 'not parsed' : new Date(milliseconds).toISOString());

Number.isNaN() 可以偵測解析失敗的訊號,但無法完整驗證應用程式專用的格式。執行環境可能會接受應用程式應該拒絕的值。若輸入必須符合特定模式,請先檢查該模式及日期欄位的日曆值,再使用解析結果。

在 JavaScript 中拆分字串並將其轉換為 Date

輸入採用已知的自訂格式時,請依照該格式拆分字串,再將各個組成部分傳入多引數的 Date 建構函式。此範例預期格式為 DD-MM-YYYYTHH:mm:ss;建構函式會將這些組成部分解讀為本地時間。若組成部分無法構成有效日期,則會回傳 null。

function parseKnownDate(value) {
  if (typeof value !== 'string') {
    return null;
  }

  const dateTimeParts = value.split('T');
  if (dateTimeParts.length !== 2) {
    return null;
  }

  const [datePart, timePart] = dateTimeParts;
  if (
    !/^\d{2}-\d{2}-\d{4}$/.test(datePart) ||
    !/^\d{2}:\d{2}:\d{2}$/.test(timePart)
  ) {
    return null;
  }

  const dateParts = datePart.split('-');
  const timeParts = timePart.split(':');
  if (dateParts.length !== 3 || timeParts.length !== 3) {
    return null;
  }

  const [day, month, year] = dateParts.map(Number);
  const [hours, minutes, seconds] = timeParts.map(Number);

  if (![day, month, year, hours, minutes, seconds].every(Number.isInteger)) {
    return null;
  }

  // The multi-argument constructor treats years 0–99 as 1900–1999.
  // setFullYear preserves the supplied year, including values in that range.
  const date = new Date(0);
  date.setFullYear(year, month - 1, day);
  date.setHours(hours, minutes, seconds, 0);

  if (
    date.getFullYear() !== year ||
    date.getMonth() !== month - 1 ||
    date.getDate() !== day ||
    date.getHours() !== hours ||
    date.getMinutes() !== minutes ||
    date.getSeconds() !== seconds
  ) {
    return null;
  }

  return date;
}

const date = parseKnownDate('21-03-2020T11:20:30');
console.log(date === null ? 'not a valid date' : date.toString());

拆分方式取決於前述組成部分的順序;若來源使用不同順序或分隔符號,請相應調整。月份引數從零開始計算,因此程式碼會將一般月份數值減一。設定器使用本地時間,並可能將超出範圍的數值正規化;比對結果中的組成部分與解析出的數值,即可偵測是否發生正規化。初始日期以本地時區為基準,因此這個方法建立的是本地時間值,而非 UTC 時間戳。如果年份可能介於 0 到 99,使用 setFullYear() 可避開多引數建構函式對這些年份的特殊處理。此範例會檢查整數組成部分及日曆日期是否因進位而改變;輸入規則較嚴格的應用程式,也應檢查確切的字串模式及各欄位允許的範圍。

結論

將受支援的日期字串傳入 new Date(dateString) 可建立 Date 物件;若字串代表特定時刻,最好明確指定時區偏移量。不帶引數的 new Date() 會建立代表目前時間的 Date,並不會解析字串。需要距離 Unix 紀元的毫秒數或以 NaN 表示的解析失敗訊號時,可使用 Date.parse();成功解析後,若需要 Date 物件,再將數值傳入 new Date(milliseconds)。處理已知的自訂格式時,請先解析並驗證各個組成部分,再建立本地時間日期。ISO 8601 概覽介紹了許多 API 使用的日期與時間表示方式。