System.TimeSpan 結構

發行項
01/08/2024

本文提供此 API 參考文件的補充備註。

TimeSpan物件代表時間間隔（時間的持續時間或經過的時間），測量為正數或負數天、小時、分鐘、秒和秒分數。結構 TimeSpan 也可以用來代表一天的時間，但只有當時間與特定日期無關時。否則， DateTime 應該改用或 DateTimeOffset 結構。（如需使用 TimeSpan 結構反映一天時間的詳細資訊，請參閱選擇 DateTime、DateTimeOffset、TimeSpan 和 TimeZoneInfo。）

注意

值 TimeSpan 代表時間間隔，而且可以表示為特定天數、小時、分鐘、秒和毫秒。因為它代表一般間隔，而不參考特定的起點或終點，所以不能以年和月來表示，這兩者都有可變數。它與 DateTime 值不同，該值代表日期和時間，而不參考特定時區，或 DateTimeOffset 代表特定時間刻度的值。

結構用來測量持續時間的最大時間 TimeSpan 單位是一天。時間間隔是以天為單位來測量一致性，因為較大的時間單位天數，例如月和年，會有所不同。

物件的值 TimeSpan 是等於所表示時間間隔的刻度數。刻度等於 100 奈秒，或每秒 1 千萬分之一。物件的值 TimeSpan 範圍可以從到 TimeSpan.MinValue TimeSpan.MaxValue。

具現化 TimeSpan 值

您可以透過數種方式具現化 TimeSpan 值：

藉由呼叫其隱含無參數建構函式。這會建立值為 TimeSpan.Zero的物件，如下列範例所示。

TimeSpan interval = new TimeSpan();
Console.WriteLine(interval.Equals(TimeSpan.Zero));    // Displays "True".

let interval = TimeSpan()
printfn $"{interval.Equals TimeSpan.Zero}"    // Displays "True".

Dim interval As New TimeSpan()
Console.WriteLine(interval.Equals(TimeSpan.Zero))     ' Displays "True".

藉由呼叫其中一個明確的建構函式。下列範例會將 TimeSpan 值初始化為指定的小時、分和秒數。

TimeSpan interval = new TimeSpan(2, 14, 18);
Console.WriteLine(interval.ToString());              

// Displays "02:14:18".

let interval = TimeSpan(2, 14, 18)
printfn $"{interval}"              

// Displays "02:14:18".

Dim interval As New TimeSpan(2, 14, 18)
Console.WriteLine(interval.ToString())                ' Displays "02:14:18".

呼叫方法或執行傳回 TimeSpan 值的作業。例如，您可以具現化代表兩個 TimeSpan 日期和時間值之間間隔的值，如下列範例所示。

DateTime departure = new DateTime(2010, 6, 12, 18, 32, 0);
DateTime arrival = new DateTime(2010, 6, 13, 22, 47, 0);
TimeSpan travelTime = arrival - departure;  
Console.WriteLine("{0} - {1} = {2}", arrival, departure, travelTime);      

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

let departure = DateTime(2010, 6, 12, 18, 32, 0)
let arrival = DateTime(2010, 6, 13, 22, 47, 0)
let travelTime = arrival - departure  
printfn $"{arrival} - {departure} = {travelTime}"

// The example displays the following output:
//       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

Dim departure As DateTime = #06/12/2010 6:32PM#
Dim arrival As DateTime = #06/13/2010 10:47PM#
Dim travelTime As TimeSpan = arrival - departure
Console.WriteLine("{0} - {1} = {2}", arrival, departure, travelTime)
' The example displays the following output:
'       6/13/2010 10:47:00 PM - 6/12/2010 6:32:00 PM = 1.04:15:00

您也可以以此方式將物件初始化 TimeSpan 為零時間值，如下列範例所示。

Random rnd = new Random();

TimeSpan timeSpent = TimeSpan.Zero;

timeSpent += GetTimeBeforeLunch();
timeSpent += GetTimeAfterLunch();

Console.WriteLine("Total time: {0}", timeSpent);

TimeSpan GetTimeBeforeLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

TimeSpan GetTimeAfterLunch()
{
    return new TimeSpan(rnd.Next(3, 6), 0, 0);
}

// The example displays output like the following:
//        Total time: 08:00:00

open System

let rnd = Random()

let getTimeBeforeLunch () =
    TimeSpan(rnd.Next(3, 6), 0, 0)

let getTimeAfterLunch() =
    TimeSpan(rnd.Next(3, 6), 0, 0)

do
    let timeSpent = TimeSpan.Zero

    let timeSpent = timeSpent + getTimeBeforeLunch ()
    let timeSpent = timeSpent + getTimeAfterLunch ()

    printfn $"Total time: {timeSpent}"


// The example displays output like the following:
//        Total time: 08:00:00

