StringBuilder.AppendFormat 方法

定義

命名空間:

System.Text

組件:

System.Runtime.dll

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由對應物件自變數的字串表示所取代。

多載

AppendFormat(IFormatProvider, CompositeFormat, ReadOnlySpan<Object>)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。
AppendFormat(String, Object, Object, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由三個自變數之一的字串表示所取代。
AppendFormat(IFormatProvider, String, Object, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會使用指定的格式提供者，由兩個自變數之一的字串表示所取代。
AppendFormat(String, Object, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由兩個自變數之一的字串表示所取代。
AppendFormat(IFormatProvider, String, Object, Object, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之三個自變數之一的字串表示所取代。
AppendFormat(IFormatProvider, CompositeFormat, Object[])	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。
AppendFormat(IFormatProvider, String, Object[])	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會使用指定的格式提供者，取代參數陣列中對應自變數的字串表示。
AppendFormat(IFormatProvider, String, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者的單一自變數字串表示所取代。
AppendFormat(String, Object[])	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由參數陣列中對應自變數的字串表示所取代。
AppendFormat(String, Object)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由單一自變數的字串表示所取代。
AppendFormat<TArg0,TArg1,TArg2>(IFormatProvider, CompositeFormat, TArg0, TArg1, TArg2)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。
AppendFormat<TArg0,TArg1>(IFormatProvider, CompositeFormat, TArg0, TArg1)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。
AppendFormat<TArg0>(IFormatProvider, CompositeFormat, TArg0)	處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

AppendFormat(IFormatProvider, CompositeFormat, ReadOnlySpan<Object>)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, ReadOnlySpan<System::Object ^> args);

public System.Text.StringBuilder AppendFormat (IFormatProvider? provider, System.Text.CompositeFormat format, ReadOnlySpan<object?> args);

member this.AppendFormat : IFormatProvider * System.Text.CompositeFormat * ReadOnlySpan<obj> -> System.Text.StringBuilder

Public Function AppendFormat (provider As IFormatProvider, format As CompositeFormat, args As ReadOnlySpan(Of Object)) As StringBuilder

參數

provider

IFormatProvider

物件，提供特定文化特性的格式資訊。

format

CompositeFormat

CompositeFormat。

args

ReadOnlySpan<Object>

要格式化的物件範圍。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。

例外狀況

ArgumentNullException

format null。

FormatException

格式專案的索引大於或等於提供的自變數數目。

AppendFormat(String, Object, Object, Object)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由三個自變數之一的字串表示所取代。

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

複合格式字串。

arg0

Object

要格式化的第一個物件。

arg1

Object

要格式化的第二個物件。

arg2

Object

要格式化的第三個物件。

傳回

StringBuilder

附加 format 這個實例的參考。 format 中的每個格式項目都會由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於3。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例示範 AppendFormat 方法。

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
*/

open System.Text
open System.Globalization

let sb = StringBuilder()

let show (sbs: StringBuilder) =
    printfn $"{sbs}"
    sb.Length <- 0

let var1 = 111
let var2 = 2.22f
let var3 = "abcd"
let var4: obj[] = [| 3; 4.4; 'X' |]

printfn "StringBuilder.AppendFormat method:"
sb.AppendFormat("1) {0}", var1) |> ignore
show sb
sb.AppendFormat("2) {0}, {1}", var1, var2) |> ignore
show sb
sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) |> ignore
show sb
sb.AppendFormat("4) {0}, {1}, {2}", var4) |> ignore
show sb
let ci = CultureInfo("es-ES", true)
sb.AppendFormat(ci, "5) {0}", var2) |> ignore
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

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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混合，稱為格式項目，對應至透過 arg2arg0 ，這個方法的參數清單中的物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

arg0、arg1和 arg2 代表要格式化的物件。 format 中的每個格式項目都會以 arg0、arg1或 arg2的字串表示來取代，視格式專案的索引而定。 如果格式專案包含 formatString，且 args 中的對應物件會實作 IFormattable 介面，則 argx.ToString(formatString, null) 定義格式設定，其中 x 是自變數的索引。 否則，argx.ToString() 會定義格式設定。

如果指派給 format 的字串是「感謝您將 {0：####} 罐食品捐贈給我們的慈善組織」，且 arg0 是值為 10 的整數，則傳回值將會是「感謝您向慈善組織捐贈 10 罐食物」。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(IFormatProvider, String, Object, Object)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會使用指定的格式提供者，由兩個自變數之一的字串表示所取代。

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

物件，提供特定文化特性的格式資訊。

format

String

複合格式字串。

arg0

Object

要格式化的第一個物件。

arg1

Object

要格式化的第二個物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。 附加作業之後，這個實例會包含作業之前存在的任何數據，後面加上 format 複本，其中任何格式規格都由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於2（二）。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例會使用 AppendFormat(IFormatProvider, String, Object, Object) 方法來顯示儲存在泛型 Dictionary<TKey,TValue> 對象中的時間和溫度數據。 請注意，格式字串有三個格式項目，不過只有物件可格式化。 這是因為清單中的第一個物件（日期和時間值）是由兩個格式專案使用：第一個格式專案會顯示時間，而第二個則顯示日期。

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

open System
open System.Collections.Generic
open System.Globalization
open System.Text

let culture = CultureInfo "en-US"
let sb = StringBuilder()
let temperatureInfo = Dictionary<DateTime, Double>()
temperatureInfo.Add(DateTime(2010, 6, 1, 14, 0, 0), 87.46)
temperatureInfo.Add(DateTime(2010, 12, 1, 10, 0, 0), 36.81)

sb.AppendLine "Temperature Information:\n" |> ignore

for item in temperatureInfo do
    sb.AppendFormat(culture, "Temperature at {0,8:t} on {0,9:d}: {1,5:N1}°F\n", item.Key, item.Value)
    |> ignore

printfn $"{sb}"

// 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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混用，稱為格式項目，對應至此方法參數清單中的物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

provider 參數會指定 IFormatProvider 實作，以提供 arg0 和 arg1的格式資訊。 provider 可以是下列任一項：

• 提供特定文化特性格式資訊的 CultureInfo 物件。

• NumberFormatInfo 物件，如果 arg0 或 arg1 是數值，則提供特定文化特性的格式資訊。

• DateTimeFormatInfo 物件，提供 arg0 或 arg1 其為日期和時間值的文化特性特定格式資訊。

• 自訂 IFormatProvider 實作，提供 arg0 和 arg1的格式資訊。 一般而言，這類實作也會實作 ICustomFormatter 介面。

如果 provider 參數是 null，則會從目前的文化特性取得格式提供者資訊。

arg0 和 arg1 代表要格式化的物件。 format 中的每個格式項目都會取代為具有對應索引之物件的字串表示。 如果格式專案包含 formatString，且對應的自變數會實作 IFormattable 介面，則自變數的 ToString(formatString, provider) 方法會定義格式設定。 否則，自變數的 ToString() 方法會定義格式設定。

給呼叫者的注意事項

IIn .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以成長超過其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 如何：定義及使用自定義數值格式提供者
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(String, Object, Object)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由兩個自變數之一的字串表示所取代。

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

複合格式字串。

arg0

Object

要格式化的第一個物件。

arg1

Object

要格式化的第二個物件。

傳回

StringBuilder

附加 format 這個實例的參考。 format 中的每個格式項目都會由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於2。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例示範 AppendFormat 方法。

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
*/

open System.Text
open System.Globalization

let sb = StringBuilder()

let show (sbs: StringBuilder) =
    printfn $"{sbs}"
    sb.Length <- 0

let var1 = 111
let var2 = 2.22f
let var3 = "abcd"
let var4: obj[] = [| 3; 4.4; 'X' |]

printfn "StringBuilder.AppendFormat method:"
sb.AppendFormat("1) {0}", var1) |> ignore
show sb
sb.AppendFormat("2) {0}, {1}", var1, var2) |> ignore
show sb
sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) |> ignore
show sb
sb.AppendFormat("4) {0}, {1}, {2}", var4) |> ignore
show sb
let ci = CultureInfo("es-ES", true)
sb.AppendFormat(ci, "5) {0}", var2) |> ignore
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

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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混合，稱為格式項目，對應至 arg0 和 arg1，這個方法的參數清單中的兩個物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

arg0 和 arg1 代表要格式化的物件。 format 中的每個格式項目都會取代為 arg0 或 arg1的字串表示。 如果格式專案包含 formatString，而對應的 物件會實作 IFormattable 介面，則 argx.ToString(formatString, provider) 定義格式設定，其中 x 是自變數的索引。 否則，argx.ToString() 會定義格式設定。

如果指派給 format 的字串是「感謝您將 {0：####} 罐食品捐贈給我們的慈善組織」，且 arg0 是值為 10 的整數，則傳回值將會是「感謝您向慈善組織捐贈 10 罐食物」。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

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

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之三個自變數之一的字串表示所取代。

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

物件，提供特定文化特性的格式資訊。

format

String

複合格式字串。

arg0

Object

要格式化的第一個物件。

arg1

Object

要格式化的第二個物件。

arg2

Object

要格式化的第三個物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。 附加作業之後，這個實例會包含作業之前存在的任何數據，後面加上 format 複本，其中任何格式規格都由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於3（三）。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例會使用 AppendFormat(IFormatProvider, String, Object, Object, Object) 方法來說明布爾值 And 運算的結果，並具有整數值。 請注意，格式字串包含六個格式專案，但方法在其自變數清單中只有三個專案，因為每個專案都以兩種不同的方式格式化。

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)

open System
open System.Globalization
open System.Text

let rnd = Random()
let culture = CultureInfo.CreateSpecificCulture "fr-FR"
let sb = StringBuilder()

let formatString =
    "    {0,12:N0} ({0,8:X8})\nAnd {1,12:N0} ({1,8:X8})\n  = {2,12:N0} ({2,8:X8})\n"

for _ = 0 to 2 do
    let value1 = rnd.Next()
    let value2 = rnd.Next()

    sb
        .AppendFormat(culture, formatString, value1, value2, value1 &&& value2)
        .AppendLine()
    |> ignore

printfn $"{sb}"

// 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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混用，稱為格式項目，對應至此方法參數清單中的物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

provider 參數會指定 IFormatProvider 實作，以提供 arg0 和 arg1的格式資訊。 provider 可以是下列任一項：

• 提供特定文化特性格式資訊的 CultureInfo 物件。

• NumberFormatInfo 物件，如果 arg0 或 arg1 是數值，則提供特定文化特性的格式資訊。

• DateTimeFormatInfo 物件，提供 arg0、arg1或 arg2，如果它們為日期和時間值，則提供特定文化特性的格式資訊。

• 自訂 IFormatProvider 實作，提供 arg0、arg1和 arg2的格式資訊。 一般而言，這類實作也會實作 ICustomFormatter 介面。

如果 provider 參數是 null，則會從目前的文化特性取得格式提供者資訊。

arg0、arg1和 arg2 代表要格式化的物件。 format 中的每個格式項目都會取代為具有對應索引之物件的字串表示。 如果格式專案包含 formatString，且對應的自變數會實作 IFormattable 介面，則自變數的 ToString(formatString, provider) 方法會定義格式設定。 否則，自變數的 ToString() 方法會定義格式設定。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 如何：定義及使用自定義數值格式提供者
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(IFormatProvider, CompositeFormat, Object[])

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

public:
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, ... cli::array <System::Object ^> ^ args);

public System.Text.StringBuilder AppendFormat (IFormatProvider? provider, System.Text.CompositeFormat format, params object?[] args);

member this.AppendFormat : IFormatProvider * System.Text.CompositeFormat * obj[] -> System.Text.StringBuilder

Public Function AppendFormat (provider As IFormatProvider, format As CompositeFormat, ParamArray args As Object()) As StringBuilder

參數

provider

IFormatProvider

物件，提供特定文化特性的格式資訊。

format

CompositeFormat

CompositeFormat。

args

Object[]

要格式化的物件陣列。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。

例外狀況

ArgumentNullException

format 或 argsnull。

FormatException

格式專案的索引大於或等於提供的自變數數目。

AppendFormat(IFormatProvider, String, Object[])

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會使用指定的格式提供者，取代參數陣列中對應自變數的字串表示。

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

物件，提供特定文化特性的格式資訊。

format

String

複合格式字串。

args

Object[]

要格式化的物件陣列。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。 附加作業之後，這個實例會包含作業之前存在的任何數據，後面加上 format 複本，其中任何格式規格都由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於 args 陣列的長度。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例示範 AppendFormat 方法。

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
*/

open System.Text
open System.Globalization

let sb = StringBuilder()

let show (sbs: StringBuilder) =
    printfn $"{sbs}"
    sb.Length <- 0

let var1 = 111
let var2 = 2.22f
let var3 = "abcd"
let var4: obj[] = [| 3; 4.4; 'X' |]

printfn "StringBuilder.AppendFormat method:"
sb.AppendFormat("1) {0}", var1) |> ignore
show sb
sb.AppendFormat("2) {0}, {1}", var1, var2) |> ignore
show sb
sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) |> ignore
show sb
sb.AppendFormat("4) {0}, {1}, {2}", var4) |> ignore
show sb
let ci = CultureInfo("es-ES", true)
sb.AppendFormat(ci, "5) {0}", var2) |> ignore
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

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

下列範例會定義名為 CustomerFormatter 的自定義 IFormatProvider 實作，其會將 10 位數的客戶號碼格式化為第四個和第七位數之後的連字元。 它會傳遞至 StringBuilder.AppendFormat(IFormatProvider, String, Object[]) 方法，以建立字串，其中包含格式化的客戶號碼和客戶名稱。

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

open System
open System.Text

type Customer(name: string, number: int) =
    member _.Name = name
    member _.CustomerNumber = number

type CustomerNumberFormatter() =
    interface IFormatProvider with
        member this.GetFormat(formatType) =
            if formatType = typeof<ICustomFormatter> then this else null

    interface ICustomFormatter with
        member _.Format(_, arg, _) =
            match arg with
            | :? int as i ->
                let custNumber = i.ToString "D10"
                $"{custNumber.Substring(0, 4)}-{custNumber.Substring(4, 3)}-{custNumber.Substring(7, 3)}"
            | _ -> null

let customer = Customer("A Plus Software", 903654)
let sb = StringBuilder()

sb.AppendFormat(CustomerNumberFormatter(), "{0}: {1}", customer.CustomerNumber, customer.Name)
|> ignore

printfn $"{sb}"

// 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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混用，稱為格式項目，對應至此方法參數清單中的物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

provider 參數會指定 IFormatProvider 實作，可為 args中的物件提供格式資訊。 provider 可以是下列任一項：

• 提供特定文化特性格式資訊的 CultureInfo 物件。

• NumberFormatInfo 物件，提供 args中數值的文化特性特定格式資訊。

• DateTimeFormatInfo 物件，提供 args中日期和時間值的文化特性特定格式資訊。

• 自訂 IFormatProvider 實作，可為 args中的一或多個物件提供格式設定資訊。 一般而言，這類實作也會實作 ICustomFormatter 介面。 下一節的第二個範例說明使用自定義 IFormatProvider 實作的 StringBuilder.AppendFormat(IFormatProvider, String, Object[]) 方法呼叫。

如果 provider 參數是 null，則會從目前的文化特性取得格式提供者資訊。

args 代表要格式化的物件。 format 中的每個格式項目都會取代為 中對應物件的字串表示，args。 如果格式專案包含 formatString，且 args 中的對應物件會實作 IFormattable 介面，則 args[index].ToString(formatString, provider) 定義格式設定。 否則，args[index].ToString() 會定義格式設定。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 如何：定義及使用自定義數值格式提供者
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(IFormatProvider, String, Object)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者的單一自變數字串表示所取代。

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

物件，提供特定文化特性的格式資訊。

format

String

複合格式字串。

arg0

Object

要格式化的物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。 附加作業之後，這個實例會包含作業之前存在的任何數據，後綴為 format 複本，其中任何格式規格都由 arg0的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於一 （1）。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列包含對 AppendFormat(IFormatProvider, String, Object) 方法的兩個呼叫。 兩者都使用 English-United 王國（en-GB）文化的格式慣例。 第一個會在結果字串中插入 Decimal 值貨幣的字串表示。 第二個會在結果字串的兩個位置插入 DateTime 值，第一個則只包括簡短日期字串和第二個短時間字串。

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

open System
open System.Globalization
open System.Text

let sb = StringBuilder()
let value = 16.95m
let enGB = CultureInfo.CreateSpecificCulture "en-GB"
let dateToday = DateTime.Now
sb.AppendFormat(enGB, "Final Price: {0:C2}", value) |> ignore
sb.AppendLine() |> ignore
sb.AppendFormat(enGB, "Date and Time: {0:d} at {0:t}", dateToday) |> ignore
printfn $"{sb}"

// 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 物件中。

format 參數是由零或多個文字執行所組成，與零個或多個索引佔位元混合，稱為格式專案。 每個格式專案的索引必須是零 （0），因為此方法包含具有單一自變數的自變數清單。 格式化程式會將每個格式專案取代為 arg0的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 在此情況下，由於 AppendFormat(IFormatProvider, String, Object) 方法在自變數清單中具有單一自變數，因此 索引 的值一律必須為 0。 如果不是，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

provider 參數會指定 IFormatProvider 實作，可為 args中的物件提供格式資訊。 provider 可以是下列任一項：

• 提供特定文化特性格式資訊的 CultureInfo 物件。

• NumberFormatInfo 物件，如果它是數值，則為 arg0 提供特定文化特性的格式資訊。

• DateTimeFormatInfo 物件，如果它是日期和時間值，則為 arg0 提供特定文化特性的格式資訊。

• 自訂 IFormatProvider 實作，提供 arg0的格式資訊。 一般而言，這類實作也會實作 ICustomFormatter 介面。

如果 provider 參數是 null，則會從目前的文化特性取得格式資訊。

arg0 代表要格式化的物件。 format 中的每個格式項目都會取代為 arg0的字串表示。 如果格式專案包含 formatString，且 arg0 實作 IFormattable 介面，則 arg0.ToString(formatString, provider) 定義格式設定。 否則，arg0.ToString() 會定義格式設定。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 如何：定義及使用自定義數值格式提供者
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(String, Object[])

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由參數陣列中對應自變數的字串表示所取代。

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

複合格式字串。

args

Object[]

要格式化的物件陣列。

傳回

StringBuilder

附加 format 這個實例的參考。 format 中的每個格式項目都會由對應物件自變數的字串表示所取代。

例外狀況

ArgumentNullException

format 或 argsnull。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於 args 陣列的長度。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例示範 AppendFormat 方法。

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
*/

open System.Text
open System.Globalization

let sb = StringBuilder()

let show (sbs: StringBuilder) =
    printfn $"{sbs}"
    sb.Length <- 0

let var1 = 111
let var2 = 2.22f
let var3 = "abcd"
let var4: obj[] = [| 3; 4.4; 'X' |]

printfn "StringBuilder.AppendFormat method:"
sb.AppendFormat("1) {0}", var1) |> ignore
show sb
sb.AppendFormat("2) {0}, {1}", var1, var2) |> ignore
show sb
sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) |> ignore
show sb
sb.AppendFormat("4) {0}, {1}, {2}", var4) |> ignore
show sb
let ci = CultureInfo("es-ES", true)
sb.AppendFormat(ci, "5) {0}", var2) |> ignore
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

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 物件中。

