StringBuilder.AppendFormat StringBuilder.AppendFormat StringBuilder.AppendFormat StringBuilder.AppendFormat Method

定义

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都由相应的对象自变量的字符串表示形式替换。Each format item is replaced by the string representation of a corresponding object argument.

重载

AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为三个参数中任一个的字符串表示形式。Each format item is replaced by the string representation of either of three arguments using a specified format provider.

AppendFormat(String, Object) AppendFormat(String, Object) AppendFormat(String, Object) AppendFormat(String, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为一个参数的字符串表示形式。Each format item is replaced by the string representation of a single argument.

AppendFormat(String, Object[]) AppendFormat(String, Object[]) AppendFormat(String, Object[]) AppendFormat(String, Object[])

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都由参数数组中相应参数的字符串表示形式替换。Each format item is replaced by the string representation of a corresponding argument in a parameter array.

AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为单个参数的字符串表示形式。Each format item is replaced by the string representation of a single argument using a specified format provider.

AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[])

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序由参数数组中相应参数的字符串表示形式替换。Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider.

AppendFormat(String, Object, Object) AppendFormat(String, Object, Object) AppendFormat(String, Object, Object) AppendFormat(String, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为这两个参数中任意一个参数的字符串表示形式。Each format item is replaced by the string representation of either of two arguments.

AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为两个参数中任一个的字符串表示形式。Each format item is replaced by the string representation of either of two arguments using a specified format provider.

AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为这三个参数中任意一个参数的字符串表示形式。Each format item is replaced by the string representation of either of three arguments.

AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object) AppendFormat(IFormatProvider, String, Object, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为三个参数中任一个的字符串表示形式。Each format item is replaced by the string representation of either of three arguments using a specified format provider.

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);
public System.Text.StringBuilder AppendFormat (IFormatProvider provider, string format, object arg0, object arg1, object arg2);
member this.AppendFormat : IFormatProvider * string * obj * obj * obj -> System.Text.StringBuilder
Public Function AppendFormat (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object, arg2 As Object) As StringBuilder

参数

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

一个提供区域性特定的格式设置信息的对象。An object that supplies culture-specific formatting information.

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的第一个对象。The first object to format.

arg1
Object Object Object Object

要设置格式的第二个对象。The second object to format.

arg2
Object Object Object Object

要设置格式的第三个对象。The third object to format.

返回

完成追加操作后对此实例的引用。A reference to this instance after the append operation has completed. 完成追加操作后,此实例包含执行该操作之前已存在的任何数据,并且有一个 format 的副本作为后缀,其中任何格式规范都由相应对象参数的字符串表示形式替换。After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of format where any format specification is replaced by the string representation of the corresponding object argument.

异常

format 无效。format is invalid.

-or- 格式项的索引小于 0(零)或者大于或等于 3。The index of a format item is less than 0 (zero), or greater than or equal to 3 (three).

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例使用AppendFormat(IFormatProvider, String, Object, Object, Object)方法来说明具有整数值的布尔And运算的结果。The following example uses the AppendFormat(IFormatProvider, String, Object, Object, Object) method to illustrate the result of a Boolean And operation with integer values. 请注意,格式字符串包含六个格式项,但该方法在其参数列表中只有三个项,因为每个项都以两种不同的方式进行格式化。Note that the format string includes six format items, but the method has only three items in its argument list, because each item is formatted in two different ways.

using System;
using System.Globalization;
using System.Text;

public class Example
{
   public static void Main()
   {
      Random rnd = new Random();
      CultureInfo culture = CultureInfo.CreateSpecificCulture("fr-FR");
      StringBuilder sb = new StringBuilder();
      string formatString = "    {0,12:N0} ({0,8:X8})\n" +
                            "And {1,12:N0} ({1,8:X8})\n" +
                            "  = {2,12:N0} ({2,8:X8})\n";
      for (int ctr = 0; ctr <= 2; ctr++) {
         int value1 = rnd.Next();
         int value2 = rnd.Next();
         sb.AppendFormat(culture, formatString,
                         value1, value2, value1 & value2).
                         AppendLine();
      }
      Console.WriteLine(sb.ToString());
   }
}
// The example displays output like the following:
//           1 984 112 195 (76432643)
//       And 1 179 778 511 (4651FDCF)
//         = 1 178 674 243 (46412443)
//
//           2 034 813 710 (7948CB0E)
//       And  569 333 976 (21EF58D8)
//         =  558 385 160 (21484808)
//
//            126 717 735 (078D8F27)
//       And 1 830 715 973 (6D1E8245)
//         =   84 705 797 (050C8205)
Imports System.Globalization
Imports System.Text

Public Module Example
   Public Sub Main()
      Dim rnd As New Random()
      Dim culture As CultureInfo = CultureInfo.CreateSpecificCulture("fr-FR")
      Dim sb As New StringBuilder()
      Dim formatString As String = "    {0,12:N0} ({0,8:X8})" + vbCrLf +
                                   "And {1,12:N0} ({1,8:X8})" + vbCrLf +
                                   "  = {2,12:N0} ({2,8:X8})" + vbCrLf
      For ctr As Integer = 0 To 2
         Dim value1 As Integer = rnd.Next()
         Dim value2 As Integer = rnd.Next()
         sb.AppendFormat(culture, formatString,
                         value1, value2, value1 And value2).AppendLine()
      Next
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays the following output:
'           1 984 112 195 (76432643)
'       And 1 179 778 511 (4651FDCF)
'         = 1 178 674 243 (46412443)
'
'           2 034 813 710 (7948CB0E)
'       And  569 333 976 (21EF58D8)
'         =  558 385 160 (21484808)
'
'            126 717 735 (078D8F27)
'       And 1 830 715 973 (6D1E8245)
'         =   84 705 797 (050C8205)

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行,这些占位符与此方法的参数列表中的对象相对应。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

