日期時間轉換、比較、格式化是前端開發高頻需求。本文提供生產級的工具函式實作,涵蓋字串解析、時區處理、比較運算、格式化輸出,並分析原生 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;
}
/**
* 比較兩個日期
* @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();
}
/**
* 日期格式化
* @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分
/**
* 取得相對時間描述(如 "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;
}
| 問題 | 說明 | 解決方案 |
|---|---|---|
| 月份 0-11 | getMonth() 返回 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()) |
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
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();
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()); };