萬盛學電腦網

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

JavaScript 日期時間轉換與比較工具函式完整實作

JavaScript 日期時間處理核心工具函式庫實作指南

日期時間轉換、比較、格式化是前端開發高頻需求。本文提供生產級的工具函式實作,涵蓋字串解析、時區處理、比較運算、格式化輸出,並分析原生 Date 缺陷與現代替代方案。

核心工具函式實作

1. 字串解析為 Date 物件

/**
 * 將 yyyy-MM-dd HH:mm:ss.S 格式字串解析為 Date
 * 修正 Safari/iOS 不支援連字號分隔符的問題
 * @param {string} dateString - 日期時間字串
 * @returns {Date|null} 解析成功返回 Date,失敗返回 null
 */
function convertToDate(dateString) {
  if (!dateString) return null;
  
  // 統一分隔符為斜線(支援 yyyy-MM-dd 或 yyyy/MM/dd)
  var normalized = dateString.replace(/-/g, '/');
  
  // 處理毫秒部分(.S 或 .SS 或 .SSS)
  var msMatch = normalized.match(/\.(\d{1,3})(?!\d)/);
  var ms = msMatch ? parseInt(msMatch[1].padEnd(3, '0'), 10) : 0;
  
  var date = new Date(normalized);
  
  // 驗證有效性
  if (isNaN(date.getTime())) return null;
  
  // 修正毫秒(Date 建構子可能忽略 .S 格式)
  if (ms) date.setMilliseconds(ms);
  
  return date;
}

2. 日期比較函式

/**
 * 比較兩個日期
 * @param {Date|string|number} date1 
 * @param {Date|string|number} date2
 * @returns {number} 負值:date1 < date2;0:相等;正值:date1 > date2
 */
function compareDate(date1, date2) {
  var d1 = date1 instanceof Date ? date1 : convertToDate(date1);
  var d2 = date2 instanceof Date ? date2 : convertToDate(date2);
  
  if (!d1 || !d2) throw new Error('Invalid date for comparison');
  
  return d1.getTime() - d2.getTime();
}

// 便利方法
function isBefore(date1, date2) { return compareDate(date1, date2) < 0; }
function isAfter(date1, date2) { return compareDate(date1, date2) > 0; }
function isSameDay(date1, date2) {
  var d1 = date1 instanceof Date ? date1 : convertToDate(date1);
  var d2 = date2 instanceof Date ? date2 : convertToDate(date2);
  return d1.getFullYear() === d2.getFullYear() &&
         d1.getMonth() === d2.getMonth() &&
         d1.getDate() === d2.getDate();
}

3. 格式化輸出工具

/**
 * 日期格式化
 * @param {Date} date 
 * @param {string} format - yyyy/MM/dd HH:mm:ss.SSS
 * @returns {string}
 */
function formatDate(date, format) {
  if (!(date instanceof Date) || isNaN(date.getTime())) return '';
  
  var o = {
    'M+': date.getMonth() + 1,     // 月份
    'd+': date.getDate(),          // 日
    'H+': date.getHours(),         // 小時 (24制)
    'h+': date.getHours() % 12 || 12, // 小時 (12制)
    'm+': date.getMinutes(),       // 分
    's+': date.getSeconds(),       // 秒
    'q+': Math.floor((date.getMonth() + 3) / 3), // 季度
    'S+': date.getMilliseconds()   // 毫秒
  };
  
  if (/(y+)/.test(format)) {
    format = format.replace(RegExp.$1, (date.getFullYear() + '').substr(4 - RegExp.$1.length));
  }
  
  for (var k in o) {
    if (new RegExp('(' + k + ')').test(format)) {
      var val = o[k] + '';
      format = format.replace(RegExp.$1, 
        RegExp.$1.length === 1 ? val : ('00' + val).substr(val.length));
    }
  }
  return format;
}

