Kombinierte Formatierung

Artikel
08/10/2011

Das Feature für die kombinierte Formatierung in .NET Framework verwendet als Eingabe eine Liste von Objekten und eine kombinierte Formatzeichenfolge. Eine kombinierte Formatzeichenfolge besteht aus festgelegtem Text mit indizierten Platzhaltern, so genannten Formatelementen, die den Objekten in der Liste entsprechen. Der Formatierungsvorgang liefert eine Ergebniszeichenfolge, die sich aus dem ursprünglichen festgelegten Text und der Zeichenfolgendarstellung der Objekte in der Liste zusammensetzt.

Das Feature für die kombinierte Formatierung wird von Methoden wie Format, AppendFormat und einigen Überladungen von WriteLine und TextWriter.WriteLine unterstützt. Die String.Format-Methode liefert eine formatierte Ergebniszeichenfolge, die AppendFormat-Methode fügt eine formatierte Ergebniszeichenfolge an ein StringBuilder-Objekt an, die Console.WriteLine-Methode zeigt eine formatierte Ergebniszeichenfolge auf der Konsole an, und die TextWriter.WriteLine-Methode schreibt die formatierte Ergebniszeichenfolge in einen Stream oder eine Datei.

Kombinierte 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. Das Feature 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.

Betrachten Sie das folgende Format-Codefragment:

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

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

Der feste Text ist "Name = " und ", hours = ". Die Formatelemente sind "{0}" mit dem Index 0 (null), was dem Objekt myName entspricht, und "{1:hh}" mit dem Index 1, was dem Objekt DateTime.Now entspricht.

Formatelementsyntax

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

{Index[,Ausrichtung][:Formatzeichenfolge]}

Die übereinstimmenden geschweiften Klammern ("{" and "}") 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 bedeutet, dass das Formatelement mit dem Parameterbezeichner 0 (null) das erste Objekt in der Liste formatiert, und das Formatelement mit dem Parameterbezeichner 1 formatiert das zweite Objekt in der Liste usw.

Mehrere Formatelemente können auf dasselbe Element in der Objektliste verweisen, indem derselbe Parameterbezeichner festgelegt wird. Sie können beispielsweise denselben numerischen Wert im hexadezimalen, im wissenschaftlichen und im Zahlenformat formatieren, indem Sie eine kombinierte Formatzeichenfolge wie die Folgende angeben: "{0:X} {0:E} {0:N}".

Jedes Formatelement kann auf ein beliebiges Objekt in der Liste verweisen. Wenn beispielsweise drei Objekte vorliegen, können Sie das zweite, erste und dritte Objekt formatieren, indem Sie eine kombinierte Formatzeichenfolge wie die Folgende angeben: "{1} {0} {2}". Ein Objekt, auf das kein Formatelement verweist, wird ignoriert. Eine Laufzeitausnahme tritt auf, 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 für Ausrichtung kleiner als die Länge der formatierten Zeichenfolge ist, wird 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 Ausrichtung angegeben wird.

Formatzeichenfolgen-Komponente

Die optionale Komponente Formatzeichenfolge ist eine Formatzeichenfolge, die für den formatierten Objekttyp geeignet ist. Geben Sie eine standardmäßige oder eine benutzerdefinierte numerische Formatzeichenfolge an, wenn das entsprechende Objekt ein numerischer Wert ist. Geben Sie eine standardmäßige oder eine benutzerdefinierte Formatvorlage für Datum und Uhrzeit an, wenn das entsprechende Objekt ein DateTime-Objekt ist. Geben Sie eine Enumerationsformatzeichenfolge an, wenn das entsprechende Objekt ein Enumerationswert ist. Wenn Formatzeichenfolge nicht festgelegt ist, wird der allgemeine Formatbezeichner ("G") verwendet. Der Doppelpunkt ist erforderlich, wenn Formatzeichenfolge angegeben wird.

Hinweis
Eine Liste der standardmäßigen und benutzerdefinierten numerischen Formatzeichenfolgen finden Sie unter Standardmäßige Zahlenformatzeichenfolgen und unter Benutzerdefinierte Zahlenformatzeichenfolgen.Eine Liste der standardmäßigen Datums- und Uhrzeitvorlagen finden Sie unter Datums- und Uhrzeitstandardformatzeichenfolgen und unter Benutzerdefinierte und DateTime-Formatzeichenfolgen.