format 參數包含零或多個文字執行，與零或多個索引佔位元混用，稱為格式項目，對應至此方法參數清單中的物件。 格式化程式會將每個格式專案取代為對應物件的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

args 代表要格式化的物件。 format 中的每個格式項目都會取代為 中對應物件的字串表示，args。 如果格式專案包含 formatString，且 args 中的對應物件會實作 IFormattable 介面，則 args[index].ToString(formatString, provider) 定義格式設定。 否則，args[index].ToString() 會定義格式設定。

如果指派給 format 的字串是「感謝您將 {0：####} 罐食品捐贈給我們的慈善組織」，且 arg0 是值為 10 的整數，則傳回值將會是「感謝您向慈善組織捐贈 10 罐食物」。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat(String, Object)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由單一自變數的字串表示所取代。

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

複合格式字串。

arg0

Object

要格式化的物件。

傳回

StringBuilder

附加 format 這個實例的參考。 format 中的每個格式項目都會由 arg0的字串表示所取代。

例外狀況

ArgumentNullException

format null。

FormatException

format 無效。

-或-

格式專案的索引小於0（零），或大於或等於1。

ArgumentOutOfRangeException

展開字串的長度會超過 MaxCapacity。

範例

下列範例示範 AppendFormat 方法。

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
*/

open System.Text
open System.Globalization

let sb = StringBuilder()

let show (sbs: StringBuilder) =
    printfn $"{sbs}"
    sb.Length <- 0

let var1 = 111
let var2 = 2.22f
let var3 = "abcd"
let var4: obj[] = [| 3; 4.4; 'X' |]

printfn "StringBuilder.AppendFormat method:"
sb.AppendFormat("1) {0}", var1) |> ignore
show sb
sb.AppendFormat("2) {0}, {1}", var1, var2) |> ignore
show sb
sb.AppendFormat("3) {0}, {1}, {2}", var1, var2, var3) |> ignore
show sb
sb.AppendFormat("4) {0}, {1}, {2}", var4) |> ignore
show sb
let ci = CultureInfo("es-ES", true)
sb.AppendFormat(ci, "5) {0}", var2) |> ignore
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

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 物件中。

format 參數是由零或多個文字執行所組成，與零個或多個索引佔位元混合，稱為格式專案。 格式專案的索引必須是 0，才能對應至 arg0，這個方法的參數清單中的單一物件。 格式化程式會將每個格式專案取代為 arg0的字串表示。

格式項目的語法如下所示：

{index[，length][：formatString]}

方括弧中的元素是選擇性的。 下表描述每個元素。

元素	描述
索引	要格式化之物件參數清單中的以零起始的位置。 如果 索引 所指定的物件 null，則格式專案會取代為 String.Empty。 如果 索引中沒有參數 位置，則會擲回 FormatException。
、長度	參數位符串表示中的字元數下限。 如果為正數，則參數會靠右對齊;如果為負數，則為靠左對齊。
：formatString	參數所支持的標準或自定義格式字串。

注意

如需搭配日期和時間值使用的標準和自訂格式字串，請參閱 標準日期和時間格式字串 和 自定義日期和時間格式字串。 如需搭配數值使用的標準和自訂格式字串，請參閱 標準數值格式字串 和 自定義數值格式字串。 如需搭配列舉使用的標準格式字串，請參閱 列舉格式字串。

arg0 代表要格式化的物件。 format 中的每個格式項目都會取代為 arg0的字串表示。 如果格式專案包含 formatString，且 arg0 實作 IFormattable 介面，則 arg0.ToString(formatString, null) 定義格式設定。 否則，arg0.ToString() 會定義格式設定。

如果指派給 format 的字串是「感謝您將 {0：####} 罐食品捐贈給我們的慈善組織」，且 arg0 是值為 10 的整數，則傳回值將會是「感謝您向慈善組織捐贈 10 罐食物」。

給呼叫者的注意事項

在 .NET Core 和 .NET Framework 4.0 和更新版本中，當您藉由呼叫 StringBuilder(Int32, Int32) 建構函式來具現化 StringBuilder 物件時，StringBuilder 實例的長度和容量都可以超出其 MaxCapacity 屬性的值。 當您呼叫 Append(String) 和 AppendFormat(String, Object) 方法來附加小型字串時，尤其會發生此情況。

另請參閱

• .NET 中的格式設定類型
• 複合格式設定
• 標準數值格式字串
• 自定義數值格式字串
• 標準日期和時間格式字串
• 自定義日期和時間格式字串
• 標準 TimeSpan 格式字串
• 自定義 TimeSpan 格式字串
• 列舉格式字串

AppendFormat<TArg0,TArg1,TArg2>(IFormatProvider, CompositeFormat, TArg0, TArg1, TArg2)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

public:
generic <typename TArg0, typename TArg1, typename TArg2>
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0, TArg1 arg1, TArg2 arg2);

public System.Text.StringBuilder AppendFormat<TArg0,TArg1,TArg2> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0, TArg1 arg1, TArg2 arg2);

