Kombinierte Formatierung
Aktualisiert: November 2007
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 Zahlenformatzeichenfolge an, wenn das entsprechende Objekt ein numerischer Wert ist, eine Formatzeichenfolge für Datum und Uhrzeit, wenn das entsprechende Objekt ein DateTime-Objekt ist, bzw. eine Enumerationsformatzeichenfolge, 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.
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.
Verarbeitungsreihenfolge
Wenn der zu formatierende Wert null (Nothing in Visual Basic) ist, wird eine leere Zeichenfolge ("") zurückgegeben.
Wenn der zu formatierende Typ die ICustomFormatter-Schnittstelle implementiert, wird die ICustomFormatter.Format-Methode aufgerufen.
Wenn der Typ durch den vorherigen Schritt nicht formatiert wird und der Typ die IFormattable-Schnittstelle implementiert, wird die IFormattable.ToString-Methode aufgerufen.
Wenn der Typ durch den vorherigen Schritt nicht formatiert wird, führt dies zu einem Aufruf der ToString-Methode des Typs, die von der Object-Klasse geerbt wird.
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 macht die gleiche Funktionalität wie String.Format verfügbar. Der einzige Unterschied zwischen den zwei Methoden besteht darin, dass String.Format das Ergebnis als Zeichenfolge zurückgibt, während Console.WriteLine das Ergebnis in den Ausgabestream 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)
int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);
Dieser Code zeigt auf der Konsole von Computern, deren aktuelle Kultur Englisch (USA) ist, $100.00 an.
Das folgende Beispiel veranschaulicht die Formatierung mehrerer Objekte, wobei ein Objekt auf zwei Arten formatiert wird.
Dim myName As String = "Fred"
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
myName, DateTime.Now)
string myName = "Fred";
String.Format("Name = {0}, hours = {1:hh}, minutes = {1:mm}",
myName, DateTime.Now);
Die Ausgabe der oben stehenden Zeichenfolge lautet "Name = Fred, hours = 07, minutes = 23", wobei diese Zahlen die aktuelle Uhrzeit widerspiegeln.
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)
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)
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);
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);
Durch den oben stehenden Code wird bei der Kultur Englisch (USA) Folgendes auf der Konsole angezeigt. Bei anderen Kulturen werden unterschiedliche Währungssymbole und Trennzeichen angezeigt.
First Name = | Fred|
Last Name = | Opals|
Price = | $100.00|
First Name = |Fred |
Last Name = |Opals |
Price = |$100.00 |