Kombinierte Formatierung

Die Funktion für die kombinierte Formatierung in .NET verwendet als Eingabe eine Liste von Objekten und eine kombinierte Formatzeichenfolge. Eine zusammengesetzte Formatzeichenfolge besteht aus festem Text, der mit indizierten Platzhaltern kombiniert wird, die als Formatelemente bezeichnet werden. Diese Formatelemente entsprechen den Objekten in der Liste. Der Formatierungsvorgang liefert eine Ergebniszeichenfolge, die sich aus dem ursprünglichen festgelegten Text und der Zeichenfolgendarstellung der Objekte in der Liste zusammensetzt.

Wichtig

Anstatt zusammengesetzte Formatzeichenfolgen zu verwenden, können Sie interpolierte Zeichenfolgen verwenden, wenn die Sprache und die von Ihnen verwendete Version unterstützt werden. Eine interpolierte Zeichenfolge enthält interpolierte Ausdrücke. Jeder interpolierte Ausdruck wird mit dem Wert des Ausdrucks aufgelöst und in die Ergebniszeichenfolge aufgenommen, wenn die Zeichenfolge zugewiesen wird. Weitere Informationen finden Sie unter Zeichenfolgeninterpolation (C#-Referenz) und Interpolierte Zeichenfolgen (Visual Basic-Referenz).

Das Zusammengesetztformatierungsfeature wird durch die folgenden Methoden unterstützt:

Zusammengesetzte Formatzeichenfolge

Eine kombinierte Formatzeichenfolge und eine Objektliste dienen als Argumente von Methoden, die das Feature für die kombinierte Formatierung unterstützen. Die Quellzeichenfolge besteht aus 0 (null) oder mehreren Einheiten festgelegten Texts mit mindestens einem Formatelement. Der festgelegte Text ist eine von Ihnen ausgewählte beliebige Zeichenfolge. Jedes Formatelement entspricht einem Objekt oder einer geschachtelten Struktur in der Liste. Die Funktion für die kombinierte Formatierung gibt eine neue Ergebniszeichenfolge zurück, in der jedes Formatelement durch die Zeichenfolgendarstellung des entsprechenden Objekts in der Liste ersetzt wird.

Berücksichtigen Sie das folgende Format Codefragment:

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

Der feste Text ist Name = und , hours = . Die Formatelemente sind {0}, deren Index 0 dem Objekt entspricht, und {1:hh}dessen Index von 1 dem Objekt nameDateTime.Nowentspricht.

Elementsyntax formatieren

Alle Formatelemente weisen die folgende Form auf und bestehen aus folgenden Komponenten:

{index[,alignment][:formatString]}

Die passenden Klammern ({ und }) sind erforderlich.

Indexkomponente

Bei der obligatorischen Komponente Index, dem so genannten Parameterbezeichner, handelt es sich um eine bei 0 (null) beginnende Zahl, mit der ein entsprechendes Element in der Objektliste angegeben wird. Das heißt, das Formatelement, dessen Parameterbezeichner 0 ist, formatiert das erste Objekt in der Liste. Das Formatelement, dessen Parameterbezeichner 1 ist, formatiert das zweite Objekt in der Liste und so weiter. Das folgende Beispiel enthält vier Parameterbezeichner, nummeriert null bis drei, um Primzahlen kleiner als 10 darzustellen:

string primes;
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7 );
Console.WriteLine(primes);
// The example displays the following output:
//      Prime numbers less than 10: 2, 3, 5, 7
Dim primes As String
primes = String.Format("Prime numbers less than 10: {0}, {1}, {2}, {3}",
                       2, 3, 5, 7)
Console.WriteLine(primes)
' The example displays the following output:
'      Prime numbers less than 10: 2, 3, 5, 7

Mehrere Formatelemente können auf dasselbe Element in der Objektliste verweisen, indem derselbe Parameterbezeichner festgelegt wird. Sie können z. B. den gleichen numerischen Wert in hexadezimalem, wissenschaftlichem und Zahlenformat formatieren, indem Sie eine zusammengesetzte Formatzeichenfolge wie "0x{0:X} {0:E} {0:N}" angeben, wie das folgende Beispiel zeigt:

string multiple = String.Format("0x{0:X} {0:E} {0:N}",
                                Int64.MaxValue);
Console.WriteLine(multiple);
// The example displays the following output:
//      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00
Dim multiple As String = String.Format("0x{0:X} {0:E} {0:N}",
                                       Int64.MaxValue)
Console.WriteLine(multiple)
' The example displays the following output:
'      0x7FFFFFFFFFFFFFFF 9.223372E+018 9,223,372,036,854,775,807.00

