日期時間處理是前端開發的高頻痛點。本文系統整理原生 Date API、常用格式化/計算/解析工具函數、時區陷阱、效能考量,並對比主流現代庫(date-fns、dayjs、Luxon、Temporal 提案),助你根據專案需求做最佳選型。
| 方法 | 說明 | 回傳範例 |
|---|---|---|
| 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" |
/**
* 日期格式化
* @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);
}
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;
}
Date 內部儲存 UTC 時間戳,所有 get* 方法回傳本地時間,getUTC* 回傳 UTC。toISOString() / toJSON() 永遠輸出 UTC(Z 結尾)。new Date('2025-06-15'):無時區字串視為 UTC(ES5/ES6 行為不一,極易出 Bug)。new Date('2025-06-15T00:00:00'):無時區視為本地。toISOString()),顯示時用 toLocaleString() 或格式化函式指定 timeZone。
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 正在推進中,值得持續關注。