Module Example
   Dim rnd As New Random()
   
   Public Sub Main()
      Dim timeSpent As TimeSpan = TimeSpan.Zero

      timeSpent += GetTimeBeforeLunch()
      timeSpent += GetTimeAfterLunch()

      Console.WriteLine("Total time: {0}", timeSpent)
   End Sub
   
   Private Function GetTimeBeforeLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
   
   Private Function GetTimeAfterLunch() As TimeSpan
      Return New TimeSpan(rnd.Next(3, 6), 0, 0)
   End Function
End Module
' The example displays output like the following:
'       Total time: 08:00:00

TimeSpan值是由、 DateTimeOffset和結構的算術運算元和TimeSpan方法DateTime所傳回。

藉由剖析值的字串表示 TimeSpan 。您可以使用 Parse 和 TryParse 方法，將包含時間間隔的 TimeSpan 字串轉換成值。下列範例會 Parse 使用方法，將字串 TimeSpan 陣列轉換成值。

string[] values = { "12", "31.", "5.8:32:16", "12:12:15.95", ".12"};
foreach (string value in values)
{
   try {
      TimeSpan ts = TimeSpan.Parse(value);
      Console.WriteLine("'{0}' --> {1}", value, ts);
   }
   catch (FormatException) {
      Console.WriteLine("Unable to parse '{0}'", value);
   }
   catch (OverflowException) {
      Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value);
   }   
}

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

let values = [| "12"; "31."; "5.8:32:16"; "12:12:15.95"; ".12" |]
for value in values do
    try
        let ts = TimeSpan.Parse value
        printfn $"'{value}' --> {ts}"
    with 
    | :? FormatException ->
        printfn $"Unable to parse '{value}'"
    | :? OverflowException ->
        printfn $"'{value}' is outside the range of a TimeSpan."

// The example displays the following output:
//       '12' --> 12.00:00:00
//       Unable to parse '31.'
//       '5.8:32:16' --> 5.08:32:16
//       '12:12:15.95' --> 12:12:15.9500000
//       Unable to parse '.12'

Dim values() As String = {"12", "31.", "5.8:32:16", "12:12:15.95", ".12"}
For Each value As String In values
    Try
        Dim ts As TimeSpan = TimeSpan.Parse(value)
        Console.WriteLine("'{0}' --> {1}", value, ts)
    Catch e As FormatException
        Console.WriteLine("Unable to parse '{0}'", value)
    Catch e As OverflowException
        Console.WriteLine("'{0}' is outside the range of a TimeSpan.", value)
    End Try
Next
' The example displays the following output:
'       '12' --> 12.00:00:00
'       Unable to parse '31.'
'       '5.8:32:16' --> 5.08:32:16
'       '12:12:15.95' --> 12:12:15.9500000
'       Unable to parse '.12'

此外，您可以呼叫 ParseExact 或 TryParseExact 方法，定義要剖析和轉換成TimeSpan值的輸入字串精確格式。

對 TimeSpan 值執行作業

您可以使用和運算符，或呼叫 Add 和 Subtraction Subtract 方法來加入和減去持續時間Addition。您也可以呼叫 Compare、 CompareTo和 Equals 方法來比較兩個時間持續時間。結構 TimeSpan 也包含 Duration 和 Negate 方法，可將時間間隔轉換為正值和負值。

值的範圍TimeSpan是 MinValue 。MaxValue

格式化 TimeSpan 值

TimeSpan值可以表示為 [-]d。hh：mm：ss。ff，其中選擇性減號表示負時間間隔，d 元件為天，hh 是以 24 小時製為單位的小時，mm 為分鐘，ss 為秒，而 ff 為秒的分數。也就是說，時間間隔是由沒有一天時間的正數或負數天所組成，或包含一天時間的天數，或只包含一天的時間。

從 .NET Framework 4 開始，結構 TimeSpan 透過方法 ToString 的多載支援區分文化特性的格式，以將值轉換成 TimeSpan 其字串表示。默認 TimeSpan.ToString() 方法會使用與舊版 .NET Framework 中的傳回值完全相同的不變異格式，傳回時間間隔。多 TimeSpan.ToString(String) 載可讓您指定格式字串，以定義時間間隔的字串表示。多 TimeSpan.ToString(String, IFormatProvider) 載可讓您指定格式字串，以及其格式慣例用來建立時間間隔字串表示的文化特性。 TimeSpan 支援標準和自定義格式字串。（如需詳細資訊，請參閱標準 TimeSpan 格式字串和自訂 TimeSpan 格式字串。）不過，只有標準格式字串會區分文化特性。

還原舊版 TimeSpan 格式

在某些情況下，在 .NET Framework 3.5 和舊版中成功格式化 TimeSpan 值的程序代碼在 .NET Framework 4 中會失敗。這在程式代碼中最常呼叫 <TimeSpan_LegacyFormatMode> 專案方法，以 TimeSpan 格式化格式字串的值。下列範例成功格式化 TimeSpan .NET Framework 3.5 和舊版中的值，但在 .NET Framework 4 和更新版本中擲回例外狀況。請注意，它會嘗試使用不支援的格式規範來格式化 TimeSpan 值，這在 .NET Framework 3.5 和舊版中會被忽略。