member this.AppendFormat : IFormatProvider * System.Text.CompositeFormat * 'TArg0 * 'TArg1 * 'TArg2 -> System.Text.StringBuilder

Public Function AppendFormat(Of TArg0, TArg1, TArg2) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0, arg1 As TArg1, arg2 As TArg2) As StringBuilder

類型參數

TArg0

要格式化之第一個物件的型別。

TArg1

要格式化的第二個物件型別。

TArg2

要格式化的第三個物件型別。

參數

provider

IFormatProvider

物件，提供特定文化特性的格式資訊。

format

CompositeFormat

CompositeFormat。

arg0

TArg0

要格式化的第一個物件。

arg1

TArg1

要格式化的第二個物件。

arg2

TArg2

要格式化的第三個物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。

例外狀況

ArgumentNullException

format null。

FormatException

格式專案的索引大於或等於提供的自變數數目。

AppendFormat<TArg0,TArg1>(IFormatProvider, CompositeFormat, TArg0, TArg1)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

public:
generic <typename TArg0, typename TArg1>
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0, TArg1 arg1);

public System.Text.StringBuilder AppendFormat<TArg0,TArg1> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0, TArg1 arg1);

member this.AppendFormat : IFormatProvider * System.Text.CompositeFormat * 'TArg0 * 'TArg1 -> System.Text.StringBuilder

