复合格式设置

项目
03/06/2024

.NET 复合格式设置功能使用对象列表和复合格式字符串作为输入。复合格式字符串由固定文本和索引占位符混合组成，其中索引占位符称为格式项。这些格式项对应于列表中的对象。格式设置操作产生的结果字符串由原始固定文本和列表中对象的字符串表示形式混和组成。

重要

相较使用复合格式字符串，如果正在使用的语言及其版本支持，则可使用内插字符串。内插字符串包含内插表达式。每个内插表达式都使用表达式的值进行解析，并在分配字符串时包含在结果字符串中。有关详细信息，请参阅字符串内插（C# 参考）和内插字符串（Visual Basic 参考）。

以下方法支持复合格式设置功能：

String.Format，它返回格式化的结果字符串。
StringBuilder.AppendFormat，它将格式化的结果字符串追加到 StringBuilder 对象。
Console.WriteLine 方法的某些重载，它将格式化的结果字符串显示到控制台上。
TextWriter.WriteLine 方法的某些重载，它将格式化的结果字符串写入流或文件中。派生自 TextWriter 的类（如 StreamWriter 和 HtmlTextWriter）也共享此功能。
Debug.WriteLine(String, Object[])，它将格式化消息输出到跟踪侦听器。
Trace.TraceError(String, Object[])、Trace.TraceInformation(String, Object[]) 和 Trace.TraceWarning(String, Object[]) 方法，它们将格式化消息输出到跟踪侦听器。
TraceSource.TraceInformation(String, Object[]) 方法，它将信息性方法写入跟踪侦听器中。

复合格式字符串

复合格式字符串和对象列表将用作支持复合格式设置功能的方法的参数。复合格式字符串由零个或多个固定文本段与一个或多个格式项混和组成。固定文本是所选择的任何字符串，并且每个格式项对应于列表中的一个对象或装箱的结构。每个对象的字符串表示形式替换相应的格式项。

可考虑使用以下 Format 代码段：

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

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

固定文本为 Name = 和 , hours = 。格式项为 {0} 和 {1:hh}，前者的索引为 0，对应于对象 name，后者的索引为 1，对应于对象 DateTime.Now。

格式项语法

每个格式项都采用下面的形式并包含以下组件：

{index[,alignment][:formatString]}

必须使用成对的大括号（{ 和 }）。

索引组件

必需的索引组件（也叫参数说明符）是一个从 0 开始的数字，可标识对象列表中对应的项。也就是说，参数说明符为 0 的格式项会格式化列表中的第一个对象。参数说明符为 1 的格式项会格式化列表中的第二个对象，依次类推。下面的示例包括四个参数说明符，编号为 0 到 3，用于表示小于 10 的质数：

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

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

通过指定相同的参数说明符，多个格式项可以引用对象列表中的同一个元素。例如，通过指定“"0x{0:X} {0:E} {0:N}"”等复合格式字符串，可以将同一个数值设置为十六进制、科学记数法和数字格式，如下面的示例所示：

string multiple = string.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);

// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)

'The example displays the following output
'     0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

每个格式项都可以引用列表中的任一对象。例如，如果有三个对象，可以指定“{1} {0} {2}”等复合格式字符串，以设置第二个、第一个和第三个对象的格式。格式项未引用的对象会被忽略。如果参数说明符指定了超出对象列表范围的项，将引发运行时 FormatException。

对齐组件

可选的对齐组件是一个带符号的整数，指示首选的设置了格式的字段宽度。如果 alignment 值小于设置了格式的字符串的长度，alignment 将被忽略，并使用设置了格式的字符串的长度作为字段宽度。如果 alignment 为正数，字段中设置了格式的数据为右对齐；如果 alignment 为负数，字段中的设置了格式的数据为左对齐。如果需要填充，则使用空白。如果指定 alignment，则需要使用逗号。

下面的示例定义两个数组，一个包含雇员的姓名，另一个则包含雇员在两周内的工作小时数。复合格式字符串使 20 字符字段中的姓名左对齐，使 5 字符字段中的工作小时数右对齐。 “N1”标准格式字符串设置带有小数位的小时数格式。

string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                   "Ebenezer", "Francine", "George" };
decimal[] hours = { 40, 6.667m, 40.39m, 82,
                    40.333m, 80, 16.75m };

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");