// 使用範例
var now = new Date();
formatDate(now, 'yyyy-MM-dd HH:mm:ss');     // 2024-01-15 14:30:45
formatDate(now, 'yyyy/MM/dd');              // 2024/01/15
formatDate(now, 'HH:mm');                   // 14:30
formatDate(now, 'yyyy年MM月dd日 HH時mm分');   // 2024年01月15日 14時30分

4. 相對時間/倒數計時

/**
 * 取得相對時間描述(如 "3分鐘前"、"2小時後")
 * @param {Date|string|number} targetDate
 * @param {Date} [baseDate=new Date()] 基準時間
 * @returns {string}
 */
function getRelativeTime(targetDate, baseDate) {
  baseDate = baseDate || new Date();
  var target = targetDate instanceof Date ? targetDate : convertToDate(targetDate);
  if (!target) return '';
  
  var diff = target.getTime() - baseDate.getTime(); // 毫秒差
  var absDiff = Math.abs(diff);
  var suffix = diff > 0 ? '後' : '前';
  
  var minute = 60 * 1000;
  var hour = 60 * minute;
  var day = 24 * hour;
  var month = 30 * day;
  var year = 365 * day;
  
  if (absDiff < minute) return '剛剛';
  if (absDiff < hour) return Math.floor(absDiff / minute) + '分鐘' + suffix;
  if (absDiff < day) return Math.floor(absDiff / hour) + '小時' + suffix;
  if (absDiff < month) return Math.floor(absDiff / day) + '天' + suffix;
  if (absDiff < year) return Math.floor(absDiff / month) + '個月' + suffix;
  return Math.floor(absDiff / year) + '年' + suffix;
}

原生 Date 物件核心缺陷與避坑指南

問題說明解決方案
月份 0-11getMonth() 返回 0-11,易導致 off-by-one 錯誤永遠 +1 使用,或封裝 getMonth1()
兩位數年份new Date('20') → 1920 年永遠使用四位數年份
時區陷阱new Date('2024-01-01') 視為 UTC,new Date('2024/01/01') 視為本地統一用 ISO 8601: '2024-01-01T00:00:00'
夏令時間DST 切換日有 23 或 25 小時使用 UTC 方法或 date-fns/tz
不可變性setHours 等會修改原物件操作前複製:new Date(date.getTime())

現代替代方案推薦

輕量級:date-fns (模組化、Tree-shakable)

import { format, parseISO, differenceInDays, addDays } from 'date-fns';
import { zhTW } from 'date-fns/locale';

format(new Date(), 'yyyy/MM/dd', { locale: zhTW }); // "2024/01/15"
parseISO('2024-01-15T14:30:00'); // 安全解析
differenceInDays(endDate, startDate); // 天數差
addDays(new Date(), 7); // 7天後

企業級:Luxon / Temporal (TC39 階段 3)

// Luxon
import { DateTime } from 'luxon';
DateTime.fromISO('2024-01-15T14:30:00+08:00').toFormat('yyyy/MM/dd HH:mm');

// Temporal (未來標準)
Temporal.PlainDate.from('2024-01-15').add({ days: 7 }).toString();

TypeScript 完整型別定義

interface DateUtils {
  convertToDate(dateString: string): Date | null;
  compareDate(d1: Date | string | number, d2: Date | string | number): number;
  formatDate(date: Date, format: string): string;
  getRelativeTime(target: Date | string | number, base?: Date): string;
  isBefore(d1: Date | string, d2: Date | string): boolean;
  isAfter(d1: Date | string, d2: Date | string): boolean;
  isSameDay(d1: Date | string, d2: Date | string): boolean;
}

// 擴充 Date 原型 (謹慎使用)
interface Date {
  format(fmt: string): string;
  addDays(days: number): Date;
  clone(): Date;
}

Date.prototype.format = function(fmt) { return formatDate(this, fmt); };
Date.prototype.addDays = function(days) { 
  const d = new Date(this); d.setDate(d.getDate() + days); return d; 
};
Date.prototype.clone = function() { return new Date(this.getTime()); };
copyright © 萬盛學電腦網 all rights reserved