Delphi DateUtils 相對時間計算：年月週日時分秒完整函數指南

DateUtils 精細時間分量提取函數大全

DateUtils 單元提供了極其豐富的時間分量提取函數，能將任意 TDateTime 拆解為年、月、週、日、時、分、秒、毫秒等多維度的相對位置。這對於日曆顯示、排程計算、統計分組等場景至關重要。

函數分類總覽

日期層級

• MonthOfTheYear：指定時間是當年第幾月（1-12）
• WeekOfTheYear / WeekOfTheMonth：當年第幾週 / 當月第幾週
• NthDayOfWeek：當月該週幾的第幾次出現
• DayOfTheYear / DayOfTheMonth / DayOfTheWeek：當年第幾天 / 月第幾天 / 週第幾天（1-7，週一為 1）
• SysUtils.DayOfWeek：傳統函數，週日為 1，算法不同

時間層級（時/分/秒/毫秒）

每個層級都提供五個維度的「第幾個」查詢：

• HourOfTheYear / Month / Week / Day：第幾個小時
• MinuteOfTheYear / Month / Week / Day / Hour：第幾分鐘
• SecondOfTheYear / Month / Week / Day / Hour / Minute：第幾秒
• MilliSecondOfTheYear / Month / Week / Day / Hour / Minute / Second：第幾毫秒

實戰代碼範例

uses DateUtils;

procedure TForm1.FormCreate(Sender: TObject);
var
  t: TDateTime;
  w: Word;
  c: Cardinal;
  i: Int64;
begin
  t := StrToDateTime('2024-05-20 11:22:33');

  // 日期層級
  w := MonthOfTheYear(t);        // 5
  w := WeekOfTheYear(t);         // 21
  w := WeekOfTheMonth(t);        // 3
  w := NthDayOfWeek(t);          // 3
  w := DayOfTheYear(t);          // 141
  w := DayOfTheMonth(t);         // 20
  w := DayOfTheWeek(t);          // 2 (週一)
  w := SysUtils.DayOfWeek(t);    // 2 (週一)

  // 小時層級
  w := HourOfTheYear(t);         // 3347
  w := HourOfTheMonth(t);        // 467
  w := HourOfTheWeek(t);         // 59
  w := HourOfTheDay(t);          // 11

  // 分鐘層級
  c := MinuteOfTheYear(t);       // 200842
  w := MinuteOfTheMonth(t);      // 28042
  w := MinuteOfTheWeek(t);       // 3562
  w := MinuteOfTheDay(t);        // 682
  w := MinuteOfTheHour(t);       // 22

  // 秒層級
  c := SecondOfTheYear(t);       // 12050553
  c := SecondOfTheMonth(t);      // 1682553
  c := SecondOfTheWeek(t);       // 213753
  c := SecondOfTheDay(t);        // 40953
  w := SecondOfTheHour(t);       // 1353
  w := SecondOfTheMinute(t);     // 33

  // 毫秒層級
  i := MilliSecondOfTheYear(t);  // 12050553000
  c := MilliSecondOfTheMonth(t); // 1682553000
  c := MilliSecondOfTheWeek(t);  // 213753000
  c := MilliSecondOfTheDay(t);   // 40953000
  c := MilliSecondOfTheHour(t);  // 1353000
  c := MilliSecondOfTheMinute(t); // 33000
  w := MilliSecondOfTheSecond(t); // 0
end;

返回類型與效能提示

常見應用場景

• 日曆控件：DayOfTheWeek 決定起始欄位，WeekOfTheMonth 決定行數
• 統計報表分組：WeekOfTheYear 做週報，MonthOfTheYear 做月報
• 排程觸發判斷：HourOfTheDay、MinuteOfTheHour 精確匹配執行時間
• 效能分析：MilliSecondOfTheSecond 計算耗時

掌握這套函數體系，能讓時間維度的業務邏輯表達更直觀、代碼更簡潔，避免手動計算帶來的邊界錯誤。