Jedes Formatelement kann auf ein beliebiges Objekt in der Liste verweisen. Wenn beispielsweise drei Objekte vorhanden sind, können Sie das zweite, erste und dritte Objekt formatieren, indem Sie eine zusammengesetzte Formatzeichenfolge angeben, z {1} {0} {2}. B. . Ein Objekt, auf das nicht durch ein Formatelement verwiesen wird, wird ignoriert. Eine FormatException wird zur Laufzeit ausgelöst, wenn ein Parameterbezeichner auf ein Element außerhalb der Grenzen der Objektliste verweist.

Ausrichtungskomponente

Bei der optionalen Komponente Ausrichtung handelt es sich um eine ganze Zahl mit Vorzeichen, die die gewünschte formatierte Feldbreite angibt. Wenn der Wert der Ausrichtung kleiner als die Länge der formatierten Zeichenfolge ist, wird die Ausrichtung ignoriert, und die Länge der formatierten Zeichenfolge wird als Feldbreite verwendet. Die formatierten Daten im Feld werden bei einem positiven Wert für Ausrichtung rechtsbündig und bei einem negativen Wert für Ausrichtung linksbündig ausgerichtet. Wenn Füllzeichen erforderlich sind, werden Leerräume verwendet. Das Komma ist erforderlich, wenn die Ausrichtung angegeben wird.

Im folgenden Beispiel werden zwei Arrays definiert, eine, die die Namen von Mitarbeitern und den anderen enthält, die die Stunden enthalten, die sie über zwei Wochen gearbeitet haben. Die zusammengesetzte Formatzeichenfolge richtet die Namen in einem 20-Zeichen-Feld links aus und richtet ihre Stunden rechts in einem 5-Zeichen-Feld aus. Die Standardformatzeichenfolge "N1" formatiert die Stunden mit einer Bruchzahl.

using System;

public class Example
{
   public static void Main()
   {
      string[] names = { "Adam", "Bridgette", "Carla", "Daniel",
                         "Ebenezer", "Francine", "George" };
      decimal[] hours = { 40, 6.667m, 40.39m, 82, 40.333m, 80,
                                 16.75m };

      Console.WriteLine("{0,-20} {1,5}\n", "Name", "Hours");
      for (int ctr = 0; ctr < names.Length; ctr++)
         Console.WriteLine("{0,-20} {1,5:N1}", names[ctr], hours[ctr]);
   }
}
// The example displays the following output:
//       Name                 Hours
//
//       Adam                  40.0
//       Bridgette              6.7
//       Carla                 40.4
//       Daniel                82.0
//       Ebenezer              40.3
//       Francine              80.0
//       George                16.8
Module Example
    Public Sub Main()
        Dim names() As String = {"Adam", "Bridgette", "Carla", "Daniel",
                                  "Ebenezer", "Francine", "George"}
        Dim hours() As Decimal = {40, 6.667d, 40.39d, 82, 40.333d, 80,
                                   16.75d}

        Console.WriteLine("{0,-20} {1,5}", "Name", "Hours")
        Console.WriteLine()
        For ctr As Integer = 0 To names.Length - 1
            Console.WriteLine("{0,-20} {1,5:N1}", names(ctr), hours(ctr))
        Next
    End Sub
End Module
' The example displays the following output:
'       Name                 Hours
'
'       Adam                  40.0
'       Bridgette              6.7
'       Carla                 40.4
'       Daniel                82.0
'       Ebenezer              40.3
'       Francine              80.0
'       George                16.8

Zeichenfolgenkomponente formatieren

Die optionale formatString-Komponente ist eine Formatzeichenfolge, die für den Typ des formatierten Objekts geeignet ist. Sie können Folgendes angeben:

  • Eine standard- oder benutzerdefinierte numerische Formatzeichenfolge, wenn das entsprechende Objekt ein numerischer Wert ist.
  • Eine Standard- oder benutzerdefinierte Datums- und Uhrzeitformatzeichenfolge, wenn das entsprechende Objekt ein DateTime Objekt ist.
  • Eine Enumerationsformatzeichenfolge , wenn das entsprechende Objekt ein Enumerationswert ist.

Wenn formatString nicht angegeben wird, wird der allgemeine Formatbezeichner ("G") für einen numerischen, Datums- und Uhrzeit- oder Enumerationstyp verwendet. Der Doppelpunkt ist erforderlich, wenn Formatzeichenfolge angegeben wird.

In der folgenden Tabelle sind Typen oder Kategorien von Typen in der .NET-Klassenbibliothek aufgeführt, die einen vordefinierten Satz von Formatzeichenfolgen unterstützen und Links zu den Artikeln bereitstellen, die die unterstützten Formatzeichenfolgen auflisten. Die Zeichenfolgenformatierung ist ein erweiterbarer Mechanismus, der es ermöglicht, neue Formatzeichenfolgen für alle vorhandenen Typen zu definieren und einen Satz von Formatzeichenfolgen zu definieren, die von einem anwendungsspezifischen Typ unterstützt werden.

