複合格式化

.NET Framework 複合格式化功能使用對象清單和複合格式字元串作為輸入。複合格式字元串由固定文本和索引占位符混群組成，其中索引占位符稱為格式項，對應于清單中的對象。格式化操作産生的結果字元串由原始固定文本和清單中對象的字元串表示形式混群組成。

諸如 Format、AppendFormat 等方法以及 WriteLine 和 TextWriter.WriteLine 的某些重載支援複合格式化功能。String.Format 方法産生格式化的結果字元串，AppendFormat 方法将格式化的結果字元串追加到 StringBuilder 對象，Console.WriteLine 方法将格式化的結果字元串顯示到控制台，TextWriter.WriteLine 方法将格式化的結果字元串寫入流或檔案。

複合格式字元串

複合格式字元串和對象清單将用作支援複合格式化功能的方法的參數。複合格式字元串由零個或多個固定文本段與一個或多個格式項混群組成。固定文本是所選擇的任何字元串，并且每個格式項對應于清單中的一個對象或裝箱的結構。複合格式化功能傳回新的結果字元串，其中每個格式項都被清單中相應對象的字元串表示形式取代。

可考慮使用以下 Format 代碼段。

C#

複制代碼

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

固定文本為“Name = ”和“, hours = ”。格式項為“{0}”和“{1:hh}”，前者的索引為 0，對應于對象 myName，後者的索引為 1，對應于對象 DateTime.Now。

格式項文法

每個格式項都采用下面的形式并包含以下元件：

{ 索引[,對齊][:格式字元串]}

必須使用成對的大括号（“{”和“}”）。

索引元件

強制“索引”元件（也叫參數說明符）是一個從 0 開始的數字，可辨別對象清單中對應的項。 也就是說，參數說明符為 0 的格式項格式化清單中的第一個對象，參數說明符為 1 的格式項格式化清單中的第二個對象，依次類推。

通過指定相同的參數說明符，多個格式項可以引用對象清單中的同一個元素。例如，通過指定類似于“{0:X} {0:E} {0:N}”的複合格式字元串，可以将同一個數值格式化為十六進制、科學記數法和數字格式。

每個格式項都可以引用清單中的任一對象。例如，如果有三個對象，則可以通過指定類似于“{1} {0} {2}”的複合格式字元串來格式化第二、第一和第三個對象。格式項未引用的對象會被忽略。如果參數說明符指定了超出對象清單範圍的項，将導緻運作時異常。

對齊元件

可選的“對齊”元件是一個帶符号的整數，訓示首選的格式化字段寬度。如果“對齊”值小于格式化字元串的長度，“對齊”會被忽略，并且使用格式化字元串的長度作為字段寬度。如果“對齊”為正數，字段中的格式化資料為右對齊；如果“對齊”為負數，字段中的格式化資料為左對齊。 如果需要填充，則使用空白。如果指定“對齊”，就需要使用逗号。

格式字元串元件

可選的“格式字元串”元件是适合正在格式化的對象類型的格式字元串。 如果相應對象是數值，則指定數字格式字元串，如果相應對象是 DateTime 對象，則指定日期和時間格式字元串，或者如果相應對象是枚舉值，則指定枚舉格式字元串。如果不指定“格式字元串”，則對數字、日期和時間或者枚舉類型使用正常（“G”）格式說明符。 如果指定“格式說明符”，需要使用冒号。

轉義大括号

左大括号和右大括号被解釋為格式項的開始和結束。是以，必須使用轉義序列顯示文本左大括号或右大括号。在固定文本中指定兩個左大括号 ("{{") 以顯示一個左大括号 ("{")，或指定兩個右大括号 ("}}") 以顯示一個右大括号 ("}")。按照在格式項中遇到大括号的順序依次解釋它們。不支援解釋嵌套的大括号。

解釋轉義大括号的方式會導緻意外的結果。例如，考慮要顯示一個左大括号、一個格式化為十進制數的數值和一個右大括号的格式項“{{{0:D}}}”。但是，實際是按照以下方式解釋該格式項：

1. 前兩個左大括号 ("{{") 被轉義，生成一個左大括号。
2. 之後的三個字元 ("{0:") 被解釋為格式項的開始。
3. 下一個字元 ("D") 将被解釋為 Decimal 标準數值格式說明符，但後面的兩個轉義大括号 ("}}") 生成單個大括号。由于得到的字元串 ("D}") 不是标準數值格式說明符号，是以得到的字元串會被解釋為用于顯示字元串“D}”的自定義格式字元串。
4. 最後一個大括号 ("}") 被解釋為格式項的結束。
5. 顯示的最終結果是字元串“{D}”。不會顯示本來要格式化的數值。

在編寫代碼時，避免錯誤解釋轉義大括号和格式項的一種方法是單獨格式化大括号和格式項。也就是說，在第一個格式化操作中顯示文本左大括号，在下一操作中顯示格式項的結果，然後在最後一個操作中顯示文本右大括号。

處理順序

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

如果要格式化的類型實作 ICustomFormatter 接口，則調用 ICustomFormatter.Format 方法。

如果前面的步驟未格式化類型，并且該類型實作 IFormattable 接口，則調用 IFormattable.ToString 方法。

如果前面的步驟未格式化類型，則調用該類型的 ToString 方法（從 Object 類繼承而來）。

前面的步驟執行完畢之後應用對齊。

代碼示例

下面的示例顯示使用複合格式化建立的一個字元串和使用對象的 ToString 方法建立的另一個字元串。兩種格式化類型産生相同的結果。

C#

複制代碼

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 的值格式化為貨币值。

C#

複制代碼

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

此代碼在目前區域性為美國英語的計算機上，将 $100.00 顯示到控制台。

下面的示例說明格式化多個對象，包括用兩種不同的方式格式化一個對象。

C#

複制代碼

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

以上字元串的輸出是“Name = Fred, hours = 07, minutes = 23”，其中目前的時間反映了這些數字。

下列示例說明了對齊在格式化中的使用。格式化的參數放置在豎線字元 (|) 之間以突出顯示得到的對齊。

C#

複制代碼

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   |