自訂 TimeSpan 格式字串

發行項
05/22/2023

TimeSpan 格式字串會定義從格式化作業產生之 TimeSpan 值的字串表示。自訂格式字串會由一或多個自訂的 TimeSpan 格式規範搭配任意數目的常值字元所組成。任何字串只要不是標準 TimeSpan 格式字串，就會解譯為自訂的 TimeSpan 格式字串。

重要

自訂 TimeSpan 格式規範不包含預留位置分隔符號，例如分隔天與小時、小時與分鐘或是秒與小數秒的符號。相反地，這些符號必須包含在自訂格式字串中作為字串常值。例如，"dd\.hh\:mm" 會定義句號 (.) 作為天與小時之間的分隔符號，並定義冒號 (:) 作為小時與分鐘之間的分隔符號。

自訂 TimeSpan 格式規範也不包括讓您區分正負時間間隔的正負號。若要包括正負號，您必須使用條件邏輯建構格式字串。其他字元一節中會提供範例。

產生 TimeSpan 值的字串表示時，會藉由呼叫 TimeSpan.ToString 方法的多載，以及藉由支援複合格式設定的方法 (例如 String.Format)，來產生。如需詳細資訊，請參閱格式化類型和複合格式設定。下列範例說明如何在格式設定作業中使用自訂格式自串。

using System;

public class Example
{
   public static void Main()
   {
      TimeSpan duration = new TimeSpan(1, 12, 23, 62);

      string output = null;
      output = "Time of Travel: " + duration.ToString("%d") + " days";
      Console.WriteLine(output);
      output = "Time of Travel: " + duration.ToString(@"dd\.hh\:mm\:ss");
      Console.WriteLine(output);

      Console.WriteLine("Time of Travel: {0:%d} day(s)", duration);
      Console.WriteLine("Time of Travel: {0:dd\\.hh\\:mm\\:ss} days", duration);
   }
}
// The example displays the following output:
//       Time of Travel: 1 days
//       Time of Travel: 01.12:24:02
//       Time of Travel: 1 day(s)
//       Time of Travel: 01.12:24:02 days

Module Example
    Public Sub Main()
        Dim duration As New TimeSpan(1, 12, 23, 62)

        Dim output As String = Nothing
        output = "Time of Travel: " + duration.ToString("%d") + " days"
        Console.WriteLine(output)
        output = "Time of Travel: " + duration.ToString("dd\.hh\:mm\:ss")
        Console.WriteLine(output)

        Console.WriteLine("Time of Travel: {0:%d} day(s)", duration)
        Console.WriteLine("Time of Travel: {0:dd\.hh\:mm\:ss} days", duration)
    End Sub
End Module
' The example displays the following output:
'       Time of Travel: 1 days
'       Time of Travel: 01.12:24:02
'       Time of Travel: 1 day(s)
'       Time of Travel: 01.12:24:02 days

TimeSpan.ParseExact 和 TimeSpan.TryParseExact 方法也會使用自訂 TimeSpan 格式字串，以定義剖析作業所需的輸入字串格式。 (透過剖析，可將值的字串表示方式轉換為該值。) 以下範例說明在剖析作業中使用標準格式字串。

using System;

public class Example
{
   public static void Main()
   {
      string value = null;
      TimeSpan interval;

      value = "6";
      if (TimeSpan.TryParseExact(value, "%d", null, out interval))
         Console.WriteLine("{0} --> {1}", value, interval.ToString("c"));
      else
         Console.WriteLine("Unable to parse '{0}'", value);

      value = "16:32.05";
      if (TimeSpan.TryParseExact(value, @"mm\:ss\.ff", null, out interval))
         Console.WriteLine("{0} --> {1}", value, interval.ToString("c"));
      else
         Console.WriteLine("Unable to parse '{0}'", value);

      value= "12.035";
      if (TimeSpan.TryParseExact(value, "ss\\.fff", null, out interval))
         Console.WriteLine("{0} --> {1}", value, interval.ToString("c"));
      else
         Console.WriteLine("Unable to parse '{0}'", value);
   }
}
// The example displays the following output:
//       6 --> 6.00:00:00
//       16:32.05 --> 00:16:32.0500000
//       12.035 --> 00:00:12.0350000

Module Example
    Public Sub Main()
        Dim value As String = Nothing
        Dim interval As TimeSpan

        value = "6"
        If TimeSpan.TryParseExact(value, "%d", Nothing, interval) Then
            Console.WriteLine("{0} --> {1}", value, interval.ToString("c"))
        Else
            Console.WriteLine("Unable to parse '{0}'", value)
        End If

        value = "16:32.05"
        If TimeSpan.TryParseExact(value, "mm\:ss\.ff", Nothing, interval) Then
            Console.WriteLine("{0} --> {1}", value, interval.ToString("c"))
        Else
            Console.WriteLine("Unable to parse '{0}'", value)
        End If

        value = "12.035"
        If TimeSpan.TryParseExact(value, "ss\.fff", Nothing, interval) Then
            Console.WriteLine("{0} --> {1}", value, interval.ToString("c"))
        Else
            Console.WriteLine("Unable to parse '{0}'", value)
        End If
    End Sub