Public Function AppendFormat(Of TArg0, TArg1) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0, arg1 As TArg1) As StringBuilder

類型參數

TArg0

要格式化之第一個物件的型別。

TArg1

要格式化的第二個物件型別。

參數

provider

IFormatProvider

物件，提供特定文化特性的格式資訊。

format

CompositeFormat

CompositeFormat。

arg0

TArg0

要格式化的第一個物件。

arg1

TArg1

要格式化的第二個物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。

例外狀況

ArgumentNullException

format null。

FormatException

格式專案的索引大於或等於提供的自變數數目。

AppendFormat<TArg0>(IFormatProvider, CompositeFormat, TArg0)

來源:

StringBuilder.cs

處理包含零個或多個格式項目的複合格式字串，將傳回的字串附加至這個實例。 每個格式項目都會由使用指定格式提供者之任何自變數的字串表示所取代。

public:
generic <typename TArg0>
 System::Text::StringBuilder ^ AppendFormat(IFormatProvider ^ provider, System::Text::CompositeFormat ^ format, TArg0 arg0);

public System.Text.StringBuilder AppendFormat<TArg0> (IFormatProvider? provider, System.Text.CompositeFormat format, TArg0 arg0);

member this.AppendFormat : IFormatProvider * System.Text.CompositeFormat * 'TArg0 -> System.Text.StringBuilder

Public Function AppendFormat(Of TArg0) (provider As IFormatProvider, format As CompositeFormat, arg0 As TArg0) As StringBuilder

類型參數

TArg0

要格式化之第一個物件的型別。

參數

provider

IFormatProvider

物件，提供特定文化特性的格式資訊。

format

CompositeFormat

CompositeFormat。

arg0

TArg0

要格式化的第一個物件。

傳回

StringBuilder

附加作業完成之後，這個實例的參考。

例外狀況

ArgumentNullException

format null。

FormatException

格式專案的索引大於或等於提供的自變數數目。