Versehen von geschweiften Klammern mit Escapezeichen

Öffnende und schließende geschweifte Klammern werden als Beginn und Ende eines Formatelements interpretiert. Deshalb müssen Sie eine Escapesequenz verwenden, um eine literale öffnende bzw. schließende geschweifte Klammer anzuzeigen. Geben Sie zwei öffnende geschweifte Klammern ("{{") im festgelegten Text an, um eine öffnende geschweifte Klammer ("{") anzuzeigen, und geben Sie entsprechend zwei schließende geschweifte Klammern ("}}") an, um eine schließende geschweifte Klammer ("}") anzuzeigen. Geschweifte Klammern in einem Formatelement werden sequenziell in der Reihenfolge interpretiert, in der sie angetroffen werden. Die Interpretation geschachtelter geschweifter Klammern wird nicht unterstützt.

Die Art und Weise, wie geschweifte Klammern mit Escapezeichen interpretiert werden, kann zu unerwarteten Ergebnissen führen. Im folgenden Beispiel gibt es das Formatelement "{{{0:D}}}", das eine öffnende geschweifte Klammer anzeigen soll, einen numerischen Wert, der als Dezimalzahl formatiert ist, und eine schließende geschweifte Klammer. Das Formatelement wird aber tatsächlich wie folgt interpretiert:

Die ersten beiden öffnenden geschweiften Klammern ("{{") werden mit Escapezeichen versehen und ergeben eine öffnende geschweifte Klammer.
Die nächsten drei Zeichen ("{0":) werden als Anfang eines Formatelements interpretiert.
Das nächste Zeichen ("D") wird als Formatbezeichner für das numerische Standarddezimalformat interpretiert, und die nächsten beiden geschweiften Klammern mit Escapezeichen ergeben eine einzelne geschweifte Klammer. Da die entstehende Zeichenfolge ("D}") kein numerischer Standardformatbezeichner ist, wird sie als benutzerdefinierte Formatzeichenfolge interpretiert, d. h., es wird die Literalzeichenfolge "D}" angezeigt.
Die letzte geschweifte Klammer ("}") wird als Ende des Formatelements interpretiert.
Das Endergebnis, das angezeigt wird, ist die Literalzeichenfolge "{D}". Der numerische Wert, der formatiert werden sollte, wird nicht angezeigt.

Eine Möglichkeit, Code zu schreiben und dabei Probleme mit falsch interpretierten geschweiften Klammern und Formatelementen zu vermeiden, ist die separate Formatierung der geschweiften Klammern und Formatelemente. Zeigen Sie also beim ersten Formatierungsvorgang eine literale öffnende geschweifte Klammer, beim nächsten Formatierungsvorgang das Ergebnis des Formatelements und beim letzten Formatierungsvorgang eine literale schließende geschweifte Klammer an. Dieser Ansatz wird anhand des folgenden Beispiels veranschaulicht.

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

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

Verarbeitungsreihenfolge

Jeder Wert in der Parameterliste, der einem Formatelement entspricht, wird anhand der Schritte in der folgenden Liste in eine Zeichenfolge konvertiert. Wenn eine Bedingung in den ersten drei Schritten zu true ausgewertet wird, wird die Zeichenfolgendarstellung des Werts in diesem Schritt zurückgegeben, und nachfolgende Schritte werden nicht ausgeführt.

Wenn der zu formatierende Wert null ist, wird eine leere Zeichenfolge ("") zurückgegeben.
Wenn die kombinierte Formatierungsmethode einen Parameter vom Typ IFormatProvider enthält, der auch die ICustomFormatter-Schnittstelle implementiert, wird der Wert an die ICustomFormatter.Format-Methode übergeben.
Wenn der Wert die IFormattable-Schnittstelle implementiert, wird ihre IFormattable.ToString-Methode aufgerufen.
Die ToString-Methode, die überschrieben oder von der Object-Klasse geerbt wird, wird aufgerufen.

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.

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

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

Wenn das aktuelle Datum ein Donnerstag im Mai ist, ist 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 der Wert von MyInt mit der Console.WriteLine-Methode als Währungswert formatiert.

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

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

Das folgende Beispiel veranschaulicht die Formatierung mehrerer Objekte, wobei ein Objekt auf zwei Arten formatiert wird.

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

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

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.

Dim myFName As String = "Fred"
Dim myLName As String = "Opals"

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

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

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

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

Siehe auch

Freigeben über