End Module
' The example displays the following output:
'       6 --> 6.00:00:00
'       16:32.05 --> 00:16:32.0500000
'       12.035 --> 00:00:12.0350000

下表描述自訂日期和時間的格式規範。

格式規範	描述	範例
"d"、"%d"	時間間隔中的完整天數。詳細資訊："d" 自訂格式規範。	`new TimeSpan(6, 14, 32, 17, 685):` `%d` --> "6" `d\.hh\:mm` --> "6.14:32"
"dd"-"dddddddd"	時間間隔中的完整天數，視需要填補前置零。詳細資訊："dd"-"dddddddd" 自訂格式規範。	`new TimeSpan(6, 14, 32, 17, 685):` `ddd` --> "006" `dd\.hh\:mm` --> "06.14:32"
"h"、"%h"	時間間隔中未計入天數部分的完整時數。單一位數的小時數前面不會加上零。詳細資訊："h" 自訂格式規範。	`new TimeSpan(6, 14, 32, 17, 685):` `%h` --> "14" `hh\:mm` --> "14:32"
"hh"	時間間隔中未計入天數部分的完整時數。一位數的小時有前置零。詳細資訊："hh" 自訂格式規範。	`new TimeSpan(6, 14, 32, 17, 685):` `hh` --> "14" `new TimeSpan(6, 8, 32, 17, 685):` `hh` --> 08
"m"、"%m"	時間間隔中未納入時數或天數部分的完整分鐘數。單一位數的分鐘數前面不會加上零。詳細資訊："m" 自訂格式規範。	`new TimeSpan(6, 14, 8, 17, 685):` `%m` --> "8" `h\:m` --> "14:8"
"mm"	時間間隔中未納入時數或天數部分的完整分鐘數。一位數的分鐘有前置零。詳細資訊："mm" 自訂格式規範。	`new TimeSpan(6, 14, 8, 17, 685):` `mm` --> "08" `new TimeSpan(6, 8, 5, 17, 685):` `d\.hh\:mm\:ss` --> 6.08:05:17
"s"、"%s"	時間間隔中未納入時數、天數或分鐘數部分的完整秒數。單一位數的秒鐘數前面不會加上零。詳細資訊："s" 自訂格式規範。	`TimeSpan.FromSeconds(12.965)`: `%s` --> 12 `s\.fff` --> 12.965
"ss"	時間間隔中未納入時數、天數或分鐘數部分的完整秒數。一位數的秒有前置零。詳細資訊："ss" 自訂格式規範。	`TimeSpan.FromSeconds(6.965)`: `ss` --> 06 `ss\.fff` --> 06.965
"f"、"%f"	時間間隔中的十分之一秒。詳細資訊："f" 自訂格式規範。	`TimeSpan.FromSeconds(6.895)`: `f` --> 8 `ss\.f` --> 06.8
"ff"	時間間隔中的百分之一秒。詳細資訊："ff" 自訂格式規範。	`TimeSpan.FromSeconds(6.895)`: `ff` --> 89 `ss\.ff` --> 06.89
"fff"	時間間隔中的毫秒。詳細資訊："fff" 自訂格式規範。	`TimeSpan.FromSeconds(6.895)`: `fff` --> 895 `ss\.fff` --> 06.895
"ffff"	時間間隔中的萬分之一秒。詳細資訊："ffff" 自訂格式規範。	`TimeSpan.Parse("0:0:6.8954321")`: `ffff` --> 8954 `ss\.ffff` --> 06.8954
"fffff"	時間間隔中的十萬分之一秒。詳細資訊："fffff" 自訂格式規範。	`TimeSpan.Parse("0:0:6.8954321")`: `fffff` --> 89543 `ss\.fffff` --> 06.89543
"ffffff"	時間間隔中的百萬分之一秒。詳細資訊："ffffff" 自訂格式規範。	`TimeSpan.Parse("0:0:6.8954321")`: `ffffff` --> 895432 `ss\.ffffff` --> 06.895432
"fffffff"	時間間隔中的千萬分之一秒 (或小數刻度)。詳細資訊："fffffff" 自訂格式規範。	`TimeSpan.Parse("0:0:6.8954321")`: `fffffff` --> 8954321 `ss\.fffffff` --> 06.8954321
"F"、"%F"	時間間隔中的十分之一秒。如果數字為零，則不會顯示任何內容。詳細資訊："F" 自訂格式規範。	`TimeSpan.Parse("00:00:06.32")`: `%F`: 3 `TimeSpan.Parse("0:0:3.091")`: `ss\.F`: 03.
"FF"	時間間隔中的百分之一秒。不包含小數點後的零或兩位數都是零的數字。詳細資訊："FF" 自訂格式規範。	`TimeSpan.Parse("00:00:06.329")`: `FF`: 32 `TimeSpan.Parse("0:0:3.101")`: `ss\.FF`: 03.1
"FFF"	時間間隔中的毫秒。不包含小數點後的零。詳細資訊：	`TimeSpan.Parse("00:00:06.3291")`: `FFF`: 329 `TimeSpan.Parse("0:0:3.1009")`: `ss\.FFF`: 03.1
"FFFF"	時間間隔中的萬分之一秒。不包含小數點後的零。詳細資訊："FFFF" 自訂格式規範。	`TimeSpan.Parse("00:00:06.32917")`: `FFFFF`: 3291 `TimeSpan.Parse("0:0:3.10009")`: `ss\.FFFF`: 03.1
"FFFFF"	時間間隔中的十萬分之一秒。不包含小數點後的零。詳細資訊："FFFFF" 自訂格式規範。	`TimeSpan.Parse("00:00:06.329179")`: `FFFFF`: 32917 `TimeSpan.Parse("0:0:3.100009")`: `ss\.FFFFF`: 03.1
"FFFFFF"	時間間隔中的百萬分之一秒。不顯示小數點後的零。詳細資訊："FFFFFF" 自訂格式規範。	`TimeSpan.Parse("00:00:06.3291791")`: `FFFFFF`: 329179 `TimeSpan.Parse("0:0:3.1000009")`: `ss\.FFFFFF`: 03.1
"FFFFFFF"	時間間隔中的千萬分之一秒。不顯示小數點後的零或七位數都是零。詳細資訊："FFFFFFF" 自訂格式規範。	`TimeSpan.Parse("00:00:06.3291791")`: `FFFFFF`: 3291791 `TimeSpan.Parse("0:0:3.1900000")`: `ss\.FFFFFF`: 03.19
'string'	常值字串分隔符號。詳細資訊：其他字元。	`new TimeSpan(14, 32, 17):` `hh':'mm':'ss` --> "14:32:17"
\	逸出字元。詳細資訊：其他字元。	`new TimeSpan(14, 32, 17):` `hh\:mm\:ss` --> "14:32:17"
任意字元	其他任何未逸出字元都會解譯為自訂格式規範。詳細資訊：其他字元。	`new TimeSpan(14, 32, 17):` `hh\:mm\:ss` --> "14:32:17"