for (int counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

// The example displays the following output:
//      Name                 Hours
//      
//      Adam                  40.0
//      Bridgette              6.7
//      Carla                 40.4
//      Daniel                82.0
//      Ebenezer              40.3
//      Francine              80.0
//      George                16.8

Dim names As String() = {"Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George"}

Dim hours As Decimal() = {40, 6.667D, 40.39D, 82,
                          40.333D, 80, 16.75D}

Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'The example displays the following output
'     Name                 Hours
'     
'     Adam                  40.0
'     Bridgette              6.7
'     Carla                 40.4
'     Daniel                82.0
'     Ebenezer              40.3
'     Francine              80.0
'     George                16.8

格式字符串组件

可选的 formatString 组件是适合正在设置格式的对象类型的格式字符串。可以指定：

如果相应对象是数值，则为标准或自定义数字格式字符串。
如果相应对象是 DateTime 对象，则为标准或自定义日期和时间格式字符串。
如果相应对象是枚举值，则为枚举格式字符串。

如果不指定 formatString，则对数字、日期和时间或者枚举类型使用常规（“G”）格式说明符。如果指定 formatString，则需要使用冒号。

下表列出了 .NET 类库中支持预定义的格式字符串集的类型或类型的类别，并提供指向列出了支持的格式字符串的文章的链接。字符串格式化是一个可扩展的机制，可使用该机制定义所有现有类型的新的格式字符串，并定义受应用程序定义的类型支持的格式字符串集。

有关详细信息，请参阅 IFormattable 和 ICustomFormatter 接口文章。

类型或类型类别	查看
日期和时间类型（DateTime，DateTimeOffset）	标准日期和时间格式字符串自定义日期和时间格式字符串
枚举类型（所有派生自 System.Enum 的类型）	枚举格式字符串
数值类型（BigInteger、Byte、Decimal、Double、Int16、Int32、Int64、SByte、Single、UInt16、 UInt32、UInt64）	标准数字格式字符串自定义数字格式字符串
Guid	Guid.ToString(String)
TimeSpan	标准 TimeSpan 格式字符串自定义 TimeSpan 格式字符串

转义大括号

左大括号和右大括号被解释为格式项的开始和结束。若要显示文本左大括号或右大括号，必须使用转义序列。在固定文本中指定两个左大括号 ({{) 以显示一个左大括号 ({)，或指定两个右大括号 (}}) 以显示一个右大括号 (})。

具有格式项的转义大括号在 .NET 和 .NET Framework 之间以不同的方式进行分析。

.NET

大括号可以围绕格式项进行转义。例如，假设格式项为 {{{0:D}}}，旨在显示左大括号、采用十进制数格式的数值和右大括号。该格式项的解释方式如下：

前两个左大括号 ({{) 被转义，生成一个左大括号。
之后的三个字符 ({0:) 被解释为格式项的开始。
下一个字符 (D) 解释为十进制标准数字格式说明符。
下一个大括号 (}) 解释为格式项的结束。
最后两个右大括号被转义，并生成一个右大括号。
显示的最终结果是字符串 {6324}。

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

按照在格式项中遇到大括号的顺序依次解释它们。不支持解释嵌套的大括号。

解释转义大括号的方式会导致意外的结果。例如，假设格式项为 {{{0:D}}}，旨在显示左大括号、采用十进制数格式的数值和右大括号。但是，该格式项的解释方式如下：

前两个左大括号 ({{) 被转义，生成一个左大括号。
之后的三个字符 ({0:) 被解释为格式项的开始。
下一个字符 (D) 将被解释为 Decimal 标准数值格式说明符，但后面的两个转义大括号 (}}) 生成单个大括号。由于得到的字符串 (D}) 不是标准数值格式说明符号，所以得到的字符串会被解释为用于显示文本字符串 D} 的自定义格式字符串。
最后一个大括号 (}) 被解释为格式项的结束。
显示的最终结果是字符串 {D}。不会显示本来要设置格式的数值。

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

在编写代码时，避免错误解释转义大括号和格式项的一种方法是单独设置大括号和格式项的格式。也就是说，在第一个格式操作中显示文本左大括号。在下一操作中显示格式项的结果，然后在最后一个操作中显示文本右大括号。下面的示例阐释了这种方法：

int value = 6324;
string output = string.Format("{0}{1:D}{2}",
                             "{", value, "}");
Console.WriteLine(output);

// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{0}{1:D}{2}",
                                     "{", value, "}")
Console.WriteLine(output)

'The example displays the following output:
'      {6324}

