複合格式

發行項
08/20/2007

.NET Framework 複合格式功能會採用物件清單和複合格式字串做為輸入。複合格式字串是由混合索引替代符號 (Placeholder) 的固定文字所組成 (這些符號稱為對應至清單內物件的格式項目)。格式作業產生的結果字串是由原始固定文字所組成，這些固定文字混合了清單中代表物件的字串。

類似 Format、AppendFormat 的方法及 WriteLine 和 TextWriter.WriteLine 的某些多載可支援複合格式功能。String.Format 方法會產生格式化結果字串，而 AppendFormat 方法會將格式化結果字串附加到 StringBuilder 物件上，Console.WriteLine 方法則會將格式化結果字串顯示到主控台 (Console)，而 TextWriter.WriteLine 方法會將格式化結果字串寫入資料流或檔案。

複合格式字串

複合格式字串和物件清單會當做支援複合格式功能之方法的引數來使用。複合格式字串是由零個或更多段與一或多個格式項目混合的固定文字所組成，固字文字是您選擇的任何文字，而每個格式項目都會對應到清單內的一個物件或 boxed 結構。複合格式功能將會傳回新的結果字串，其中每一個格式項目都會由清單內對應物件的字串表示來取代。

請考量下列 Format 程式碼片段。

Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now)

string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now);

固定的文字為 "Name = " 和 ", hours = "。格式項目為 "{0}" (其索引為 0，且會對應至物件 myName) 及 "{1:hh}" (其索引為 1，且會對應至物件 DateTime.Now)。

格式項目語法

每個格式項目都會使用下列格式，並由下列元件所組成：

{ index[,alignment][:formatString]}

成對的大括號 ("{" 和 "}") 是必要的。

索引元件

強制的索引元件 (也稱為參數規範) 是用以識別物件清單中對應項目的數字 (從 0 開始)。也就是說，參數規範為 0 的格式項目會格式化清單中的第一個物件，而參數規範為 1 的格式項目會格式化清單中的第二個物件，依此類推。

多個格式項目可以藉由指定相同參數規範來參考物件清單中的相同項目。例如，您可以指定複合格式字串 (如："{0:X} {0:E} {0:N}") 來格式化十六進位、科學格式和數字格式的相同數值。

每個格式項目皆可參考清單內的任何物件。例如，如果有三個物件，您可以指定複合格式字串 (如："{1} {0} {2}") 來格式化第二個、第一個和第三個物件。不是格式項目所參考的物件會被忽略。如果參數規範指派超出物件清單範圍的項目，即會產生執行階段例外狀況。

對齊元件

選擇性對齊元件為帶正負號的整數 (Signed Integer)，它指示慣用的格式化欄位寬度。如果對齊的值小於格式化字串的長度，對齊會被忽略而使用格式化字串的長度當做欄位寬度。如果對齊為正數，欄位中的格式化資料會靠右對齊；如果對齊為負數，則會靠左對齊。如果填補有必要，則會使用泛空白字元 (White Space)。如果指定了對齊**，逗號即是必需的。

格式字串元件

選擇性的 formatString 元件是一個格式字串，適用於將格式化的物件型別。如果對應的物件為數值，則指定數值格式字串，而如果對應的物件為 DateTime 物件，則指定日期和時間格式字串，或者如果對應的物件為列舉值，則指定列舉型別格式字串。如果未指定 formatString，則會使用數值、日期和時間或列舉型別的一般 ("G") 格式規範。如果指定 formatString，則需要冒號。

逸出大括號

左右大括號會被解譯成格式項目的開頭與結尾。因此，您必須使用逸出序列 (Escape Sequence)，才能顯示字面上的左右大括號。請在固定文字中指定兩個左邊的大括號 ("{{")，以顯示一個左邊的大括號 ("{")，或者指定兩個右邊的大括號 ("}}") 來顯示一個右邊的大括號 ("}")。格式項目中的括號會以它們出現的順序依序解譯，但是不支援解譯巢狀大括號。

解譯逸出括號的方式，可能會造成無法預期的結果。例如，格式項目 "{{{0:D}}}" 原本是要顯示一個左邊大括號、一個格式化為十進位的數值和一個右邊大括號。然而，格式項目實際會以下列方式來解譯：

前面兩個左邊大括號 ("{{") 逸出，產生一個左邊大括號。
接下來的三個字元 ("{0:") 會解譯成格式項目的開頭。
再下一個字元 ("D") 可能解譯成十進位 (Decimal) 標準數值格式規範，但後面兩個逸出的右邊大括號 ("}}") 會產生一個大括號。由於結果字串 ("D}") 並非標準的數值格式規範，因此，結果字串會被解譯成自訂格式字串，表示會顯示成常值字串 "D}"。
最後的大括號 ("}") 會被解譯成格式項目的結尾。
最後顯示的結果會是常值字串 "{D}"，而要進行格式化的數值則不會顯示出來。

撰寫程式碼時，能夠避免錯誤解譯逸出大括號和格式項目的方法，就是個別地格式化大括號和格式項目。也就是說，在第一個格式化作業中顯示常值的左邊大括號，在下一個作業中顯示格式項目的結果，接著在最終作業中顯示常值的右邊大括號。

處理順序

如果要格式化的值是 null (在 Visual Basic 中為 Nothing)，則會傳回空字串 ("")。

如果要格式化的型別將實作 ICustomFormatter 介面，則會呼叫 ICustomFormatter.Format 方法。

如果前面的步驟並未格式化型別，而型別實作 IFormattable 介面，則會呼叫 IFormattable.ToString 方法。

如果前面的步驟並未格式化型別，則會呼叫型別的 ToString 方法，而此方法是繼承自 Object 類別。

對齊會在已經執行前面的步驟之後套用。

程式碼範例

下列範例顯示一個使用複合格式建立的字串，和另一個使用物件的 ToString 方法建立的字串。這兩個型別的格式化產生相等結果。

Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM")

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");

假設目前日期是五月份的星期四，前面範例中兩個字串的值在美國英文文化特性中都是 Thursday May。

Console.WriteLine 會將同一個功能公開為 String.Format。這兩種方法唯一的差別在於，String.Format 會傳回結果當做字串，而 Console.WriteLine 則會將結果寫入至與 Console 物件關聯的輸出資料流。下列範例使用 Console.WriteLine 方法，將 MyInt 的值格式化為貨幣值。

Dim MyInt As Integer = 100
Console.WriteLine("{0:C}", MyInt)

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);

這個程式碼顯示 $100.00 到以美國英文做為目前文化特性的電腦的主控台。

下列範例示範多個物件的格式化，其中包括使用兩種不同方式來格式化一個物件。

Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now)

string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
      myName, DateTime.Now);

上述字串的輸出為 "Name = Fred, hours = 07, minutes = 23"，其中目前時間反映這些數字。

下列範例示範對齊在格式化中的用法。格式化的引數會放在兩個垂直線 (|) 字元之間以強調所產生的對齊。

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"
Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C }|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C }|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt); 
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);

前面的程式碼在美國英文文化特性的主控台上顯示如下。不同文化特性會顯示不同貨幣符號和分隔符號。

First Name = |          Fred|
Last Name = |         Opals|
Price = |           $100.00|
First Name = |Fred      |
Last Name = |Opals     |
Price = |$100.00   |

請參閱