"d" 自訂格式規範

"d" 自訂格式規範會輸出 TimeSpan.Days 屬性的值，這代表時間間隔中的完整天數。它會輸出 TimeSpan 值中的完整天數，即使該值有多個位數也一樣。如果 TimeSpan.Days屬性的值為零，此規範就會輸出 "0"。

如果單獨使用 "d" 自訂格式規範，請指定 "%d"，以免被錯誤解譯為標準格式字串。下列範例提供說明。

TimeSpan ts1 = new TimeSpan(16, 4, 3, 17, 250);
Console.WriteLine(ts1.ToString("%d"));
// Displays 16

Dim ts As New TimeSpan(16, 4, 3, 17, 250)
Console.WriteLine(ts.ToString("%d"))
' Displays 16

下列範例說明如何使用 "d" 自訂格式規範。

TimeSpan ts2 = new TimeSpan(4, 3, 17);
Console.WriteLine(ts2.ToString(@"d\.hh\:mm\:ss"));

TimeSpan ts3 = new TimeSpan(3, 4, 3, 17);
Console.WriteLine(ts3.ToString(@"d\.hh\:mm\:ss"));
// The example displays the following output:
//       0.04:03:17
//       3.04:03:17

Dim ts2 As New TimeSpan(4, 3, 17)
Console.WriteLine(ts2.ToString("d\.hh\:mm\:ss"))

Dim ts3 As New TimeSpan(3, 4, 3, 17)
Console.WriteLine(ts3.ToString("d\.hh\:mm\:ss"))
' The example displays the following output:
'       0.04:03:17
'       3.04:03:17

自訂 TimeSpan 格式字串

"d" 自訂格式規範

"dd"-"dddddddd" 自訂格式規範

"h" 自訂格式規範

"hh" 自訂格式規範

"m" 自訂格式規範

"mm" 自訂格式規範

"s" 自訂格式規範

"ss" 自訂格式規範

"f" 自訂格式規範

"ff" 自訂格式規範

"fff" 自訂格式規範

"ffff" 自訂格式規範

"fffff" 自訂格式規範

"ffffff" 自訂格式規範

"fffffff" 自訂格式規範

"F" 自訂格式規範

"FF" 自訂格式規範

"FFF" 自訂格式規範

"FFFF" 自訂格式規範

"FFFFF" 自訂格式規範

"FFFFFF" 自訂格式規範

"FFFFFFF" 自訂格式規範

其他字元

另請參閱

意見反應

其他資源