简介

TimeSpan 是 .NET 中用于表示时间间隔或持续时间的重要结构体。它提供了丰富的方法和属性来处理时间跨度，从几毫秒到几百万天都可以精确表示。

概念与特性

TimeSpan 表示一个时间间隔（时间段），而不是具体的时间点。

与 DateTime 区别：

• DateTime 表示一个具体的时间点（例如：2025-09-18 08:00）。

• TimeSpan 表示一个时间间隔（例如：2 小时 30 分钟）。

创建 TimeSpan

构造函数

// 构造函数：TimeSpan(days, hours, minutes, seconds)
var span1 = new TimeSpan(1, 2, 30, 0); // 1天2小时30分0秒

// 构造函数：TimeSpan(hours, minutes, seconds)
var span2 = new TimeSpan(2, 30, 0);    // 2小时30分

静态工厂方法

推荐使用静态方法，可读性更高：

TimeSpan ts1 = TimeSpan.FromDays(1.5);       // 1.5天
TimeSpan ts2 = TimeSpan.FromHours(2.5);      // 2.5小时
TimeSpan ts3 = TimeSpan.FromMinutes(90);     // 90分钟
TimeSpan ts4 = TimeSpan.FromSeconds(45);     // 45秒
TimeSpan ts5 = TimeSpan.FromMilliseconds(500); // 500毫秒
TimeSpan ts6 = TimeSpan.FromTicks(5000);     // 5000 Ticks

解析字符串

TimeSpan ts = TimeSpan.Parse("1.02:30:00");  
// 格式：d.hh:mm:ss -> 1天2小时30分

或安全解析：

if (TimeSpan.TryParse("02:15", out var result))
    Console.WriteLine(result); // 02:15:00

常用属性

区别

• Days、Hours 等返回整数部分（对应分量）。

• TotalDays、TotalHours 等返回完整总量。

示例：

var ts = new TimeSpan(1, 2, 30, 0);
Console.WriteLine(ts.Days);        // 1
Console.WriteLine(ts.TotalHours);  // 26.5

运算操作

加减

var t1 = TimeSpan.FromHours(3);
var t2 = TimeSpan.FromMinutes(30);

TimeSpan sum = t1 + t2;  // 3:30:00
TimeSpan diff = t1 - t2; // 2:30:00

乘除

TimeSpan doubleTime = TimeSpan.FromMinutes(45) * 2; // 1:30:00
TimeSpan halfTime   = TimeSpan.FromHours(4) / 2;    // 2:00:00

C# 11 之前不支持直接乘除，需要用 TimeSpan.FromTicks() 手动计算。 （.NET 7 / C# 11 起支持 * / 运算符）

比较

TimeSpan ts1 = TimeSpan.FromHours(2);
TimeSpan ts2 = TimeSpan.FromMinutes(120); // 也是2小时

// 比较
bool isEqual = ts1 == ts2;                // true
bool isNotEqual = ts1 != ts2;             // false
bool isGreater = ts1 > TimeSpan.FromHours(1); // true
bool isLess = ts1 < TimeSpan.FromHours(3);    // true

// 比较方法
int compareResult = ts1.CompareTo(ts2);   // 0 (相等)
bool equals = ts1.Equals(ts2);            // true

取绝对值

var negative = TimeSpan.FromHours(-5);
var positive = negative.Duration(); // 05:00:00

取负值

var neg = -TimeSpan.FromMinutes(30); // -00:30:00

与 DateTime 配合

TimeSpan 常用于计算两个时间点的差值：

格式化输出

默认格式

标准格式

自定义格式

ToString 支持标准和自定义格式：

需要转义 : 和 .

常用静态字段

典型使用场景

定时任务/超时控制

统计程序耗时

实际应用示例

输出示例：

高级用法

自定义 TimeSpan 扩展方

注意事项和最佳实践

• 不可变性：TimeSpan 是值类型且不可变，所有操作都返回新的 TimeSpan 实例

• 精度考虑：TimeSpan 使用 ticks（100 纳秒）作为内部存储，提供高精度但需要注意浮点运算的精度问题

• 文化敏感性：解析和格式化 TimeSpan 时，注意当前线程的文化设置

• 性能考虑：对于高性能场景，考虑使用 Stopwatch 而不是 DateTime 减法来计算时间间隔

DateTime start = DateTime.Now;
// 模拟一些操作
System.Threading.Thread.Sleep(1500);
DateTime end = DateTime.Now;

TimeSpan elapsed = end - start;
Console.WriteLine($"执行耗时: {elapsed.TotalMilliseconds} ms");

DateTime tomorrow = DateTime.Now + TimeSpan.FromDays(1);

Console.WriteLine(ts.ToString()); // "1.02:30:00" (d.hh:mm:ss)

Console.WriteLine(ts.ToString("c"));     // 同上 (常数格式)
Console.WriteLine(ts.ToString("g"));     // 1:2:30:45.5 (常规短格式)
Console.WriteLine(ts.ToString("G"));     // 1:02:30:45.5000000 (常规长格式)

var ts = new TimeSpan(1, 2, 30, 45, 500);
Console.WriteLine(ts.ToString(@"hh:mm:ss"));        // 02:30:45
Console.WriteLine(ts.ToString(@"d.hh:mm:ss.fff")); // 1.02:30:45.500

var timeout = TimeSpan.FromSeconds(30);
var cts = new CancellationTokenSource(timeout);

var watch = System.Diagnostics.Stopwatch.StartNew();
// do work
watch.Stop();
Console.WriteLine(watch.Elapsed); // TimeSpan

using System;

class Program
{
    static void Main()
    {
        DateTime start = DateTime.Now;

        // 模拟任务
        System.Threading.Thread.Sleep(1200);

        DateTime end = DateTime.Now;
        TimeSpan span = end - start;

        Console.WriteLine($"耗时: {span.TotalMilliseconds} 毫秒");
        Console.WriteLine($"格式化: {span.ToString(@"hh:mm:ss.fff")}");
        Console.WriteLine($"天: {span.Days}, 小时: {span.Hours}, 总小时: {span.TotalHours:F2}");
    }
}

耗时: 1203.45 毫秒
格式化: 00:00:01.203
天: 0, 小时: 0, 总小时: 0.00

public static class TimeSpanExtensions
{
    public static string ToHumanReadableString(this TimeSpan timeSpan)
    {
        if (timeSpan.TotalDays >= 1)
            return $"{(int)timeSpan.TotalDays} 天 {timeSpan.Hours} 小时";
        
        if (timeSpan.TotalHours >= 1)
            return $"{(int)timeSpan.TotalHours} 小时 {timeSpan.Minutes} 分钟";
        
        if (timeSpan.TotalMinutes >= 1)
            return $"{(int)timeSpan.TotalMinutes} 分钟 {timeSpan.Seconds} 秒";
        
        if (timeSpan.TotalSeconds >= 1)
            return $"{(int)timeSpan.TotalSeconds} 秒";
        
        return $"{timeSpan.Milliseconds} 毫秒";
    }
}

// 使用扩展方法
TimeSpan ts = TimeSpan.FromHours(2.5);
Console.WriteLine(ts.ToHumanReadableString()); // 输出: 2 小时 30 分钟