[FEE-10001] Temporal API — 取代 Date
INFO
Date 從 Netscape Navigator 2 起就充滿缺陷。Temporal 以不可變(immutable)型別取代它,並具備原生的 IANA 時區支援:ZonedDateTime 在建構時就攜帶時區,其餘型別則明確不含時區。此提案已於 2026 年 3 月達到 TC39 Stage 4,目前已在 Firefox 139+、Chrome 與 Edge 144+,以及 Node.js 26+ 中原生內建、不需旗標即可使用。
Web Platform Proposals
Temporal 已於 2026 年 3 月達到 TC39 Stage 4,預計收錄於 ES2027 版本(未能趕上 ES2026 快照;TC39 的 finished-proposals 清單將其預期發布年份列為 2027 年)。它已在 Firefox 139+(2025 年 5 月)、Chrome 與 Edge 144+(2026 年 1 月),以及 Node.js 26+(2026 年 5 月)中穩定且不需旗標即可使用。Safari 目前僅在 Safari Technology Preview 中提供旗標後的實作,尚未達到 Baseline(所有主流瀏覽器皆支援)的門檻,因此在 Safari 與其他較舊的執行環境中仍需要 polyfill(@js-temporal/polyfill 或 temporal-polyfill)。依照本分類自身的畢業政策(見 FEE-10000),在三大引擎都不需旗標即可使用之前,Temporal 會持續留在 FEE-10001;一旦 Safari 也穩定推出,它就會成為 JavaScript Core & Runtime 的畢業候選文章。
背景
Date 是 JavaScript 最古老也最令人頭痛的 API 之一。1995 年,Brendan Eich 在 10 天內設計了它,直接複製了 Java 的 java.util.Date 設計。Java 自己在 1.1 版(1997 年)就廢棄了這個 API 的大部分方法,距離 1.0 版推出僅一年之隔。
Date 的五大核心問題
1. 月份從 0 開始計算。 一月是 0,十二月是 11。這沒有任何技術上的理由,是從 Java 複製過來的 bug,且在不破壞既有 Web 相容性的前提下無法修正。
// "這是哪個月?" — 每次忘記就會答錯
const d = new Date(2024, 0, 15); // 一月 15 日,而非第 0 個月
d.getMonth(); // 回傳 0,而非 12. Date 是可變的(mutable)。 所有 setXxx() 方法都會就地(in-place)修改物件。把一個 Date 傳給函式庫,它可能在你不知情的情況下修改你的時間戳記。
const deadline = new Date('2024-12-31');
doSomething(deadline); // 函式庫內部呼叫了 deadline.setMonth(6)
console.log(deadline); // 現在變成 7 月 31 日 — 你的截止日消失了3. 不支援 IANA 時區。 Date 物件沒有時區的概念。你只能取得本地時間(根據機器 OS 設定)或 UTC。無法將 America/New_York 或 Asia/Tokyo 當作第一類值(first-class value)來操作。每個需要處理時區的應用程式,要麼引入函式庫,要麼撰寫脆弱的手動偏移量計算。
4. 解析行為依實作而定。 new Date(string) 的行為部分有規範,部分留給引擎自行決定。
new Date('2020-01-01') // UTC(ISO 8601 純日期 → 依規範為 UTC)
new Date('01/01/2020') // 本地時間(非 ISO 格式 → 依實作)
new Date('Jan 1 2020') // 依實作而定在不同環境(Node.js 版本、各瀏覽器、iOS Safari)中,相同的字串可能產生不同的時間點(instant)。
5. 沒有時間長度(duration)運算。 沒有內建的 Duration 型別。「30 天後」需要手動進行毫秒運算。這個運算在日光節約時間(DST)邊界上會出錯。
// 錯誤:DST 轉換可能增減一小時
const thirtyDays = 30 * 24 * 60 * 60 * 1000;
const future = new Date(Date.now() + thirtyDays);
// 同樣錯誤:在 DST 轉換當天,這會悄悄給出錯誤的小時
const d = new Date();
d.setDate(d.getDate() + 30);分散式團隊遇上第五個問題
一名開發者正在為分散在各地的團隊建立行事曆應用程式。會議需要以每位參與者的本地時區顯示。開發者這樣寫:
// 嘗試方案一:偏移量計算
function toUserTime(utcMs, offsetHours) {
return new Date(utcMs + offsetHours * 3600 * 1000);
}
const meeting = new Date('2024-03-10T14:00:00Z'); // UTC
const nyDisplay = toUserTime(meeting.getTime(), -5); // "EST 是 UTC-5"冬天一切正常。但在 3 月 10 日 — 美國切換到日光節約時間的那天 — 會議顯示了錯誤的時間。紐約在轉換後是 UTC-4,而非 UTC-5。
開發者嘗試用硬編碼的 DST 表來修正,卻發現這張表需要涵蓋所有時區,以及每年的規則變更,最終發現自己在建立一個殘缺的 IANA 時區資料庫副本。
正確的解法是搭配 IANA 時區識別碼使用 Temporal.ZonedDateTime。Temporal 原生處理 DST 轉換與行事曆運算;至於閏秒,如同 Date 一樣,Temporal 刻意不表示閏秒(解析到的 :60 秒會被限制為 :59)。下方「範例」章節會正確地解出這個同一個 3 月 10 日會議。
視覺對比
快速參考:
| 使用情境 | 型別 |
|---|---|
| 向使用者顯示會議時間 | ZonedDateTime |
| 將事件儲存至資料庫 | Instant |
| 生日或節假日(純日期) | PlainDate |
| 營業時間(純時間) | PlainTime |
| 表單的日期時間輸入值 | PlainDateTime |
| 「加 30 天」或計算間隔 | Duration |
範例
以下是一個完整的時區感知行事曆應用程式範例。在引擎已原生內建 Temporal 之處直接使用原生版本,只有在缺少時才載入 polyfill:
// 進行功能偵測,只有在缺少 Temporal 時才載入 polyfill
// (Safari,以及任何比 Firefox 139 / Chrome 144 / Node.js 26 更舊的執行環境)
// 注意:@js-temporal/polyfill 刻意不會安裝全域的 Temporal 物件
// (以避免遮蔽原生實作),因此必須明確將匯入結果綁定到 globalThis。
globalThis.Temporal ??= (await import('@js-temporal/polyfill')).Temporal;
// 0. 正確解出「背景」段落中 2024 年 3 月 10 日的會議
const meeting = Temporal.Instant
.from('2024-03-10T14:00:00Z')
.toZonedDateTimeISO('America/New_York');
console.log(meeting.toString()); // "2024-03-10T10:00:00-04:00[America/New_York]"
console.log(meeting.offset); // "-04:00",DST 已自動解析
// 1. 取得當前時間,以 ZonedDateTime 表示
const nowNY = Temporal.Now.zonedDateTimeISO('America/New_York');
console.log(nowNY.toString());
// 例如:"2024-03-15T09:30:00-04:00[America/New_York]"[America/New_York] 這個後綴是 ISO 8601 的 RFC 9557 延伸格式。它在保留 UTC 偏移量的同時,也一併還原 IANA 時區,因此序列化後的 ZonedDateTime 能保有單純偏移量無法表達的時區身分。
// 2. 使用 Duration 加上 30 天
const thirtyDays = Temporal.Duration.from({ days: 30 });
const futureNY = nowNY.add(thirtyDays);
console.log(futureNY.toString());
// "2024-04-14T09:30:00-04:00[America/New_York]"
// DST 安全:Temporal 自動調整 UTC 偏移量
// 3. 轉換為 Instant 以便儲存
const instant = futureNY.toInstant();
const stored = instant.toJSON(); // ISO 8601 UTC 字串
console.log(stored);
// "2024-04-14T13:30:00Z"
// 4. 從儲存的值重建 ZonedDateTime
const reconstructed = Temporal.Instant
.from(stored)
.toZonedDateTimeISO('America/New_York');
console.log(reconstructed.toString());
// "2024-04-14T09:30:00-04:00[America/New_York]" — 完全吻合
// 5. 跨時區比較:東京早上 9 點 vs 倫敦早上 9 點
const tokyoMeeting = Temporal.ZonedDateTime.from(
'2024-06-01T09:00:00+09:00[Asia/Tokyo]'
);
const londonMeeting = Temporal.ZonedDateTime.from(
'2024-06-01T09:00:00+01:00[Europe/London]'
);
// 以 Instant 比較,找出在時間軸上哪個更早
const tokyoInstant = tokyoMeeting.toInstant();
const londonInstant = londonMeeting.toInstant();
const comparison = Temporal.Instant.compare(tokyoInstant, londonInstant);
// -1 代表 tokyoMeeting 較早
console.log(comparison); // -1
// 兩者相差多久?
const gap = tokyoInstant.until(londonInstant);
console.log(gap.toString()); // "PT8H" — 東京早上 9 點比倫敦早上 9 點早 8 小時
// 以倫敦時區顯示東京會議時間
const tokyoMeetingInLondon = tokyoMeeting
.toInstant()
.toZonedDateTimeISO('Europe/London');
console.log(tokyoMeetingInLondon.toLocaleString('en-GB', { timeZoneName: 'short' }));
// "01/06/2024, 01:00:00 BST"最佳實踐
Engineers MUST 對任何要顯示給使用者的日期/時間使用 Temporal.ZonedDateTime,無論是用於顯示、排程或跨時區比較。這個型別同時攜帶日期、時間與 IANA 時區。
const meeting = Temporal.ZonedDateTime.from({
year: 2024, month: 3, day: 10,
hour: 14, minute: 0,
timeZone: 'America/New_York',
});Engineers MUST 對資料庫儲存與跨系統傳輸使用 Temporal.Instant。 Instant 是純粹的 UTC 時間點,不含時區或行事曆。這是儲存至資料庫、放入 API 回應或寫入日誌的正確型別。
// 儲存這個 — 而非 ZonedDateTime
const stored = meeting.toInstant().toJSON(); // "2024-03-10T18:00:00Z"Engineers SHOULD NOT 在涉及時區的情境下使用 Temporal.PlainDateTime。 Plain 型別存在的目的是用於無時區的使用情境:表單輸入、範本排程(「每週一早上 9 點,不論使用者身在何處」),以及尚未確定時區的假設性未來日期。
以 Temporal.Instant.toJSON()(ISO 8601 字串)或 .epochMilliseconds(數字)儲存日期。 絕對不要將 ZonedDateTime 直接儲存至資料庫。它攜帶了不屬於資料層的使用者特定時區。
// 正確的持久化方式
const asISO = instant.toJSON(); // "2024-03-10T18:00:00Z"
const asNumber = instant.epochMilliseconds; // 1710093600000使用 Temporal.Now.zonedDateTimeISO() 取代 new Date() 取得當前時間。
// 修改前
const now = new Date();
// 修改後
const now = Temporal.Now.zonedDateTimeISO('America/New_York');從 <input type="date"> 解析使用者輸入時,先解析為 PlainDate,再搭配使用者時區轉換為 ZonedDateTime。 input[type=date] 給你的是 "2024-03-10" 這樣的字串:沒有時間,沒有時區。先將其視為 PlainDate。
const inputValue = '2024-03-10'; // 來自 <input type="date">
const plain = Temporal.PlainDate.from(inputValue);
const zoned = plain.toZonedDateTime({
timeZone: userTimezone,
plainTime: Temporal.PlainTime.from({ hour: 9 }),
});使用 .with() 進行部分更新,而非直接修改物件。
修改前:
// 修改前:直接修改 Date
const d = new Date(2024, 2, 15);
d.setMonth(5); // 就地修改修改後:
// 修改後:不可變的 Temporal
const d = Temporal.PlainDate.from('2024-03-15');
const updated = d.with({ month: 6 }); // 6 月 15 日,d 保持不變遷移既有的 Date 程式碼
Date 與 Temporal 之間的互通永遠要經過 Instant。沒有直接的 Date → ZonedDateTime 或 Date → PlainDate 轉換路徑。
// Date → Temporal(兩種等效寫法)
const legacyDate = new Date('2024-03-10T18:00:00Z');
const instantA = legacyDate.toTemporalInstant(); // 提案為 Date.prototype 新增的橋接方法
const instantB = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime());
// Temporal → Date
const backToDate = new Date(instantA.epochMilliseconds);
// Instant → 特定時區(一旦確定適用哪個時區)
const zoned = instantA.toZonedDateTimeISO('America/New_York');Engineers SHOULD 在遷移既有程式碼時優先使用 legacyDate.toTemporalInstant(),而非手動轉換 epoch 毫秒數。這是提案本身定義在 Date.prototype 上的橋接方法,在 Firefox 139+、Chrome 與 Edge 144+,以及 Node.js 26+ 中皆為原生內建。在 @js-temporal/polyfill 底下,這個方法不會自動掛載;需要先手動掛上再呼叫:Date.prototype.toTemporalInstant = toTemporalInstant;(從 polyfill 套件匯入)。
設計思維
Date 為何如此設計
Brendan Eich 在 1995 年 5 月為了趕上 Netscape 的截止日,在 10 天內寫完了 JavaScript。日期處理直接複製自 Java 的 java.util.Date,包括從 0 開始的月份。Java 在 1.0 版(1996 年)推出了 java.util.Date,意識到設計有缺陷,並在 1.1 版(1997 年)廢棄了大部分方法,改以 java.util.Calendar 取代。JavaScript 沒有類似的逃生門。Web 的向後相容性限制使這個 bug 永久固定下來。
生態系統如何補救
Date 的不足催生了整個第三方日期函式庫分類:
| 函式庫 | 狀態 | 特色 |
|---|---|---|
| Moment.js | 維護模式(2020 年 9 月) | 可變包裝器,套件體積大 |
| date-fns | 持續維護中 | 函式式,支援 tree-shaking |
| day.js | 持續維護中 | 體積極小,相容 Moment.js API |
| Luxon | 持續維護中 | 不可變,具備時區感知 |
Temporal 從 Moment.js 與 Luxon 的經驗中汲取教訓。Moment.js 維護者 Maggie Johnson-Pint 是 Temporal 提案的共同發起人(co-champion),這項設計也借鑑了這兩個函式庫在生態系統中累積的經驗。其中最關鍵的一課:把「時間點」、「行事曆日期」與「時鐘時間」分離成不同型別,讓 API 具備自我說明(self-documenting)的特性。
Temporal 的不可變設計
每個 Temporal 型別都是不可變的。算術運算回傳新物件,原始物件保持不變。這與 JavaScript 中 String 的設計原則相同:你不會修改一個字串,而是產生一個新的。
const date = Temporal.PlainDate.from('2024-01-15');
const nextMonth = date.add({ months: 1 }); // 新物件:2024-02-15
console.log(date.toString()); // "2024-01-15" — 保持不變不可變性也讓 Temporal 物件可以安全地跨函式呼叫共享、存入狀態,或作為快取鍵。使用 Date 時,這些操作都不安全。
Temporal 型別系統的職責分離
Date 試圖成為萬能工具:行事曆日期、時鐘時間、UTC 時間戳記,以及本地時間格式化,全部塞進一個可變物件。Temporal 明確地分離了這些職責:
- Instant:我們在通用時間軸上的哪個位置?(無行事曆,無時區)
- PlainDate / PlainTime / PlainDateTime:忽略時區,時鐘顯示什麼?
- ZonedDateTime:在特定地點,行事曆和時鐘顯示什麼?
- Duration:兩個時間點之間相差多少?
這反映了人類實際上思考時間的方式。「我的航班在 14:00 起飛」是 PlainTime。「Unix 紀元始於 1970-01-01T00:00:00Z」是 Instant。「會議在紐約時間週二早上 9 點」是 ZonedDateTime。
型別參考
| 型別 | 一句話說明 |
|---|---|
Temporal.PlainDate | 不含時間的行事曆日期 — 生日、節假日、申報截止日 |
Temporal.PlainTime | 不含日期的一天中的時間 — 營業時間、鬧鐘時間 |
Temporal.PlainDateTime | 不含時區的日期加時間 — 排程 UI 的輸入值、假設性日期 |
Temporal.ZonedDateTime | 包含 IANA 時區的日期加時間 — 任何面向使用者的時間的正確選擇 |
Temporal.Instant | 絕對 UTC 時間點 — 日誌、資料庫儲存、跨系統比較 |
Temporal.Duration | 用於算術的時間長度 — 「30 天」、「2 小時 15 分鐘」 |
所有型別均為不可變。所有算術方法均回傳新物件。除了預設的 ISO 8601 行事曆外,PlainDate、PlainDateTime 與 ZonedDateTime 也可透過 calendar 選項支援地區性行事曆(西曆、日本曆、希伯來曆、波斯曆、中國農曆、伊斯蘭曆等)。
常用建構模式
// 從字串字面值建立
Temporal.PlainDate.from('2024-03-15');
Temporal.Instant.from('2024-03-15T14:00:00Z');
Temporal.ZonedDateTime.from('2024-03-15T14:00:00+09:00[Asia/Tokyo]');
// 從欄位建立
Temporal.PlainDate.from({ year: 2024, month: 3, day: 15 });
Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 15, hour: 14, timeZone: 'Asia/Tokyo' });
// 取得當前時間
Temporal.Now.instant(); // 當前 UTC 時間點
Temporal.Now.zonedDateTimeISO('Asia/Tokyo'); // 東京當前時間
Temporal.Now.plainDateISO('Asia/Tokyo'); // 東京今日日期延伸閱讀
- FEE-300 JavaScript Core & Runtime Overview
- FEE-400 Browser APIs Overview
- FEE-10000 TC39 & JS Proposals Overview
- FEE-10002 Explicit Resource Management
參考資料
- TC39, "Temporal Proposal," GitHub (2026). https://tc39.es/proposal-temporal/
- TC39, "Temporal API Documentation," GitHub (2026). https://tc39.es/proposal-temporal/docs/
- MDN Contributors, "Temporal," MDN Web Docs (2026). https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
- TC39, "Temporal Cookbook," GitHub (2026). https://tc39.es/proposal-temporal/docs/cookbook.html
- Igalia, "Temporal Reaches Stage 4," Igalia Blog (2026). https://www.igalia.com/2026/03/13/Temporal-Reaches-Stage-4.html
- js-temporal maintainers, "@js-temporal/polyfill," npm (2026). https://www.npmjs.com/package/@js-temporal/polyfill
- FullCalendar, "temporal-polyfill (spec-compliant, roughly 20 KB min+gz)," GitHub (2026). https://github.com/fullcalendar/temporal-polyfill
- Mozilla, "Firefox 139 for Developers (first browser to ship Temporal unflagged)," MDN Web Docs (2025). https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/139
- Node.js Foundation, "Node.js 26.0.0 (Current) Release Notes," Node.js (2026). https://nodejs.org/en/blog/release/v26.0.0/