複合格式化 AppendFormat 字元

文章目錄

• 複合格式字串
• 格式項文法
• 程式碼範例

.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），則返回Null 字元串 ("")。

如果要格式化的類型實現 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   |