萬盛學電腦網

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

JavaScript 日期時間處理大全:原生 API、格式化、計算、解析與現代庫選型

日期時間處理是前端開發的高頻痛點。本文系統整理原生 Date API、常用格式化/計算/解析工具函數、時區陷阱、效能考量,並對比主流現代庫(date-fns、dayjs、Luxon、Temporal 提案),助你根據專案需求做最佳選型。

一、原生 Date 基礎 API 速查

方法說明回傳範例
getFullYear()四位數年份2025
getMonth()月份(0-11)5 (六月)
getDate()日期(1-31)15
getDay()星期(0-6,0=週日)0
getHours()小時(0-23)14
getMinutes()分鐘(0-59)30
getSeconds()秒數(0-59)45
getMilliseconds()毫秒(0-999)123
getTime()時間戳(毫秒,UTC 1970/1/1 起)1749997845123
Date.now()靜態方法,當前時間戳同上
toISOString()ISO 8601 字串 (UTC)"2025-06-15T06:30:45.123Z"
toLocaleString()依當地語系格式化"2025/6/15 下午2:30:45"

二、萬用格式化函式(支援 yyyy/MM/dd HH:mm:ss.S 等自訂格式)


/**
 * 日期格式化
 * @param {Date|number|string} date 日期物件/時間戳/可解析字串
 * @param {string} fmt 格式模板
 * @returns {string}
 * 
 * 模板符號:
 * yyyy/YYYY - 四位年份
 * yy/YY     - 兩位年份
 * MM        - 雙位月份 (01-12)
 * M         - 月份 (1-12)
 * dd/DD     - 雙位日期 (01-31)
 * d/D       - 日期 (1-31)
 * HH/hh     - 雙位小時 (00-23 / 01-12)
 * H/h       - 小時 (0-23 / 1-12)
 * mm        - 雙位分鐘 (00-59)
 * m         - 分鐘 (0-59)
 * ss/SS     - 雙位秒數 (00-59)
 * s/S       - 秒數 (0-59)
 * SSS       - 三位毫秒 (000-999)
 * w/W       - 星期中文 (日-六)
 */
function formatDate(date, fmt = 'yyyy-MM-dd HH:mm:ss') {
  if (!date) return '';
  const d = date instanceof Date ? date : new Date(date);
  if (isNaN(d.getTime())) return 'Invalid Date';

  const week = ['日','一','二','三','四','五','六'];
  const opt = {
    'yyyy|YYYY': d.getFullYear(),
    'yy|YY': String(d.getFullYear() % 100).padStart(2, '0'),
    'MM': String(d.getMonth() + 1).padStart(2, '0'),
    'M': d.getMonth() + 1,
    'dd|DD': String(d.getDate()).padStart(2, '0'),
    'd|D': d.getDate(),
    'HH|hh': String(d.getHours()).padStart(2, '0'),
    'H|h': d.getHours(),
    'mm': String(d.getMinutes()).padStart(2, '0'),
    'm': d.getMinutes(),
    'ss|SS': String(d.getSeconds()).padStart(2, '0'),
    's|S': d.getSeconds(),
    'SSS': String(d.getMilliseconds()).padStart(3, '0'),
    'w|W': week[d.getDay()]
  };

  let result = fmt;
  for (const [pattern, value] of Object.entries(opt)) {
    result = result.replace(new RegExp(pattern, 'g'), String(value));
  }
  return result;
}

// 測試
console.log(formatDate(new Date(), 'yyyy年MM月dd日 w HH:mm:ss.SSS'));
// 2025年06月15日 日 14:30:45.123

三、日期計算工具函數


// 日期加減(天/月/年)
function addDate(date, amount, unit = 'day') {
  const d = new Date(date);
  switch (unit) {
    case 'day': d.setDate(d.getDate() + amount); break;
    case 'month': d.setMonth(d.getMonth() + amount); break;
    case 'year': d.setFullYear(d.getFullYear() + amount); break;
    case 'hour': d.setHours(d.getHours() + amount); break;
    case 'minute': d.setMinutes(d.getMinutes() + amount); break;
    case 'second': d.setSeconds(d.getSeconds() + amount); break;
  }
  return d;
}

// 兩日期差值(回傳毫秒/秒/分/時/天)
function diffDate(date1, date2, unit = 'day') {
  const diff = new Date(date1).getTime() - new Date(date2).getTime();
  const units = { ms: 1, s: 1e3, m: 6e4, h: 3.6e6, day: 8.64e7 };
  return Math.floor(diff / (units[unit] || units.day));
}

// 取得該月天數
function daysInMonth(year, month) { // month 1-12
  return new Date(year, month, 0).getDate();
}

// 判斷閏年
function isLeapYear(year) {
  const y = year || new Date().getFullYear();
  return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
}

// 取得該日期是當年第幾周 (ISO 8601)
function getWeekOfYear(date) {
  const d = new Date(date);
  d.setHours(0,0,0,0);
  d.setDate(d.getDate() + 4 - (d.getDay() || 7));
  const yearStart = new Date(d.getFullYear(), 0, 1);
  return Math.ceil((d - yearStart) / 8.64e7 / 7);
}