Weitere Informationen finden Sie in den Artikeln und ICustomFormatter SchnittstellenIFormattable.

Typ oder Typkategorie Siehe
Datums-/Zeittypen (DateTime, DateTimeOffset) Standard-Formatzeichenfolgen für Datum und Uhrzeit

Benutzerdefinierte Formatzeichenfolgen für Datum und Uhrzeit
Enumerationstypen (alle Typen abgeleitet von System.Enum) Enumerationsformatzeichenfolgen
Numerische Typen (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Standardmäßige Zahlenformatzeichenfolgen

Benutzerdefinierte Zahlenformatzeichenfolgen
Guid Guid.ToString(String)
TimeSpan TimeSpan-Standardformatzeichenfolgen

Benutzerdefinierte TimeSpan-Formatzeichenfolgen

Ausfangen von Klammern

Öffnende und schließende geschweifte Klammern werden als Beginn und Ende eines Formatelements interpretiert. Um eine Literal öffnende Klammer oder eine schließende Klammer anzuzeigen, müssen Sie eine Escapesequenz verwenden. Geben Sie zwei öffnende Klammern () im festen Text an, um eine öffnende Klammer () oder zwei schließende}} Klammern () anzuzeigen, um eine schließende Klammer () anzuzeigen ({{}).{ Klammern in einem Formatelement werden sequenziell in der Reihenfolge interpretiert, in der sie auftreten. Das Interpretieren geschachtelter Klammern wird nicht unterstützt.

Die Art und Weise, wie geschweifte Klammern mit Escapezeichen interpretiert werden, kann zu unerwarteten Ergebnissen führen. Ziehen Sie beispielsweise das Formatelement {{{0:D}}}in Betracht, das eine öffnende Klammer, einen numerischen Wert, der als Dezimalzahl formatiert ist, und eine schließende Klammer anzuzeigen. Das Formatelement wird jedoch auf folgende Weise interpretiert:

  1. Die ersten beiden öffnenden Klammern ({{) werden entweicht und geben eine öffnende Klammer ab.
  2. Die nächsten drei Zeichen ({0:) werden als Anfang eines Formatelements interpretiert.
  3. Das nächste Zeichen () würde als Dezimalformat-Formatbezeichner interpretiert, aber die nächsten beiden escaped Klammern (D}}) liefern eine einzelne Klammer. Da die resultierende Zeichenfolge (D}) kein standard numerischer Formatbezeichner ist, wird die resultierende Zeichenfolge als benutzerdefinierte Formatzeichenfolge interpretiert, die die Literalzeichenfolge D}anzeigt.
  4. Die letzte Klammer (}) wird als Ende des Formatelements interpretiert.
  5. Das endgültige Ergebnis, das angezeigt wird, ist die Literalzeichenfolge, {D}. Der numerische Wert, der formatiert werden soll, wird nicht angezeigt.

Eine Möglichkeit, Ihren Code zu schreiben, um zu vermeiden, dass die escaped-Klammern und Formatelemente nicht interpretiert werden, ist das Formatieren der Klammern und Formatelemente separat. Das heißt, im ersten Formatvorgang wird eine Literal-Öffnende Klammer angezeigt. Zeigen Sie im nächsten Vorgang das Ergebnis des Formatelements an, und zeigen Sie im endgültigen Vorgang eine Literal schließende Klammer an. Im folgenden Beispiel wird dieser Ansatz veranschaulicht:

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

Verarbeitungsreihenfolge

Wenn der Aufruf der zusammengesetzten Formatierungsmethode ein Argument enthält, dessen Wert nicht nullist, ruft die Laufzeit die IFormatProvider.GetFormat Methode auf, um eine ICustomFormatterIFormatProvider Implementierung anzufordern. Wenn die Methode eine ICustomFormatter Implementierung zurückgeben kann, wird sie für die Dauer des Aufrufs der zusammengesetzten Formatierungsmethode zwischengespeichert.

