Share via

复合格式

  • 项目

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

复合格式设置功能受 Format、AppendFormat 以及 WriteLine 和 TextWriter.WriteLine 的某些重载等方法支持。 String.Format 方法可产生设置了格式的结果字符串，AppendFormat 方法将设置了格式的结果字符串追加到 StringBuilder 对象，Console.WriteLine 方法将设置了格式的结果字符串显示到控制台，TextWriter.WriteLine 方法将设置了格式的结果字符串写入流或文件。

复合格式字符串

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

可考虑使用以下 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}”和“{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}”。 不会显示本来要设置格式的数值。

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

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}

int value = 6324;
string output = string.Format("{0}{1:D}{2}", 
                             "{", value, "}");
Console.WriteLine(output);
// The example displays the following output:
//       {6324}

处理顺序

通过执行以下列表中的步骤，将参数列表中与格式项对应的每个值转换为一个字符串。 如果符合前三个步骤中的任一条件，则在此步骤中返回值的字符串表示形式，并且不执行后续步骤。

  1. 如果要设置格式的值为 null，则将返回空字符串 ("")。

  2. 如果复合格式设置方法包括也实现 ICustomFormatter 接口的类型 IFormatProvider 的参数，则将该值传递给 ICustomFormatter.Format 方法。

  3. 如果该值实现 IFormattable 接口，则调用其 IFormattable.ToString 方法。

  4. 调用类型的 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)
' The example displays the following output
' if en-US is the current culture:
'        $100.00

int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
// The example displays the following output 
// if en-US is the current culture:
//        $100.00

下面的示例说明为多个对象设置格式，包括用两种不同的方式为一个对象设置格式。

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 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 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)
Console.WriteLine()

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)
' 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   |

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);
Console.WriteLine();

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);
// 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   |

请参见

参考

WriteLine

String.Format

概念

格式化类型

标准数字格式字符串

自定义数字格式字符串

标准日期和时间格式字符串

自定义日期和时间格式字符串

枚举格式字符串

其他资源

标准 TimeSpan 格式字符串

自定义的 TimeSpan 格式字符串