`Date` 物件

本文將說明 Date 物件。

我們將以實際例子，從基本機制到實務工作中常用的操作，逐步說明 Date 物件。

YouTube Video

Date 物件

Date 物件是什麼？

JavaScript 的 Date 物件是用來處理日期與時間的標準物件。在內部，它根據自 1970 年 1 月 1 日 00:00:00（UTC）以來經過的毫秒數來管理日期和時間。

首先，讓我們建立一個表示當前日期和時間的 Date 物件，並檢查其內容。

1const now = new Date();
2console.log(now);

• 這段程式碼會建立一個代表執行瞬間當下日期與時間的 Date 物件。顯示格式會根據執行環境（例如瀏覽器或作業系統）有所不同。

如何建立 Date 物件

根據需求，可以用多種方式建立 Date 物件。有一點特別容易出錯，需要注意，就是建構函數中的「月份是以 0 為起點」，也就是月份從 0 開始。

1const d1 = new Date();                     // Current date and time
2const d2 = new Date("2025-01-01");         // Create from an ISO date string
3const d3 = new Date(2025, 0, 1);           // January 1, 2025 (month is zero-based)
4const d4 = new Date(2025, 0, 1, 10, 30);   // January 1, 2025, 10:30
5
6console.log(d1, d2, d3, d4);

• 在 new Date(year, month, day) 當中，month 代表「0 是一月，11 是十二月」。如果沒注意這一點，可能會不小心建立偏差一個月的日期，因此要格外留意。

取得日期與時間的各元素

你可以從 Date 物件中分別取得年份、月份、日期、時間以及星期幾。所有取得方法（getter）都會回傳數字型態。

1const date = new Date();
2
3console.log(date.getFullYear()); // Year
4console.log(date.getMonth());    // Month (0-based: 0 = January)
5console.log(date.getDate());     // Day of the month
6console.log(date.getHours());    // Hours
7console.log(date.getMinutes());  // Minutes
8console.log(date.getSeconds());  // Seconds
9console.log(date.getDay());      // Day of the week (0 = Sunday, 6 = Saturday)

• 與建立日期一樣，getMonth() 取得的月份也是以 0 為起點。在顯示時通常會加 1 來進行調整。
• getDay() 會以數字的形式返回星期幾。0 代表星期日，6 代表星期六。

修改日期與時間

Date 是可變動（mutable）的物件，也就是說你可以在之後更改他的值。這項特性很方便，但也要小心不小心造成副作用。

你可以使用 set 方法來更改現有 Date 物件的值。

1const date = new Date("2025-01-01");
2
3date.setFullYear(2026);
4date.setMonth(5);   // June
5date.setDate(15);
6
7console.log(date);

• setMonth() 也是以 0 為起點。原本的物件會被直接修改。

日期的加減運算

日期的計算通常是用毫秒進行，或是透過 setDate() 方法。若以「天」為單位進行計算，用 setDate() 特別直觀又安全。

1const date = new Date("2025-01-01");
2
3date.setDate(date.getDate() + 7);
4console.log(date);

• 在這個例子中，我們計算指定日期後第 7 天的日期。即使用天數跨到下個月，也會自動調整。

比較 Date 物件

Date 物件可以當作數值進行比較。這是因為內部實際比較的是毫秒數值。

1const a = new Date("2025-01-01");
2const b = new Date("2025-01-10");
3
4console.log(a < b);   // true
5console.log(a > b);   // false

• 如果你想判斷日期先後，不需要額外轉換。可以直接用比較運算子進行比較。

操作時間戳記（毫秒數）

Date 可以與毫秒數（時間戳記）互相轉換。這種格式經常用於 API 或資料庫整合。

1const now = Date.now();
2console.log(now);
3
4const date = new Date(now);
5console.log(date);

• Date.now() 回傳目前的毫秒數。當你想用數值儲存或比較時間時會非常有用。

將日期格式化為字串

直接顯示 Date 物件時，格式通常不一定符合你的需求。因此，你應該根據需求自己調整格式。

1const date = new Date("2025-01-01");
2
3const formatted = `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;
4console.log(formatted);

• 手動進行格式化，可以完全控制最終顯示的樣式。在實際開發中，通常會搭配套件來處理。

UTC 與本地時間的差異

Date 提供了同時操作本地時間和 UTC 的方法。在伺服器對接或跨國需求上，正確理解這差異很重要。

1const date = new Date();
2
3console.log(date.getHours());    // Local time (hours)
4console.log(date.getUTCHours()); // UTC time (hours)

• getUTC* 方法永遠是以 UTC 時間回傳。處理跨時區資料時要特別注意。

使用 Date 物件時的注意事項

Date 雖然方便，但也有不少需要留心的地方。特別是月分由 0 起算以及物件可變動，這兩點很容易引起 bug。

下方讓我們透過具體範例來看看 Date 是可變物件這一點產生的影響。

1const original = new Date("2025-01-01");
2const copy = new Date(original);
3
4copy.setDate(10);
5
6console.log(original);
7console.log(copy);

• 如果要保留原本的日期時間，一定要複製一份。僅僅知道這一點就能幫助你避免意外的 bug。

Date 難以處理的原因以及使用外部函式庫的判斷標準

Date 物件作為標準功能已經提供了足夠的功能，但在實際使用中仍有一些困難的情況。典型的問題包含月份與星期以 0 為起點、容易混淆本地時間和 UTC，以及物件本身是可變的。這些問題隨著日期處理的增加會導致更多錯誤。

Date 足以應付簡單的日期取得與比較，但進行較多的日期運算或顯示格式化時，程式碼的可讀性及維護性容易降低。

如果你有下列需求，可以考慮使用像是 dayjs 或 date-fns 這樣的輕量級日期函式庫。

• 你需要明確處理時區
• 你經常需要進行日期或區間的計算
• 你希望能靈活地變更顯示格式
• 你希望能以不可變的方式處理日期與時間

總結

Date 物件是 JavaScript 操作日期時間最基本的工具。只要理解其特性，正確地建立、取得、運算、與格式化，就能安全可靠地於實務上使用。

熟悉基礎後，根據需求再搭配日期套件是實用的作法。

您可以在我們的 YouTube 頻道上使用 Visual Studio Code 來跟隨上述文章一起學習。 請也查看我們的 YouTube 頻道。

YouTube Video