Jeder Wert in der Parameterliste, der einem Formatelement entspricht, wird wie folgt in eine Zeichenfolge konvertiert:

  1. Wenn der zu formatierende Wert null ist, wird eine leere Zeichenfolge (String.Empty) zurückgegeben.

  2. Wenn eine ICustomFormatter-Implementierung verfügbar ist, ruft die Laufzeit die Format-Methode auf. Die Laufzeit übergibt den Wert des Formatelements formatString (oder null wenn es nicht vorhanden ist) an die Methode. Die Laufzeit übergibt auch die IFormatProvider Implementierung an die Methode. Wenn der Aufruf der ICustomFormatter.Format Methode zurückgegeben wird null, wird die Ausführung zum nächsten Schritt fortgesetzt. Andernfalls wird das Ergebnis des ICustomFormatter.Format Anrufs zurückgegeben.

  3. Wenn der Wert die IFormattable-Schnittstelle implementiert, wird die ToString(String, IFormatProvider)-Methode der Schnittstelle aufgerufen. Wenn ein Element im Formatelement vorhanden ist, wird der FormatString-Wert an die Methode übergeben. null Andernfalls wird er übergeben. Das IFormatProvider-Argument wird wie folgt bestimmt:

  4. Die parameterlose ToString-Methode des Typs, die entweder Object.ToString() überschreibt oder das Verhalten ihrer Basisklasse erbt, wird aufgerufen. In diesem Fall wird die formatzeichenfolge, die von der formatString Komponente im Formatelement angegeben wird, falls vorhanden, ignoriert.

Die Ausrichtung wird angewendet, nachdem die vorhergehenden Schritte durchgeführt wurden.

Codebeispiele

Das folgende Beispiel stellt eine Zeichenfolge dar, die mit der kombinierten Formatierung erstellt wurde, und eine weitere, die mit der ToString-Methode eines Objekts erstellt wurde. Beide Formatierungen führen zum gleichen Ergebnis.

string FormatString1 = String.Format("{0:dddd MMMM}", DateTime.Now);
string FormatString2 = DateTime.Now.ToString("dddd MMMM");
Dim FormatString1 As String = String.Format("{0:dddd MMMM}", DateTime.Now)
Dim FormatString2 As String = DateTime.Now.ToString("dddd MMMM")

Wenn das aktuelle Datum ein Donnerstag im Mai ist, lautet der Wert beider Zeichenfolgen im vorherigen Beispiel Thursday May in der Kultur Englisch (USA).

Console.WriteLine stellt die gleiche Funktionalität wie String.Format bereit. Der einzige Unterschied zwischen den beiden Methoden besteht darin, dass String.Format das Ergebnis als Zeichenfolge zurückgibt, während Console.WriteLine das Ergebnis in den Ausgabestrom schreibt, der dem Console-Objekt zugeordnet ist. Im folgenden Beispiel wird die Console.WriteLine Methode verwendet, um den Wert eines MyInt Währungswerts zu formatieren:

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

Im folgenden Beispiel wird die Formatierung mehrerer Objekte veranschaulicht, einschließlich der Formatierung eines Objekts auf zwei verschiedene Arten:

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

Das folgende Beispiel veranschaulicht die Verwendung der Ausrichtung beim Formatieren. Die zu formatierenden Argumente werden zwischen senkrechte Striche („|“) platziert, um die resultierende Ausrichtung zu kennzeichnen.

string myFName = "Fred";
string myLName = "Opals";
int myInt = 100;
string FormatFName = String.Format("First Name = |{0,10}|", myFName);
string FormatLName = String.Format("Last Name = |{0,10}|", myLName);
string FormatPrice = String.Format("Price = |{0,10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
Console.WriteLine();

FormatFName = String.Format("First Name = |{0,-10}|", myFName);
FormatLName = String.Format("Last Name = |{0,-10}|", myLName);
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt);
Console.WriteLine(FormatFName);
Console.WriteLine(FormatLName);
Console.WriteLine(FormatPrice);
// The example displays the following output on a system whose current
// culture is en-US:
//          First Name = |      Fred|
//          Last Name = |     Opals|
//          Price = |   $100.00|
//
//          First Name = |Fred      |
//          Last Name = |Opals     |
//          Price = |$100.00   |
Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

Dim myInt As Integer = 100
Dim FormatFName As String = String.Format("First Name = |{0,10}|", myFName)
Dim FormatLName As String = String.Format("Last Name = |{0,10}|", myLName)
Dim FormatPrice As String = String.Format("Price = |{0,10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
Console.WriteLine()

FormatFName = String.Format("First Name = |{0,-10}|", myFName)
FormatLName = String.Format("Last Name = |{0,-10}|", myLName)
FormatPrice = String.Format("Price = |{0,-10:C}|", myInt)
Console.WriteLine(FormatFName)
Console.WriteLine(FormatLName)
Console.WriteLine(FormatPrice)
' The example displays the following output on a system whose current
' culture is en-US:
'          First Name = |      Fred|
'          Last Name = |     Opals|
'          Price = |   $100.00|
'
'          First Name = |Fred      |
'          Last Name = |Opals     |
'          Price = |$100.00   |

Siehe auch