参数指定可为arg0和提供arg1格式设置信息的实现。IFormatProvider providerThe provider parameter specifies an IFormatProvider implementation that can provide formatting information for arg0 and arg1. provider 可以是以下任意形式:provider can be any of the following:

  • 一个CultureInfo对象,提供区域性特定的格式设置信息。A CultureInfo object that provides culture-specific formatting information.

  • 一个NumberFormatInfo对象, arg0arg1为提供区域性特定的格式设置信息,如果它们是数字值,则为。A NumberFormatInfo object that provides culture-specific formatting information for arg0 or arg1 if they are numeric values.

  • 一个DateTimeFormatInfo对象,提供、或arg0 arg2的区域性特定格式设置arg1信息,如果它们是日期和时间值,则为。A DateTimeFormatInfo object that provides culture-specific formatting information for arg0, arg1, or arg2 if they are date and time values.

  • 提供、 IFormatProvider arg0arg2的格式设置信息的自定义实现。 arg1A custom IFormatProvider implementation that provides formatting information for arg0, arg1, and arg2. 通常,此类实现还实现ICustomFormatter接口。Typically, such an implementation also implements the ICustomFormatter interface.

如果参数为null,则从当前区域性获取格式提供程序信息。 providerIf the provider parameter is null, format provider information is obtained from the current culture.

arg0arg1arg2表示要设置格式的对象。arg0, arg1, and arg2 represent the objects to be formatted. format的每个格式项都替换为具有相应索引的对象的字符串表示形式。Each format item in format is replaced with the string representation of the object that has the corresponding index. 如果格式项包括formatString ,并且相应的参数实现了IFormattable接口,则参数的ToString(formatString, provider)方法会定义格式设置。If the format item includes formatString and the corresponding argument implements the IFormattable interface, then the argument's ToString(formatString, provider) method defines the formatting. 否则,自变量的ToString()方法定义格式设置。Otherwise, the argument's ToString() method defines the formatting.

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(String, Object) AppendFormat(String, Object) AppendFormat(String, Object) AppendFormat(String, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为一个参数的字符串表示形式。Each format item is replaced by the string representation of a single argument.

public:
 System::Text::StringBuilder ^ AppendFormat(System::String ^ format, System::Object ^ arg0);
public System.Text.StringBuilder AppendFormat (string format, object arg0);
member this.AppendFormat : string * obj -> System.Text.StringBuilder
Public Function AppendFormat (format As String, arg0 As Object) As StringBuilder

参数

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的对象。An object to format.

返回

对追加了 format 的此实例的引用。A reference to this instance with format appended. format 中的每个格式项都替换为 arg0 的字符串表示形式。Each format item in format is replaced by the string representation of arg0.

异常

format 无效。format is invalid.

- 或 --or- 格式项的索引小于 0(零),或者大于或等于 1。The index of a format item is less than 0 (zero), or greater than or equal to 1.

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例演示AppendFormat方法。The following example demonstrates the AppendFormat method.

using namespace System;
using namespace System::Text;
using namespace System::Globalization;
void Show( StringBuilder^ sbs )
{
   Console::WriteLine( sbs );
   sbs->Length = 0;
}

int main()
{
   StringBuilder^ sb = gcnew StringBuilder;
   int var1 = 111;
   float var2 = 2.22F;
   String^ var3 = "abcd";
   array<Object^>^var4 = {3,4.4,(Char)'X'};
   Console::WriteLine();
   Console::WriteLine( "StringBuilder.AppendFormat method:" );
   sb->AppendFormat( "1) {0}", var1 );
   Show( sb );
   sb->AppendFormat( "2) {0}, {1}", var1, var2 );
   Show( sb );
   sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 );
   Show( sb );
   sb->AppendFormat( "4) {0}, {1}, {2}", var4 );
   Show( sb );
   CultureInfo^ ci = gcnew CultureInfo( "es-ES",true );
   array<Object^>^temp1 = {var2};
   sb->AppendFormat( ci, "5) {0}", temp1 );
   Show( sb );
}

/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
Imports System.Text
Imports System.Globalization