处理顺序

如果对复合格式设置方法的调用包括其值不为 null的IFormatProvider参数，则运行时会调用其 IFormatProvider.GetFormat 方法来请求 ICustomFormatter 实现。如果此方法可返回 ICustomFormatter 实现，那么它会在复合格式方法调用期间缓存。

如下所示，将参数列表中与格式项对应的每个值转换为字符串：

如果要设置格式的值为 null，则将返回空字符串 String.Empty。
如果 ICustomFormatter 实现可用，则运行时将调用其 Format 方法。运行时将格式项的 formatString 值（如果不存在则为 null）传递给方法。运行时还将 IFormatProvider 实现传递给该方法。如果对 ICustomFormatter.Format 方法的调用返回 null，则继续执行下一步骤。否则，将返回 ICustomFormatter.Format 调用的结果。
如果该值实现 IFormattable 接口，则调用此接口的 ToString(String, IFormatProvider) 方法。如果格式项中存在 formatString 值，则向方法传递该值。否则，传递 null。按如下方式确定 IFormatProvider 自变量：
- 对于数值，如果调用带非 null IFormatProvider 自变量的复合格式设置方法，则运行时从其 NumberFormatInfo 方法请求 IFormatProvider.GetFormat 对象。在以下情况下，使用当前区域性的 NumberFormatInfo 对象：无法提供该值、实际参数值为 null 或复合格式设置方法没有 IFormatProvider 形式参数。
- 对于日期和时间值，如果调用带非 null IFormatProvider 自变量的复合格式设置方法，则运行时从其 DateTimeFormatInfo 方法请求 IFormatProvider.GetFormat 对象。在以下情况下，改为使用当前区域性的 DateTimeFormatInfo 对象：
  - IFormatProvider.GetFormat 方法无法提供 DateTimeFormatInfo 对象。
  - 自变量的值为 null。
  - 复合格式设置方法没有 IFormatProvider 参数。
- 对于其他类型的对象，如果调用带 IFormatProvider 参数的复合格式设置方法，它的值会直接传递到 IFormattable.ToString 实现。否则，null 传递到 IFormattable.ToString 实现。
调用类型的无参数的 ToString 方法（该方法将重写 Object.ToString() 或继承其基类的行为）。在这种情况下，如果格式项中存在 formatString 组件指定的格式字符串，则将忽略该字符串。

前面的步骤执行完毕之后应用对齐。

代码示例

下面的示例显示使用复合格式设置创建的一个字符串和使用对象的 ToString 方法创建的另一个字符串。两种格式设置类型产生相同的结果。

string formatString1 = string.Format("{0:dddd MMMM}", DateTime.Now);
string formatString2 = DateTime.Now.ToString("dddd MMMM");

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

假定当前日期是五月的星期四，那么在美国英语区域性中上述示例中的两个字符串的值都是 Thursday May英语区域性。

Console.WriteLine 提供与 String.Format 相同的功能。这两种方法的唯一差异是 String.Format 将其结果作为字符串返回，而 Console.WriteLine 将结果写入与 Console 对象关联的输出流中。下面的示例使用 Console.WriteLine 方法将 myNumber 的值的格式设置为货币值：

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

// The example displays the following output
// if en-US is the current culture:
//        $100.00

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

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

下面的示例演示如何为多个对象设置格式，包括用两种不同的方式为一个对象设置格式：

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

// Depending on the current time, the example displays output like the following:
//        Name = Fred, hours = 11, minutes = 30

Dim myName As String = "Fred"
Console.WriteLine(String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
                                myName, DateTime.Now))
'Depending on the current time, the example displays output Like the following:
'       Name = Fred, hours = 11, minutes = 30

下面的示例演示了对齐在格式设置中的使用方式。设置了格式的自变量放置在竖线字符 (|) 之间以突出显示得到的对齐。

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);

// The example displays the following output on a system whose current
// culture is en-US:
//     First Name = |      Fred|
//     Last Name =  |     Opals|
//     Price =      |   $100.00|
//
//     First Name = |Fred      |
//     Last Name =  |Opals     |
//     Price =      |$100.00   |

Dim firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)

'The example displays the following output on a system whose current
'culture Is en-US:
'    First Name = |      Fred|
'    Last Name =  |     Opals|
'    Price =      |   $100.00|
'
'    First Name = |Fred      |
'    Last Name =  |Opals     |
'    Price =      |$100.00   |