C# TimeSpan 完全指南：屬性、方法、構造與實戰陷阱

TimeSpan 是什麼？

TimeSpan 表示一段**時間間隔**（持續時間），而非具體日期時間點。它精度達 100 納秒 (1 Tick = 0.1 微秒)，範圍約 ±2.9 億年。區別於 `DateTime` (時間點)，`TimeSpan` 支持加減乘除、比較、格式化等豐富操作。

核心屬性對比：成對出現的「部分」與「總量」

關鍵理解：

• Days、Hours... 表示**分解後的各段值** (如 1 天 25 小時 → Days=1, Hours=1)。
• TotalHours 等表示**整個間隔換算後的總值** (上例 TotalHours=49)。
• 無 TotalTicks 屬性，因 Ticks 本身就是總量 (長整數)。

構造函數全解析

// 解析字符串
TimeSpan.Parse("1.02:03:04");           // 標準格式: d.hh:mm:ss.fffffff
TimeSpan.ParseExact("01:02:03", "hh\\:mm\\:ss", null); // 自定義格式
TimeSpan.TryParse("abc", out _);        // 安全解析，不拋異常

// 比較
TimeSpan.Compare(t1, t2); // -1/0/1
t1.CompareTo(t2);         // 實例方法

實例方法

運算符重載
DateTime dt1 = new DateTime(2010, 1, 2, 8, 43, 35);
DateTime dt2 = new DateTime(2010, 1, 12, 8, 43, 34);

TimeSpan diff = dt2 - dt1; // dt2 晚於 dt1

// 結果分析
Console.WriteLine($"Days: {diff.Days}");             // 9
Console.WriteLine($"Hours: {diff.Hours}");           // 23
Console.WriteLine($"Minutes: {diff.Minutes}");       // 59
Console.WriteLine($"Seconds: {diff.Seconds}");       // 59
Console.WriteLine($"TotalDays: {diff.TotalDays}");   // 9.999988...
Console.WriteLine($"TotalHours: {diff.TotalHours}"); // 239.9997...
Console.WriteLine($"TotalMinutes: {diff.TotalMinutes}"); // 14399.98...
Console.WriteLine($"TotalSeconds: {diff.TotalSeconds}"); // 863999
Console.WriteLine($"Ticks: {diff.Ticks}");           // 8639990000000

// 驗證計算
// 9天23時59分59秒 = 9*86400 + 23*3600 + 59*60 + 59 = 863999 秒
// Ticks = 863999 * 10,000,000 = 8,639,990,000,000


常見陷阱與最佳實踐


陷阱
錯誤示例
正確做法

混淆部分屬性與總量屬性
`int hours = ts.Hours;` // 僅得 0-23
`double hours = ts.TotalHours;` // 得完整小時數
整數截斷導致精度丟失
`int mins = (int)ts.TotalMinutes;`
`double mins = ts.TotalMinutes;` 或 `long totalSecs = (long)ts.TotalSeconds;`
負 TimeSpan 格式化顯示異常
`(-TimeSpan.FromHours(1)).ToString()` → "-01:00:00"
用 `ts.Duration().ToString()` 獲取絕對值顯示，或自行處理符號
字符串解析格式不匹配
`TimeSpan.Parse("25:00")` 拋異常
`TimeSpan.Parse("1.01:00:00")` 或 `TimeSpan.FromHours(25)`
序列化問題
JSON.NET 默認序列化為對象 {Days,Hours...}
配置 `TimeSpanConverter` 序列化為 "hh:mm:ss" 或總秒數



.NET 6+ 新增功能

總結速查表

構造：優先用 `FromXxx` 靜態方法，語義清晰。
屬性：需要「總量」用 `TotalXxx` (Double)；需要「分解顯示」用 `Days/Hours...` (Int)。
運算：直接用 `+ - == > <` 運算符，代碼可讀性最高。
格式化：`ToString(@"hh\:mm\:ss")` 自定義顯示；注意轉義冒號。
解析：用 `TryParse` 避免異常；非標準格式用 `ParseExact`。
負值：`Duration()` 獲取絕對值；比較時負值小於正值。