四、字串解析為 Date(安全版)


function parseDate(str, formats = ['yyyy-MM-dd', 'yyyy/MM/dd', 'yyyy.MM.dd', 'yyyy-MM-dd HH:mm:ss']) {
  if (!str) return null;
  if (str instanceof Date) return str;
  if (typeof str === 'number') return new Date(str);
  
  // 嘗試原生解析(支援 ISO 8601、RFC 2822 等)
  const native = new Date(str);
  if (!isNaN(native.getTime())) return native;
  
  // 依格式模板解析
  for (const fmt of formats) {
    const regex = fmt
      .replace(/yyyy|YYYY/g, '(\\d{4})')
      .replace(/yy|YY/g, '(\\d{2})')
      .replace(/MM/g, '(\\d{2})')
      .replace(/M/g, '(\\d{1,2})')
      .replace(/dd|DD/g, '(\\d{2})')
      .replace(/d|D/g, '(\\d{1,2})')
      .replace(/HH|hh/g, '(\\d{2})')
      .replace(/H|h/g, '(\\d{1,2})')
      .replace(/mm/g, '(\\d{2})')
      .replace(/m/g, '(\\d{1,2})')
      .replace(/ss|SS/g, '(\\d{2})')
      .replace(/s|S/g, '(\\d{1,2})');
    
    const match = str.match(new RegExp(`^${regex}$`));
    if (match) {
      const [, y, M, d, H, m, s] = match;
      const year = y.length === 2 ? 2000 + +y : +y;
      const month = (+M || 1) - 1;
      const day = +d || 1;
      const hour = +H || 0;
      const min = +m || 0;
      const sec = +s || 0;
      const dt = new Date(year, month, day, hour, min, sec);
      if (!isNaN(dt.getTime())) return dt;
    }
  }
  return null;
}

五、時區處理核心觀念

  1. Date 內部儲存 UTC 時間戳,所有 get* 方法回傳本地時間,getUTC* 回傳 UTC。
  2. toISOString() / toJSON() 永遠輸出 UTC(Z 結尾)。
  3. new Date('2025-06-15'):無時區字串視為 UTC(ES5/ES6 行為不一,極易出 Bug)。
  4. new Date('2025-06-15T00:00:00'):無時區視為本地。
  5. 最佳實踐:傳輸/儲存統一用 ISO 8601 UTC 字串(toISOString()),顯示時用 toLocaleString() 或格式化函式指定 timeZone。

指定時區格式化(Intl.DateTimeFormat)


function formatInTimeZone(date, fmt, timeZone = 'Asia/Taipei', locale = 'zh-TW') {
  const d = date instanceof Date ? date : new Date(date);
  const options = { timeZone, hour12: false };
  // 手動映射格式符號到 IntL 選項(簡化版)
  return new Intl.DateTimeFormat(locale, {
    ...options,
    year: 'numeric', month: '2-digit', day: '2-digit',
    hour: '2-digit', minute: '2-digit', second: '2-digit'
  }).format(d).replace(/\//g, '-').replace(/,/, '');
}

六、現代庫對比選型指南

庫體積 (gz)API 風格Tree-shaking時區/國際化不可變性推薦場景
date-fns v3~12 KB (按需)函數式、純淨✅ 極佳需搭配 date-fns-tz✅現代專案首選、Tree-shaking 關鍵
dayjs~2 KB (核心)Moment 相容鏈式✅ 好插件制 utc/timezone✅舊專案遷移 Moment、體積敏感
Luxon~15 KB類別導向、Intl 為核心⚠️ 較弱✅ 內建最強✅複雜時區/國際化、Node 後端
Temporal (Stage 3)原生 (未來)現代化、不可變、強類型N/A✅ 原生級✅未來標準,可用 Polyfill 試用
原生 Date + 封裝0 KB自定N/A手動處理❌ 可變極簡專案、無建置流程、學習用途

七、效能與最佳實踐清單

  • ✅ 高頻格式化(如列表渲染)使用 Intl.DateTimeFormat 實例複用,避免重複建構。
  • ✅ 避免在迴圈中 new Date(),提取時間戳運算。
  • ✅ 序列化傳輸統一 toISOString(),後端儲存 UTC。
  • ✅ 表單輸入用 <input type="datetime-local">,配合 valueAsDate。
  • ✅ 單元測試覆蓋邊界:閏年、月份邊界、夏令時間切換、時區跨日。

結語

原生 Date API 雖有歷史包袱,但配合 formatDate、addDate、diffDate、parseDate 等封裝函式已能覆蓋 80% 場景。專案若涉及複雜時區、國際化、大量日期運算,強烈建議引入 date-fns(函數式、Tree-shaking 友善)或 Luxon(Intl 核心、時區最強)。未來標準 Temporal 正在推進中,值得持續關注。

copyright © 萬盛學電腦網 all rights reserved