在 .NET 开发中，除了 DateTime 表示具体时间点，TimeSpan 是我们常用的另一个结构，用于表示两个时间点之间的"间隔"或"持续时间"。
无论是倒计时、超时判断、定时逻辑，还是两个事件的间隔计算，TimeSpan 都扮演着关键角色。
一、TimeSpan 是什么？
public struct TimeSpan : IComparable, IComparable<TimeSpan>, IEquatable<TimeSpan>, IFormattable表示一个时间段或时间长度，可以是正值（向未来）、负值（向过去），例如：
-
30 分钟
-
-2 小时
-
3 天 5 小时
TimeSpan 不是时间点，而是两个时间点之间的差。
二、构造 TimeSpan
1. 通过构造函数（手动填写）
TimeSpan span1 = new TimeSpan(1, 2, 30); // 1小时 2分钟 30秒
TimeSpan span2 = new TimeSpan(5, 12, 30, 45); // 5天 12小时 30分 45秒2. 推荐方式：通过静态方法创建
TimeSpan fromHours = TimeSpan.FromHours(1.5); // 1 小时 30 分
TimeSpan fromMinutes = TimeSpan.FromMinutes(45); // 45 分钟
TimeSpan fromSeconds = TimeSpan.FromSeconds(10); // 10 秒
TimeSpan fromDays = TimeSpan.FromDays(2); // 2 天
TimeSpan fromMilliseconds = TimeSpan.FromMilliseconds(500); // 500 毫秒三、从 DateTime 获取 TimeSpan
DateTime start = new DateTime(2025, 8, 7, 9, 0, 0);
DateTime end = new DateTime(2025, 8, 7, 12, 30, 0);
TimeSpan diff = end - start; // 时间差
Console.WriteLine(diff); // 03:30:00也可以和当前时间对比：
TimeSpan ago = DateTime.Now - start;四、TimeSpan 的组成部分
TimeSpan span = new TimeSpan(1, 12, 30, 45, 500); // 1天12小时30分45秒500毫秒| 属性 | 类型 | 示例值 | 说明 |
|---|---|---|---|
Days |
int | 1 | 天数部分 |
Hours |
int | 12 | 小时部分 |
Minutes |
int | 30 | 分钟部分 |
Seconds |
int | 45 | 秒数部分 |
Milliseconds |
int | 500 | 毫秒部分 |
Ticks |
long | - | 总 Tick 数（1 Tick = 100ns） |
TotalDays |
double | 1.521 | 总天数（含小数） |
TotalHours |
double | 36.5 | 总小时 |
TotalMinutes |
double | 2190 | 总分钟 |
TotalSeconds |
double | 131400 | 总秒数 |
TotalMilliseconds |
double | 131400500 | 总毫秒数 |
五、加减操作
1. TimeSpan 与 DateTime 相加减
DateTime now = DateTime.Now;
DateTime later = now + TimeSpan.FromMinutes(10);
DateTime earlier = now - TimeSpan.FromHours(1);2. TimeSpan 与 TimeSpan 相加减
TimeSpan a = TimeSpan.FromMinutes(30);
TimeSpan b = TimeSpan.FromMinutes(45);
TimeSpan total = a + b; // 1小时15分
TimeSpan diff = a - b; // -15分钟六、比较 TimeSpan
TimeSpan a = TimeSpan.FromHours(1);
TimeSpan b = TimeSpan.FromMinutes(90);
bool isShorter = a < b; // true
bool isEqual = a == b; // false
int result = TimeSpan.Compare(a, b); // -1 表示 a 小于 b七、格式化输出
默认格式
TimeSpan span = new TimeSpan(1, 2, 3);
Console.WriteLine(span); // 输出 "01:02:03"自定义格式
TimeSpan span = new TimeSpan(1, 2, 3);
string custom = span.ToString(@"hh\:mm\:ss"); // "01:02:03"
string full = span.ToString(@"d\.hh\:mm\:ss"); // "0.01:02:03"
\:是转义字符，用于保留冒号，否则会报错。
八、解析字符串为 TimeSpan
TimeSpan t1 = TimeSpan.Parse("02:30:00");
bool success = TimeSpan.TryParse("not valid", out TimeSpan t2); // 不抛异常九、实际开发常用场景
| 场景 | 示例 |
|---|---|
| 计算两个时间差 | TimeSpan diff = end - start; |
| 判断是否过期 | if (DateTime.Now - created > TimeSpan.FromMinutes(30)) |
| 倒计时 | TimeSpan left = deadline - DateTime.Now; |
| 格式化显示 | span.ToString(@"hh\:mm\:ss") |
| 定时触发逻辑 | yield return new WaitForSeconds((float)span.TotalSeconds); |
十、小结
| 项目 | 说明 |
|---|---|
| 类型 | System.TimeSpan |
| 表示 | 时间间隔（可为负） |
| 构造 | 构造函数 或 TimeSpan.FromXxx() |
| 单位 | Tick（100 纳秒） |
| 精度 | 毫秒 ~ 纳秒 |
| 常用于 | 时间差计算、倒计时、调度逻辑 |
🕒 十一、常见成员总结
TimeSpan ts = new TimeSpan(1, 2, 3, 4, 567); // 1天2小时3分4秒567毫秒🧮 1. Days
返回时间间隔中的 "天"部分。
int days = ts.Days; // 1⏰ 2. Hours
返回除去天数后的 "小时"部分。
int hours = ts.Hours; // 2⏱️ 3. Minutes
返回除天和小时以外的 "分钟"部分。
int minutes = ts.Minutes; // 3🕐 4. Seconds
返回除天、小时、分钟之外的 "秒"部分。
int seconds = ts.Seconds; // 4🧩 5. Milliseconds
返回时间间隔中的 "毫秒"部分。
int ms = ts.Milliseconds; // 567📏 6. TotalDays
返回 总天数，包括小数部分。
double totalDays = ts.TotalDays; // 1.085...📘 7. TotalHours
返回 总小时数。
double totalHours = ts.TotalHours; // 26.085...📗 8. TotalMinutes
返回 总分钟数。
double totalMinutes = ts.TotalMinutes; // 1565.085...📙 9. TotalSeconds
返回 总秒数。
double totalSeconds = ts.TotalSeconds; // 93904.567📕 10. TotalMilliseconds
返回 总毫秒数。
double totalMilliseconds = ts.TotalMilliseconds; // 93904567🔤 11. ToString()
格式化为 标准字符串。
string str = ts.ToString(); // "1.02:03:04.567"