Class Sample
   Private Shared sb As New StringBuilder()

   Public Shared Sub Main()
      Dim var1 As Integer = 111
      Dim var2 As Single = 2.22F
      Dim var3 As String = "abcd"
      Dim var4 As Object() =  {3, 4.4, "X"c}
      
      Console.WriteLine()
      Console.WriteLine("StringBuilder.AppendFormat method:")
      sb.AppendFormat("1) {0}", var1)
      Show(sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(sb)
      Dim ci As New CultureInfo("es-ES", True)
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(sb)
   End Sub
   
   Public Shared Sub Show(sbs As StringBuilder)
      Console.WriteLine(sbs.ToString())
      sb.Length = 0
   End Sub
End Class
'
'This example produces the following results:
'
'StringBuilder.AppendFormat method:
'1) 111
'2) 111, 2.22
'3) 111, 2.22, abcd
'4) 3, 4.4, X
'5) 2,22

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. 格式项的索引必须为0,以对应arg0于此方法的参数列表中的单个对象。The index of the format items must be 0, to correspond to arg0, the single object in the parameter list of this method. 格式设置过程将每个格式项替换为的字符串arg0表示形式。The formatting process replaces each format item with the string representation of arg0.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

arg0表示要设置格式的对象。arg0 represents the object to be formatted. format的每个格式项都替换为的字符串arg0表示形式。Each format item in format is replaced with the string representation of arg0. 如果格式项formatString包含并arg0实现IFormattable接口,则arg0.ToString(formatString, null)定义格式设置。If the format item includes formatString and arg0 implements the IFormattable interface, then arg0.ToString(formatString, null) defines the formatting. 否则, arg0.ToString()会定义格式设置。Otherwise, arg0.ToString() defines the formatting.

如果分配给format的字符串为 "感谢你向慈善组织捐赠 {0: # # # #} 个食物If the string assigned to format is "Thank you for your donation of {0:####} cans of food to our charitable organization." arg0是一个值为10的整数,则返回值将为 "感谢你向慈善组织捐赠10罐食物"。and arg0 is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization."

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(String, Object[]) AppendFormat(String, Object[]) AppendFormat(String, Object[]) AppendFormat(String, Object[])

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都由参数数组中相应参数的字符串表示形式替换。Each format item is replaced by the string representation of a corresponding argument in a parameter array.

public:
 System::Text::StringBuilder ^ AppendFormat(System::String ^ format, ... cli::array <System::Object ^> ^ args);
public System.Text.StringBuilder AppendFormat (string format, params object[] args);
member this.AppendFormat : string * obj[] -> System.Text.StringBuilder
Public Function AppendFormat (format As String, ParamArray args As Object()) As StringBuilder

参数

format
String String String String

复合格式字符串。A composite format string.

args
Object[]

要设置其格式的对象的数组。An array of objects to format.

返回

对追加了 format 的此实例的引用。A reference to this instance with format appended. format 中的每个格式项都由相应的对象参数的字符串表示形式替换。Each format item in format is replaced by the string representation of the corresponding object argument.

异常

formatargsnullformat or args is null.

format 无效。format is invalid.

-or- 格式项的索引小于 0(零),或者大于或等于 args 数组的长度。The index of a format item is less than 0 (zero), or greater than or equal to the length of the args array.

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例演示AppendFormat方法。The following example demonstrates the AppendFormat method.

using namespace System;
using namespace System::Text;
using namespace System::Globalization;
void Show( StringBuilder^ sbs )
{
   Console::WriteLine( sbs );
   sbs->Length = 0;
}

int main()
{
   StringBuilder^ sb = gcnew StringBuilder;
   int var1 = 111;
   float var2 = 2.22F;
   String^ var3 = "abcd";
   array<Object^>^var4 = {3,4.4,(Char)'X'};
   Console::WriteLine();
   Console::WriteLine( "StringBuilder.AppendFormat method:" );
   sb->AppendFormat( "1) {0}", var1 );
   Show( sb );
   sb->AppendFormat( "2) {0}, {1}", var1, var2 );
   Show( sb );
   sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 );
   Show( sb );
   sb->AppendFormat( "4) {0}, {1}, {2}", var4 );
   Show( sb );
   CultureInfo^ ci = gcnew CultureInfo( "es-ES",true );
   array<Object^>^temp1 = {var2};
   sb->AppendFormat( ci, "5) {0}", temp1 );
   Show( sb );
}

/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
Imports System.Text
Imports System.Globalization

Class Sample
   Private Shared sb As New StringBuilder()

   Public Shared Sub Main()
      Dim var1 As Integer = 111
      Dim var2 As Single = 2.22F
      Dim var3 As String = "abcd"
      Dim var4 As Object() =  {3, 4.4, "X"c}
      
      Console.WriteLine()
      Console.WriteLine("StringBuilder.AppendFormat method:")
      sb.AppendFormat("1) {0}", var1)
      Show(sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(sb)
      Dim ci As New CultureInfo("es-ES", True)
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(sb)
   End Sub
   
   Public Shared Sub Show(sbs As StringBuilder)
      Console.WriteLine(sbs.ToString())
      sb.Length = 0
   End Sub
End Class
'
'This example produces the following results:
'
'StringBuilder.AppendFormat method:
'1) 111
'2) 111, 2.22
'3) 111, 2.22, abcd
'4) 3, 4.4, X
'5) 2,22

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行,这些占位符与此方法的参数列表中的对象相对应。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

args表示要设置格式的对象。args represents the objects to be formatted. format的每个格式项都替换为中args相应对象的字符串表示形式。Each format item in format is replaced with the string representation of the corresponding object in args. formatString如果格式项包括,并且中args的相应对象实现IFormattable接口,则args[index].ToString(formatString, provider)定义格式设置。If the format item includes formatString and the corresponding object in args implements the IFormattable interface, then args[index].ToString(formatString, provider) defines the formatting. 否则, args[index].ToString()会定义格式设置。Otherwise, args[index].ToString() defines the formatting.

如果分配给format的字符串为 "感谢你向慈善组织捐赠 {0: # # # #} 个食物If the string assigned to format is "Thank you for your donation of {0:####} cans of food to our charitable organization." arg0是一个值为10的整数,则返回值将为 "感谢你向慈善组织捐赠10罐食物"。and arg0 is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization."

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object) AppendFormat(IFormatProvider, String, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为单个参数的字符串表示形式。Each format item is replaced by the string representation of a single argument using a specified format provider.

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0);
public System.Text.StringBuilder AppendFormat (IFormatProvider provider, string format, object arg0);
member this.AppendFormat : IFormatProvider * string * obj -> System.Text.StringBuilder
Public Function AppendFormat (provider As IFormatProvider, format As String, arg0 As Object) As StringBuilder

参数

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

一个提供区域性特定的格式设置信息的对象。An object that supplies culture-specific formatting information.

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的对象。The object to format.

返回

完成追加操作后对此实例的引用。A reference to this instance after the append operation has completed. 完成追加操作后,此实例包含执行该操作之前已存在的任何数据,并且有一个 format 的副本作为后缀,其中任何格式规范都由 arg0 的字符串表示形式替换。After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of format in which any format specification is replaced by the string representation of arg0.

异常

format 无效。format is invalid.

- 或 --or- 格式项的索引小于 0(零),或者大于等于一 (1)。The index of a format item is less than 0 (zero), or greater than or equal to one (1).

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面包括对方法的AppendFormat(IFormatProvider, String, Object)两次调用。The following includes two calls to the AppendFormat(IFormatProvider, String, Object) method. 两者都使用英语(英国)区域性的格式约定。Both use the formatting conventions of the English-Great Britain (en-GB) culture. 第一个在结果字符串中插入货币Decimal值的字符串表示形式。The first inserts the string representation of a Decimal value currency in a result string. 第二个将DateTime值插入到结果字符串中的两个位置,第一个是只包含短日期字符串,第二个在短时间字符串中。The second inserts a DateTime value in two places in a result string, the first including only the short date string and the second the short time string.

using System;
using System.Globalization;
using System.Text;

public class Example
{
   public static void Main()
   {
      StringBuilder sb = new StringBuilder();
      Decimal value = 16.95m;
      CultureInfo enGB = CultureInfo.CreateSpecificCulture("en-GB");
      DateTime dateToday = DateTime.Now;
      sb.AppendFormat(enGB, "Final Price: {0:C2}", value);
      sb.AppendLine();
      sb.AppendFormat(enGB, "Date and Time: {0:d} at {0:t}", dateToday);
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//       Final Price: £16.95
//       Date and Time: 01/10/2014 at 10:22
Imports System.Globalization
Imports System.Text

Module Example
   Public Sub Main()
      Dim sb As New StringBuilder()
      Dim value As Decimal = 16.95d
      Dim enGB As CultureInfo = CultureInfo.CreateSpecificCulture("en-GB")
      Dim dateToday As DateTime = Date.Now
      sb.AppendFormat(enGB, "Final Price: {0:C2}", value)
      sb.AppendLine()
      sb.AppendFormat(enGB, "Date and Time: {0:d} at {0:t}", dateToday)
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays output like the following:
'       Final Price: £16.95
'       Date and Time: 01/10/2014 at 10:22

注解

此方法使用 .NET Framework 的复合格式设置功能将的arg0值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of arg0 to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items. 每个格式项的索引必须为零(0),因为此方法包含一个带有单个参数的参数列表。The index of each format item must be zero (0) since this method includes an argument list with a single argument. 格式设置过程将每个格式项替换为的字符串arg0表示形式。The formatting process replaces each format item with the string representation of arg0.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 在这种情况下, AppendFormat(IFormatProvider, String, Object)因为方法在参数列表中有一个参数,所以index的值必须始终为0。In this case, since the AppendFormat(IFormatProvider, String, Object) method has a single argument in the argument list, the value of index must always be 0. 如果不是, FormatException则会引发。If it is not, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

参数指定一个IFormatProvider实现,该实现可以为中args的对象提供格式设置信息。 providerThe provider parameter specifies an IFormatProvider implementation that can provide formatting information for the objects in args. provider 可以是以下任意形式:provider can be any of the following:

  • 一个CultureInfo对象,提供区域性特定的格式设置信息。A CultureInfo object that provides culture-specific formatting information.

  • 一个NumberFormatInfo对象,它提供有关的arg0区域性特定格式设置信息。A NumberFormatInfo object that provides culture-specific formatting information for arg0 if it is a numeric value.

  • 一个DateTimeFormatInfo对象,它提供有关的arg0区域性特定格式设置信息。A DateTimeFormatInfo object that provides culture-specific formatting information for arg0 if it is a date and time value.

  • IFormatProviderarg0提供格式设置信息的自定义实现。A custom IFormatProvider implementation that provides formatting information for arg0. 通常,此类实现还实现ICustomFormatter接口。Typically, such an implementation also implements the ICustomFormatter interface.

如果参数为null,则从当前区域性获取格式设置信息。 providerIf the provider parameter is null, formatting information is obtained from the current culture.

arg0表示要设置格式的对象。arg0 represents the object to be formatted. format的每个格式项都替换为的字符串arg0表示形式。Each format item in format is replaced with the string representation of arg0. 如果格式项formatString包含并arg0实现IFormattable接口,则arg0.ToString(formatString, provider)定义格式设置。If the format item includes formatString and arg0 implements the IFormattable interface, then arg0.ToString(formatString, provider) defines the formatting. 否则, arg0.ToString()会定义格式设置。Otherwise, arg0.ToString() defines the formatting.

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[]) AppendFormat(IFormatProvider, String, Object[])

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序由参数数组中相应参数的字符串表示形式替换。Each format item is replaced by the string representation of a corresponding argument in a parameter array using a specified format provider.

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::String ^ format, ... cli::array <System::Object ^> ^ args);
public System.Text.StringBuilder AppendFormat (IFormatProvider provider, string format, params object[] args);
member this.AppendFormat : IFormatProvider * string * obj[] -> System.Text.StringBuilder
Public Function AppendFormat (provider As IFormatProvider, format As String, ParamArray args As Object()) As StringBuilder

参数

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

一个提供区域性特定的格式设置信息的对象。An object that supplies culture-specific formatting information.

format
String String String String

复合格式字符串。A composite format string.

args
Object[]

要设置其格式的对象的数组。An array of objects to format.

返回

完成追加操作后对此实例的引用。A reference to this instance after the append operation has completed. 完成追加操作后,此实例包含执行该操作之前已存在的任何数据,并且有一个 format 的副本作为后缀,其中任何格式规范都由相应对象参数的字符串表示形式替换。After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of format where any format specification is replaced by the string representation of the corresponding object argument.

异常

format 无效。format is invalid.

- 或 --or- 格式项的索引小于 0(零),或者大于或等于 args 数组的长度。The index of a format item is less than 0 (zero), or greater than or equal to the length of the args array.

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例演示AppendFormat方法。The following example demonstrates the AppendFormat method.

using namespace System;
using namespace System::Text;
using namespace System::Globalization;
void Show( StringBuilder^ sbs )
{
   Console::WriteLine( sbs );
   sbs->Length = 0;
}

int main()
{
   StringBuilder^ sb = gcnew StringBuilder;
   int var1 = 111;
   float var2 = 2.22F;
   String^ var3 = "abcd";
   array<Object^>^var4 = {3,4.4,(Char)'X'};
   Console::WriteLine();
   Console::WriteLine( "StringBuilder.AppendFormat method:" );
   sb->AppendFormat( "1) {0}", var1 );
   Show( sb );
   sb->AppendFormat( "2) {0}, {1}", var1, var2 );
   Show( sb );
   sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 );
   Show( sb );
   sb->AppendFormat( "4) {0}, {1}, {2}", var4 );
   Show( sb );
   CultureInfo^ ci = gcnew CultureInfo( "es-ES",true );
   array<Object^>^temp1 = {var2};
   sb->AppendFormat( ci, "5) {0}", temp1 );
   Show( sb );
}

/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
Imports System.Text
Imports System.Globalization

Class Sample
   Private Shared sb As New StringBuilder()

   Public Shared Sub Main()
      Dim var1 As Integer = 111
      Dim var2 As Single = 2.22F
      Dim var3 As String = "abcd"
      Dim var4 As Object() =  {3, 4.4, "X"c}
      
      Console.WriteLine()
      Console.WriteLine("StringBuilder.AppendFormat method:")
      sb.AppendFormat("1) {0}", var1)
      Show(sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(sb)
      Dim ci As New CultureInfo("es-ES", True)
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(sb)
   End Sub
   
   Public Shared Sub Show(sbs As StringBuilder)
      Console.WriteLine(sbs.ToString())
      sb.Length = 0
   End Sub
End Class
'
'This example produces the following results:
'
'StringBuilder.AppendFormat method:
'1) 111
'2) 111, 2.22
'3) 111, 2.22, abcd
'4) 3, 4.4, X
'5) 2,22

下面的示例定义了一个IFormatProvider名为CustomerFormatter的自定义实现,该实现在第四个和第七个数字后设置一个包含连字符的10位客户编号The following example defines a custom IFormatProvider implementation named CustomerFormatter that formats a 10-digit customer number with hyphens after the fourth and seventh digits. 它被传递给StringBuilder.AppendFormat(IFormatProvider, String, Object[])方法以创建一个字符串,该字符串包含带格式的客户编号和客户名称。It is passed to the StringBuilder.AppendFormat(IFormatProvider, String, Object[]) method to create a string that includes the formatted customer number and customer name.

using System;
using System.Text;

public class Customer
{
   private string custName;
   private int custNumber;
   
   public Customer(string name, int number)
   {
      this.custName = name;
      this.custNumber = number;
   }
   
   public string Name
   {
      get { return this.custName; }
   }
   
   public int CustomerNumber
   {
      get { return this.custNumber; }
   }
}

public class CustomerNumberFormatter : IFormatProvider, ICustomFormatter
{   
   public object GetFormat(Type formatType)
   {
      if (formatType == typeof(ICustomFormatter))
         return this;
      return null;
   }
   
   public string Format(string format, object arg, IFormatProvider provider)
   {
      if (arg is Int32)
      {
         string custNumber = ((int) arg).ToString("D10");
         return custNumber.Substring(0, 4) + "-" + custNumber.Substring(4, 3) + 
                "-" + custNumber.Substring(7, 3);
      }
      else
      {
         return null;
      }
   }                   
}

public class Example
{
   public static void Main()
   {
      Customer customer = new Customer("A Plus Software", 903654);
      StringBuilder sb = new StringBuilder();
      sb.AppendFormat(new CustomerNumberFormatter(), "{0}: {1}", 
                      customer.CustomerNumber, customer.Name);
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//      0000-903-654: A Plus Software
Imports System.Text

Public Class Customer
   Private custName As String
   Private custNumber As Integer
   
   Public Sub New(name As String, number As Integer)
      custName = name
      custNumber = number
   End Sub
   
   Public ReadOnly Property Name As String
      Get
         Return Me.custName
      End Get
   End Property
   
   Public ReadOnly Property CustomerNumber As Integer
      Get
         Return Me.custNumber
      End Get
   End Property
End Class

Public Class CustomerNumberFormatter 
   Implements IFormatProvider, ICustomFormatter
   
   Public Function GetFormat(formatType As Type) As Object _
                   Implements IFormatProvider.GetFormat
      If formatType Is GetType(ICustomFormatter) Then
         Return Me
      End If
      Return Nothing
   End Function
   
   Public Function Format(fmt As String, arg As Object, provider As IFormatProvider) As String _
                   Implements ICustomFormatter.Format
      If typeof arg Is Int32 Then
         Dim custNumber As String = CInt(arg).ToString("D10")
         Return custNumber.Substring(0, 4) + "-" + custNumber.SubString(4, 3) + _
                "-" + custNumber.Substring(7, 3)
      Else
         Return Nothing
      End If
   End Function                   
End Class

Module Example
   Public Sub Main()
      Dim customer As New Customer("A Plus Software", 903654)
      Dim sb As New StringBuilder()
      sb.AppendFormat(New CustomerNumberFormatter, "{0}: {1}", _
                      customer.CustomerNumber, customer.Name)
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays the following output:
'      0000-903-654: A Plus Software

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行,这些占位符与此方法的参数列表中的对象相对应。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

参数指定一个IFormatProvider实现,该实现可以为中args的对象提供格式设置信息。 providerThe provider parameter specifies an IFormatProvider implementation that can provide formatting information for the objects in args. provider 可以是以下任意形式:provider can be any of the following:

如果参数为null,则从当前区域性获取格式提供程序信息。 providerIf the provider parameter is null, format provider information is obtained from the current culture.

args表示要设置格式的对象。args represents the objects to be formatted. format的每个格式项都替换为中args相应对象的字符串表示形式。Each format item in format is replaced with the string representation of the corresponding object in args. formatString如果格式项包括,并且中args的相应对象实现IFormattable接口,则args[index].ToString(formatString, provider)定义格式设置。If the format item includes formatString and the corresponding object in args implements the IFormattable interface, then args[index].ToString(formatString, provider) defines the formatting. 否则, args[index].ToString()会定义格式设置。Otherwise, args[index].ToString() defines the formatting.

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(String, Object, Object) AppendFormat(String, Object, Object) AppendFormat(String, Object, Object) AppendFormat(String, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为这两个参数中任意一个参数的字符串表示形式。Each format item is replaced by the string representation of either of two arguments.

public:
 System::Text::StringBuilder ^ AppendFormat(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);
public System.Text.StringBuilder AppendFormat (string format, object arg0, object arg1);
member this.AppendFormat : string * obj * obj -> System.Text.StringBuilder
Public Function AppendFormat (format As String, arg0 As Object, arg1 As Object) As StringBuilder

参数

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的第一个对象。The first object to format.

arg1
Object Object Object Object

要设置格式的第二个对象。The second object to format.

返回

对追加了 format 的此实例的引用。A reference to this instance with format appended. format 中的每个格式项都由相应的对象参数的字符串表示形式替换。Each format item in format is replaced by the string representation of the corresponding object argument.

异常

format 无效。format is invalid.

- 或 --or- 格式项的索引小于 0(零),或者大于等于 2。The index of a format item is less than 0 (zero), or greater than or equal to 2.

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例演示AppendFormat方法。The following example demonstrates the AppendFormat method.

using namespace System;
using namespace System::Text;
using namespace System::Globalization;
void Show( StringBuilder^ sbs )
{
   Console::WriteLine( sbs );
   sbs->Length = 0;
}

int main()
{
   StringBuilder^ sb = gcnew StringBuilder;
   int var1 = 111;
   float var2 = 2.22F;
   String^ var3 = "abcd";
   array<Object^>^var4 = {3,4.4,(Char)'X'};
   Console::WriteLine();
   Console::WriteLine( "StringBuilder.AppendFormat method:" );
   sb->AppendFormat( "1) {0}", var1 );
   Show( sb );
   sb->AppendFormat( "2) {0}, {1}", var1, var2 );
   Show( sb );
   sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 );
   Show( sb );
   sb->AppendFormat( "4) {0}, {1}, {2}", var4 );
   Show( sb );
   CultureInfo^ ci = gcnew CultureInfo( "es-ES",true );
   array<Object^>^temp1 = {var2};
   sb->AppendFormat( ci, "5) {0}", temp1 );
   Show( sb );
}

/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
Imports System.Text
Imports System.Globalization

Class Sample
   Private Shared sb As New StringBuilder()

   Public Shared Sub Main()
      Dim var1 As Integer = 111
      Dim var2 As Single = 2.22F
      Dim var3 As String = "abcd"
      Dim var4 As Object() =  {3, 4.4, "X"c}
      
      Console.WriteLine()
      Console.WriteLine("StringBuilder.AppendFormat method:")
      sb.AppendFormat("1) {0}", var1)
      Show(sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(sb)
      Dim ci As New CultureInfo("es-ES", True)
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(sb)
   End Sub
   
   Public Shared Sub Show(sbs As StringBuilder)
      Console.WriteLine(sbs.ToString())
      sb.Length = 0
   End Sub
End Class
'
'This example produces the following results:
'
'StringBuilder.AppendFormat method:
'1) 111
'2) 111, 2.22
'3) 111, 2.22, abcd
'4) 3, 4.4, X
'5) 2,22

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行arg0 ,这两个对象分别与此方法的参数列表中的两个对象相对应arg1formatThe format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to arg0 and arg1, the two objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

arg0arg1表示要设置格式的对象。arg0 and arg1 represent the objects to be formatted. format的每个格式项都替换为arg0arg1的字符串表示形式。Each format item in format is replaced with the string representation of either arg0 or arg1. 如果格式formatString项包括,并且相应的对象IFormattable实现接口,则arg x .ToString(formatString, provider)定义格式设置,其中x是参数的索引。If the format item includes formatString and the corresponding object implements the IFormattable interface, then argx.ToString(formatString, provider) defines the formatting, where x is the index of the argument. 否则, arg x.ToString()定义格式设置。Otherwise, argx.ToString() defines the formatting.

如果分配给format的字符串为 "感谢你向慈善组织捐赠 {0: # # # #} 个食物If the string assigned to format is "Thank you for your donation of {0:####} cans of food to our charitable organization." arg0是一个值为10的整数,则返回值将为 "感谢你向慈善组织捐赠10罐食物"。and arg0 is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization."

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object) AppendFormat(IFormatProvider, String, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都使用指定的格式提供程序替换为两个参数中任一个的字符串表示形式。Each format item is replaced by the string representation of either of two arguments using a specified format provider.

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::String ^ format, System::Object ^ arg0, System::Object ^ arg1);
public System.Text.StringBuilder AppendFormat (IFormatProvider provider, string format, object arg0, object arg1);
member this.AppendFormat : IFormatProvider * string * obj * obj -> System.Text.StringBuilder
Public Function AppendFormat (provider As IFormatProvider, format As String, arg0 As Object, arg1 As Object) As StringBuilder

参数

provider
IFormatProvider IFormatProvider IFormatProvider IFormatProvider

一个提供区域性特定的格式设置信息的对象。An object that supplies culture-specific formatting information.

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的第一个对象。The first object to format.

arg1
Object Object Object Object

要设置格式的第二个对象。The second object to format.

返回

完成追加操作后对此实例的引用。A reference to this instance after the append operation has completed. 完成追加操作后,此实例包含执行该操作之前已存在的任何数据,并且有一个 format 的副本作为后缀,其中任何格式规范都由相应对象参数的字符串表示形式替换。After the append operation, this instance contains any data that existed before the operation, suffixed by a copy of format where any format specification is replaced by the string representation of the corresponding object argument.

异常

format 无效。format is invalid.

-or- 格式项的索引小于 0(零)或者大于或等于 2。The index of a format item is less than 0 (zero), or greater than or equal to 2 (two).

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例使用AppendFormat(IFormatProvider, String, Object, Object)方法来显示通用Dictionary<TKey,TValue>对象中存储的时间和温度数据。The following example uses the AppendFormat(IFormatProvider, String, Object, Object) method to display time and temperature data stored in a generic Dictionary<TKey,TValue> object. 请注意,格式字符串具有三个格式项,但仅有要设置格式的对象。Note that the format string has three format items, although there are only to objects to format. 这是因为列表中的第一个对象(日期和时间值)由两个格式项使用:第一个格式项显示时间,第二个格式项显示日期。This is because the first object in the list (a date and time value) is used by two format items: The first format item displays the time, and the second displays the date.

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Text;

public class Example
{
   public static void Main()
   {
      CultureInfo culture = new CultureInfo("en-US");
      StringBuilder sb = new StringBuilder();
      Dictionary<DateTime, Double> temperatureInfo = new Dictionary<DateTime, Double>(); 
      temperatureInfo.Add(new DateTime(2010, 6, 1, 14, 0, 0), 87.46);
      temperatureInfo.Add(new DateTime(2010, 12, 1, 10, 0, 0), 36.81);
      

      sb.AppendLine("Temperature Information:\n");
      foreach (var item in temperatureInfo)
      {
         sb.AppendFormat(culture,
                         "Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F\n",
                         item.Key, item.Value);
      }
      Console.WriteLine(sb.ToString());
   }
}
// The example displays the following output:
//       Temperature Information:
//       
//       Temperature at  2:00 PM on  6/1/2010:  87.5°F
//       Temperature at 10:00 AM on 12/1/2010:  36.8°F
Imports System.Collections.Generic
Imports System.Globalization
Imports System.Text

Module Example
   Public Sub Main()
      Dim culture As New CultureInfo("en-US")
      Dim sb As New StringBuilder()
      Dim temperatureInfo As New Dictionary(Of Date, Double) 
      temperatureInfo.Add(#6/1/2010 2:00PM#, 87.46)
      temperatureInfo.Add(#12/1/2010 10:00AM#, 36.81)
      
      sb.AppendLine("Temperature Information:").AppendLine()
      For Each item In temperatureInfo
         sb.AppendFormat(culture,
                         "Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F",
                         item.Key, item.Value).AppendLine()
      Next
      Console.WriteLine(sb.ToString())
   End Sub
End Module
' The example displays the following output:
'       Temperature Information:
'       
'       Temperature at  2:00 PM on  6/1/2010:  87.5°F
'       Temperature at 10:00 AM on 12/1/2010:  36.8°F

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

format参数包含与零个或多个索引占位符(称为格式项)混合的零个或多个文本的运行,这些占位符与此方法的参数列表中的对象相对应。The format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

参数指定可为arg0和提供arg1格式设置信息的实现。IFormatProvider providerThe provider parameter specifies an IFormatProvider implementation that can provide formatting information for arg0 and arg1. provider 可以是以下任意形式:provider can be any of the following:

  • 一个CultureInfo对象,提供区域性特定的格式设置信息。A CultureInfo object that provides culture-specific formatting information.

  • 一个NumberFormatInfo对象, arg0arg1为提供区域性特定的格式设置信息,如果它们是数字值,则为。A NumberFormatInfo object that provides culture-specific formatting information for arg0 or arg1 if they are numeric values.

  • 一个DateTimeFormatInfo对象,它为提供区域性特定的格式arg0设置arg1信息,或者,为日期和时间值。A DateTimeFormatInfo object that provides culture-specific formatting information for arg0 or arg1 if they are date and time values.

  • arg0IFormatProvider 提供arg1格式设置信息的自定义实现。A custom IFormatProvider implementation that provides formatting information for arg0 and arg1. 通常,此类实现还实现ICustomFormatter接口。Typically, such an implementation also implements the ICustomFormatter interface.

如果参数为null,则从当前区域性获取格式提供程序信息。 providerIf the provider parameter is null, format provider information is obtained from the current culture.

arg0arg1表示要设置格式的对象。arg0 and arg1 represent the objects to be formatted. format的每个格式项都替换为具有相应索引的对象的字符串表示形式。Each format item in format is replaced with the string representation of the object that has the corresponding index. 如果格式项包括formatString ,并且相应的参数实现了IFormattable接口,则参数的ToString(formatString, provider)方法会定义格式设置。If the format item includes formatString and the corresponding argument implements the IFormattable interface, then the argument's ToString(formatString, provider) method defines the formatting. 否则,自变量的ToString()方法定义格式设置。Otherwise, the argument's ToString() method defines the formatting.

调用方说明

在 .net Core 和在 .NET Framework 4.0 及更高版本中,当你通过StringBuilder StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量可能会超出其MaxCapacity知识产权.IIn .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object) AppendFormat(String, Object, Object, Object)

向此实例追加通过处理复合格式字符串(包含零个或更多格式项)而返回的字符串。Appends the string returned by processing a composite format string, which contains zero or more format items, to this instance. 每个格式项都替换为这三个参数中任意一个参数的字符串表示形式。Each format item is replaced by the string representation of either of three arguments.

public:
 System::Text::StringBuilder ^ AppendFormat(System::String ^ format, System::Object ^ arg0, System::Object ^ arg1, System::Object ^ arg2);
public System.Text.StringBuilder AppendFormat (string format, object arg0, object arg1, object arg2);
member this.AppendFormat : string * obj * obj * obj -> System.Text.StringBuilder
Public Function AppendFormat (format As String, arg0 As Object, arg1 As Object, arg2 As Object) As StringBuilder

参数

format
String String String String

复合格式字符串。A composite format string.

arg0
Object Object Object Object

要设置格式的第一个对象。The first object to format.

arg1
Object Object Object Object

要设置格式的第二个对象。The second object to format.

arg2
Object Object Object Object

要设置格式的第三个对象。The third object to format.

返回

对追加了 format 的此实例的引用。A reference to this instance with format appended. format 中的每个格式项都由相应的对象参数的字符串表示形式替换。Each format item in format is replaced by the string representation of the corresponding object argument.

异常

format 无效。format is invalid.

- 或 --or- 格式项的索引小于 0(零)或者大于或等于 3。The index of a format item is less than 0 (zero), or greater than or equal to 3.

扩展的字符串的长度将超过 MaxCapacityThe length of the expanded string would exceed MaxCapacity.

示例

下面的示例演示AppendFormat方法。The following example demonstrates the AppendFormat method.

using namespace System;
using namespace System::Text;
using namespace System::Globalization;
void Show( StringBuilder^ sbs )
{
   Console::WriteLine( sbs );
   sbs->Length = 0;
}

int main()
{
   StringBuilder^ sb = gcnew StringBuilder;
   int var1 = 111;
   float var2 = 2.22F;
   String^ var3 = "abcd";
   array<Object^>^var4 = {3,4.4,(Char)'X'};
   Console::WriteLine();
   Console::WriteLine( "StringBuilder.AppendFormat method:" );
   sb->AppendFormat( "1) {0}", var1 );
   Show( sb );
   sb->AppendFormat( "2) {0}, {1}", var1, var2 );
   Show( sb );
   sb->AppendFormat( "3) {0}, {1}, {2}", var1, var2, var3 );
   Show( sb );
   sb->AppendFormat( "4) {0}, {1}, {2}", var4 );
   Show( sb );
   CultureInfo^ ci = gcnew CultureInfo( "es-ES",true );
   array<Object^>^temp1 = {var2};
   sb->AppendFormat( ci, "5) {0}", temp1 );
   Show( sb );
}

/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
using System;
using System.Text;
using System.Globalization;

class Sample 
{
    static StringBuilder sb = new StringBuilder();

    public static void Main() 
    {
    int    var1   = 111;
    float  var2   = 2.22F;
    string var3   = "abcd";
    object[] var4 = {3, 4.4, 'X'};

    Console.WriteLine();
    Console.WriteLine("StringBuilder.AppendFormat method:");
    sb.AppendFormat("1) {0}", var1);
    Show(sb);
    sb.AppendFormat("2) {0}, {1}", var1, var2);
    Show(sb);
    sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3);
    Show(sb);
    sb.AppendFormat("4) {0}, {1}, {2}", var4);
    Show(sb);
    CultureInfo ci = new CultureInfo("es-ES", true);
    sb.AppendFormat(ci, "5) {0}", var2);
    Show(sb);
    }

    public static void Show(StringBuilder sbs)
    {
    Console.WriteLine(sbs.ToString());
    sb.Length = 0;
    }
}
/*
This example produces the following results:

StringBuilder.AppendFormat method:
1) 111
2) 111, 2.22
3) 111, 2.22, abcd
4) 3, 4.4, X
5) 2,22
*/
Imports System.Text
Imports System.Globalization

Class Sample
   Private Shared sb As New StringBuilder()

   Public Shared Sub Main()
      Dim var1 As Integer = 111
      Dim var2 As Single = 2.22F
      Dim var3 As String = "abcd"
      Dim var4 As Object() =  {3, 4.4, "X"c}
      
      Console.WriteLine()
      Console.WriteLine("StringBuilder.AppendFormat method:")
      sb.AppendFormat("1) {0}", var1)
      Show(sb)
      sb.AppendFormat("2) {0}, {1}", var1, var2)
      Show(sb)
      sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3)
      Show(sb)
      sb.AppendFormat("4) {0}, {1}, {2}", var4)
      Show(sb)
      Dim ci As New CultureInfo("es-ES", True)
      sb.AppendFormat(ci, "5) {0}", var2)
      Show(sb)
   End Sub
   
   Public Shared Sub Show(sbs As StringBuilder)
      Console.WriteLine(sbs.ToString())
      sb.Length = 0
   End Sub
End Class
'
'This example produces the following results:
'
'StringBuilder.AppendFormat method:
'1) 111
'2) 111, 2.22
'3) 111, 2.22, abcd
'4) 3, 4.4, X
'5) 2,22

注解

此方法使用 .NET Framework 的复合格式设置功能将对象的值转换为其文本表示形式,并将该表示形式嵌入到当前StringBuilder对象中。This method uses the composite formatting feature of the .NET Framework to convert the value of an object to its text representation and embed that representation in the current StringBuilder object.

参数由零个或多个包含零个或多个索引占位符(称为格式项,它们对应arg2arg0 ),这种方法的参数列表中的对象组成。 formatThe format parameter consists of zero or more runs of text intermixed with zero or more indexed placeholders, called format items, that correspond to arg0 through arg2, the objects in the parameter list of this method. 格式设置过程将每个格式项替换为相应对象的字符串表示形式。The formatting process replaces each format item with the string representation of the corresponding object.

格式项的语法如下所示:The syntax of a format item is as follows:

{index[,length] [:格式字符串]}{index[,length][:formatString]}

括号中的元素是可选的。Elements in square brackets are optional. 下表对每个元素进行了描述。The following table describes each element.

元素Element 说明Description
indexindex 要设置格式的对象的参数列表中的从零开始的位置。The zero-based position in the parameter list of the object to be formatted. 如果由index指定的对象为null,则会将格式String.Empty项替换为。If the object specified by index is null, the format item is replaced by String.Empty. 如果索引位置中没有参数, FormatException则会引发。If there is no parameter in the index position, a FormatException is thrown.
length,length 参数的字符串表示形式中的最小字符数。The minimum number of characters in the string representation of the parameter. 如果为正,则参数为右对齐; 否则为。如果为负,则为左对齐。If positive, the parameter is right-aligned; if negative, it is left-aligned.
:formatString:formatString 参数支持的标准或自定义格式字符串。A standard or custom format string that is supported by the parameter.

备注

对于用于日期和时间值的标准和自定义格式字符串,请参阅标准日期和时间格式字符串和自定义日期和时间格式字符串For the standard and custom format strings used with date and time values, see Standard Date and Time Format Strings and Custom Date and Time Format Strings. 对于与数值一起使用的标准和自定义格式字符串,请参阅标准数字格式字符串自定义数字格式字符串For the standard and custom format strings used with numeric values, see Standard Numeric Format Strings and Custom Numeric Format Strings. 对于用于枚举的标准格式字符串,请参阅枚举格式字符串For the standard format strings used with enumerations, see Enumeration Format Strings.

arg0arg1arg2表示要设置格式的对象。arg0, arg1, and arg2 represent the objects to be formatted. format的每个格式项都替换为arg0arg1arg2的字符串表示形式,具体取决于格式项的索引。Each format item in format is replaced with the string representation of either arg0, arg1, or arg2, depending on the index of the format item. 如果格式项包括formatString ,并且中.ToString(formatString, null) IFormattable args的相应对象实现接口,则arg x定义格式设置,其中x是参数的索引。If the format item includes formatString and the corresponding object in args implements the IFormattable interface, then argx.ToString(formatString, null) defines the formatting, where x is the index of the argument. 否则, arg x.ToString()定义格式设置。Otherwise, argx.ToString() defines the formatting.

如果分配给format的字符串为 "感谢你向慈善组织捐赠 {0: # # # #} 个食物If the string assigned to format is "Thank you for your donation of {0:####} cans of food to our charitable organization." arg0是一个值为10的整数,则返回值将为 "感谢你向慈善组织捐赠10罐食物"。and arg0 is an integer with the value 10, the return value will be "Thank you for your donation of 10 cans of food to our charitable organization."

调用方说明

在 .net Core 和 .NET Framework 4.0 及更高版本StringBuilder中,当通过StringBuilder(Int32, Int32)调用构造函数实例化对象时, StringBuilder实例的长度和容量超出其MaxCapacity知识产权.In .NET Core and in the .NET Framework 4.0 and later versions, when you instantiate the StringBuilder object by calling the StringBuilder(Int32, Int32) constructor, both the length and the capacity of the StringBuilder instance can grow beyond the value of its MaxCapacity property. 当调用Append(String)和方法追加小字符串时, AppendFormat(String, Object)尤其如此。This can occur particularly when you call the Append(String) and AppendFormat(String, Object) methods to append small strings.

另请参阅

适用于