ShowFormattingCode();
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

Console.WriteLine("---");

ShowParsingCode();
// Output:
//       000000006 --> 6.00:00:00

void ShowFormattingCode()
{
    TimeSpan interval = new TimeSpan(12, 30, 45);
    string output;
    try
    {
        output = String.Format("{0:r}", interval);
    }
    catch (FormatException)
    {
        output = "Invalid Format";
    }
    Console.WriteLine(output);
}

void ShowParsingCode()
{
    string value = "000000006";
    try
    {
        TimeSpan interval = TimeSpan.Parse(value);
        Console.WriteLine("{0} --> {1}", value, interval);
    }
    catch (FormatException)
    {
        Console.WriteLine("{0}: Bad Format", value);
    }
    catch (OverflowException)
    {
        Console.WriteLine("{0}: Overflow", value);
    }
}

let showFormattingCode () =
    let interval = TimeSpan(12, 30, 45)
    try
        $"{interval:r}"
    with :? FormatException ->
        "Invalid Format"
    |> printfn "%s"

let showParsingCode () =
    let value = "000000006"
    try
        let interval = TimeSpan.Parse value
        printfn $"{value} --> {interval}"
    with
    | :? FormatException ->
        printfn $"{value}: Bad Format"
    | :? OverflowException ->
        printfn $"{value}: Overflow"

showFormattingCode ()
// Output from .NET Framework 3.5 and earlier versions:
//       12:30:45
// Output from .NET Framework 4:
//       Invalid Format    

printfn "---"

showParsingCode ()
// Output:
//       000000006 --> 6.00:00:00

Dim interval As New TimeSpan(12, 30, 45)
Dim output As String
Try
    output = String.Format("{0:r}", interval)
Catch e As FormatException
    output = "Invalid Format"
End Try
Console.WriteLine(output)
' Output from .NET Framework 3.5 and earlier versions:
'       12:30:45
' Output from .NET Framework 4:
'       Invalid Format

如果您無法修改程式代碼，您可以使用下列其中一種方式來還原值的舊版格式 TimeSpan 設定：

藉由建立包含 <TimeSpan_LegacyFormatMode> 專案的組態檔。將這個項目的 enabled 屬性設定為 true 會根據每個應用程式還原舊版 TimeSpan 格式設定。

當您建立應用程式域時，設定「NetFx40_TimeSpanLegacyFormatMode」相容性參數。這會啟用個別應用程式域的舊版 TimeSpan 格式設定。下列範例會建立使用舊版 TimeSpan 格式的應用程式域。

using System;

public class Example2
{
    public static void Main()
    {
        AppDomainSetup appSetup = new AppDomainSetup();
        appSetup.SetCompatibilitySwitches(new string[] { "NetFx40_TimeSpanLegacyFormatMode" });
        AppDomain legacyDomain = AppDomain.CreateDomain("legacyDomain",
                                                        null, appSetup);
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe");
    }
}

open System

let appSetup = AppDomainSetup()
appSetup.SetCompatibilitySwitches [| "NetFx40_TimeSpanLegacyFormatMode" |]
let legacyDomain = AppDomain.CreateDomain("legacyDomain", null, appSetup)
legacyDomain.ExecuteAssembly "ShowTimeSpan.exe" |> ignore

Module Example3
    Public Sub Main()
        Dim appSetup As New AppDomainSetup()
        appSetup.SetCompatibilitySwitches({"NetFx40_TimeSpanLegacyFormatMode"})
        Dim legacyDomain As AppDomain = AppDomain.CreateDomain("legacyDomain",
                                                             Nothing, appSetup)
        legacyDomain.ExecuteAssembly("ShowTimeSpan.exe")
    End Sub
End Module

當下列程式代碼在新的應用程式域中執行時，它會還原為舊版 TimeSpan 格式設定行為。

using System;

public class Example3
{
   public static void Main()
   {
      TimeSpan interval = DateTime.Now - DateTime.Now.Date;
      string msg = String.Format("Elapsed Time Today: {0:d} hours.",
                                 interval);
      Console.WriteLine(msg);
   }
}
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

open System

let interval = DateTime.Now - DateTime.Now.Date
printfn $"Elapsed Time Today: {interval:d} hours."
// The example displays the following output:
//       Elapsed Time Today: 01:40:52.2524662 hours.

Module Example4
    Public Sub Main()
        Dim interval As TimeSpan = Date.Now - Date.Now.Date
        Dim msg As String = String.Format("Elapsed Time Today: {0:d} hours.",
                                         interval)
        Console.WriteLine(msg)
    End Sub
End Module
' The example displays output like the following:
'       Elapsed Time Today: 01:40:52.2524662 hours.

共用方式為

System.TimeSpan 結構

具現化 TimeSpan 值

對 TimeSpan 值執行作業

格式化 TimeSpan 值

還原舊版 TimeSpan 格式

其他資源