Složené formátováníComposite Formatting

Funkce složeného formátování .NET přebírá seznam objektů a složený řetězec formátu jako vstup.The .NET composite formatting feature takes a list of objects and a composite format string as input. Složený řetězec formátu se skládá z pevného textu smíšeného s indexovanými zástupnými symboly nazvanými „položky formátu“, které odpovídají objektům v seznamu.A composite format string consists of fixed text intermixed with indexed placeholders, called format items, that correspond to the objects in the list. Výsledkem operace formátování je výsledný řetězec, který se skládá z původního pevného textu smíšeného s řetězcovou reprezentací objektů v seznamu.The formatting operation yields a result string that consists of the original fixed text intermixed with the string representation of the objects in the list.

Důležité

Namísto použití složených formátovacích řetězců můžete použít interpolované řetězce , pokud jazyk a jazykovou verzi, kterou používáte, podporuje.Instead of using composite format strings, you can use interpolated strings if the language and language version that you're using support them. Interpolovaný řetězec je řetězec, který obsahuje interpolovaných výrazů.An interpolated string is a string that contains interpolated expressions. Každý interpolovaný výraz je přeložit výraz hodnotu a zahrnuté ve výsledném řetězci, když se přiřadí řetězec.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Další informace naleznete v tématu interpolace řetězce (C# referenční) a interpolované řetězce (Visual Basic odkaz).For more information, see String interpolation (C# Reference) and Interpolated strings (Visual Basic Reference).

Funkce složeného formátování je podporována například následujícími metodami:The composite formatting feature is supported by methods such as the following:

Složený řetězec formátuComposite Format String

Složený řetězec formátu a seznam objektů se používají jako argumenty metod, které podporují funkci složeného formátování.A composite format string and object list are used as arguments of methods that support the composite formatting feature. Složený řetězec formátu se skládá z žádného výskytu nebo několika výskytů pevného textu smíšeného s jednou nebo několika položkami formátu.A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. Pevný text je jakýkoli řetězec, který si zvolíte, a jednotlivé položky formátu odpovídají objektu nebo ohraničené struktuře v seznamu.The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. Funkce složeného formátování vrátí nový výsledný řetězec, kde každá položka formátu je nahrazena řetězcovou reprezentací odpovídajícího objektu v seznamu.The composite formatting feature returns a new result string where each format item is replaced by the string representation of the corresponding object in the list.

Vezměte v úvahu Format následující fragment kódu.Consider the following Format code fragment.

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)

Pevný text jeName = "" a ", hours = ".The fixed text is "Name = " and ", hours = ". Položky formátu jsou{0}"", jejichž index je 0, který odpovídá objektu namea "{1:hh}", jehož index je 1, což odpovídá objektu DateTime.Now.The format items are "{0}", whose index is 0, which corresponds to the object name, and "{1:hh}", whose index is 1, which corresponds to the object DateTime.Now.

Syntaxe položky formátuFormat Item Syntax

Jednotlivé položky formátu mají následující podobu a skládají se z následujících součástí:Each format item takes the following form and consists of the following components:

{ index[,alignment][:formatString]}{ index[,alignment][:formatString]}

Jsou požadovány odpovídající složené závorky ("{" a "}").The matching braces ("{" and "}") are required.

Součást IndexIndex Component

Povinná součást indexu , označovaná také jako specifikátor parametru, je číslo od 0, které identifikuje odpovídající položku v seznamu objektů.The mandatory index component, also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. To znamená, že položka formátu, jejíž specifikátor parametru je 0, formátuje první objekt v seznamu, položka formátu, jejíž specifikátor parametru je 1, formátuje druhý objekt v seznamu atd.That is, the format item whose parameter specifier is 0 formats the first object in the list, the format item whose parameter specifier is 1 formats the second object in the list, and so on. Následující příklad obsahuje čtyři specifikátory parametrů, očíslované nula až tři, aby představovaly hlavní čísla menší než deset:The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than ten:

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

Více položek formátu může odkazovat na stejný prvek v seznamu objektů zadáním stejného specifikátoru parametru.Multiple format items can refer to the same element in the list of objects by specifying the same parameter specifier. Můžete například formátovat stejnou číselnou hodnotu v šestnáctkovém, vědeckém a číselném formátu zadáním složeného formátovacího řetězce, jako například: "0x{0:X} {0:E} ",jak{0:N}ukazuje následující příklad.For example, you can format the same numeric value in hexadecimal, scientific, and number format by specifying a composite format string such as : "0x{0:X} {0:E} {0:N}", as the following example shows.

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

Každá položka formátu může odkazovat na libovolný objekt v seznamu.Each format item can refer to any object in the list. Například pokud existují tři objekty, lze naformátovat druhý, první a třetí objekt zadáním složeného formátu řetězce, například: "{1} {0} {2}".For example, if there are three objects, you can format the second, first, and third object by specifying a composite format string like this: "{1} {0} {2}". Objekt, který není odkazován položkou formátu, je ignorován.An object that is not referenced by a format item is ignored. Výjimka FormatException je vyvolána za běhu, pokud specifikátor parametru označuje položku mimo hranice seznamu objektů.A FormatException is thrown at runtime if a parameter specifier designates an item outside the bounds of the list of objects.

Součást ZarovnáníAlignment Component

Volitelná součást Zarovnání je celé číslo se znaménkem, které označuje upřednostňovanou šířku pole.The optional alignment component is a signed integer indicating the preferred formatted field width. Pokud je hodnota Zarovnání menší než délka formátovaného řetězce, Zarovnání je ignorováno a délka formátovaného řetězce se používá jako šířka pole.If the value of alignment is less than the length of the formatted string, alignment is ignored and the length of the formatted string is used as the field width. Formátovaná data v poli jsou zarovnána vpravo, pokud je Zarovnání kladné a zarovnané doleva, pokud je Zarovnání záporné.The formatted data in the field is right-aligned if alignment is positive and left-aligned if alignment is negative. Pokud je vyžadováno odsazení obsahu, jsou použity prázdné znaky.If padding is necessary, white space is used. Čárka je vyžadována, pokud je zadáno Zarovnání .The comma is required if alignment is specified.

Následující příklad definuje dvě pole, jednu, která obsahuje jména zaměstnanců a druhý, které obsahují hodiny, které pracovaly po dobu dvou týdnů.The following example defines two arrays, one containing the names of employees and the other containing the hours they worked over a two-week period. Složený řetězec formátu vlevo zarovná názvy v poli o 20 znacích a v poli s pěti znaky Zarovná hodiny vpravo.The composite format string left-aligns the names in a 20-character field, and right-aligns their hours in a 5-character field. Všimněte si, že standardní formátovací řetězec "N1" slouží také k formátování hodin s jednou zlomkovou číslicí.Note that the "N1" standard format string is also used to format the hours with one fractional digit.

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

Součást Řetězec formátuFormat String Component

Volitelná komponenta formatString je řetězec formátu, který je vhodný pro typ objektu, který se formátuje.The optional formatString component is a format string that is appropriate for the type of object being formatted. Zadejte standardní nebo vlastní řetězec číselného formátu, pokud je odpovídajícím objektem číselná hodnota, standardní nebo vlastní řetězec formátu data a času, pokud je odpovídajícím objektem DateTime objekt nebo řetězec formátu výčtu , pokud odpovídající objekt je hodnota výčtu.Specify a standard or custom numeric format string if the corresponding object is a numeric value, a standard or custom date and time format string if the corresponding object is a DateTime object, or an enumeration format string if the corresponding object is an enumeration value. Pokud není zadán vlastnost formatString , je použit obecný specifikátor formátu ("G") pro číselný, datum a čas nebo typ výčtu.If formatString is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. Dvojtečka je povinná, pokud je zadána vlastnost formatString .The colon is required if formatString is specified.

Následující tabulka uvádí seznam typů nebo kategorií typů v knihovně tříd rozhraní .NET Framework, které podporují předdefinovanou množinu řetězců formátu, a obsahuje odkazy na témata, která poskytují seznam jednotlivých řetězců formátu.The following table lists types or categories of types in the .NET Framework class library that support a predefined set of format strings, and provides links to the topics that list the supported format strings. Formátování řetězců poskytuje rozšířitelný mechanismus, který umožňuje definovat nové řetězce formátu pro všechny existující typy a také definovat množinu řetězců formátu podporovaných typem definovaného aplikací.Note that string formatting is an extensible mechanism that makes it possible to define new format strings for all existing types as well as to define a set of format strings supported by an application-defined type. Další informace najdete v IFormattable tématech rozhraní a. ICustomFormatterFor more information, see the IFormattable and ICustomFormatter interface topics.

Typ nebo kategorie typůType or type category Další informace naleznete v tématuSee
Typy data a času (DateTime, DateTimeOffset)Date and time types (DateTime, DateTimeOffset) Standardní řetězce formátu data a časuStandard Date and Time Format Strings

Vlastní řetězce formátu data a časuCustom Date and Time Format Strings
Výčtové typy (všechny typy odvozené System.Enumod)Enumeration types (all types derived from System.Enum) Výčet řetězců formátuEnumeration Format Strings
Číselné typy (BigInteger, Byte, Decimal, Double, ,Int16 ,Int64, ,Single,, ,UInt32) Int32 SByte UInt16 UInt64Numeric types (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Standardní řetězce číselného formátuStandard Numeric Format Strings

Vlastní řetězce číselného formátuCustom Numeric Format Strings
Guid Guid.ToString(String)
TimeSpan Standardní řetězce formátu TimeSpanStandard TimeSpan Format Strings

Vlastní řetězce formátu TimeSpanCustom TimeSpan Format Strings

Řídicí znaky pro složené závorkyEscaping Braces

Levá a pravá složená závorka se interpretuje jako počátek a konec položky formátu.Opening and closing braces are interpreted as starting and ending a format item. V důsledku toho je nutné použít sekvenci řídicích znaků pro zobrazení literální levé a pravé složené závorky.Consequently, you must use an escape sequence to display a literal opening brace or closing brace. Chcete-li zobrazit jednu levou složenou závorku ("{"), zadejte dvě levé složené závorky ("{{"); chcete-li zobrazit jednu pravou složenou závorku ("}"), zadejte dvě pravé závorky ("}}").Specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), or two closing braces ("}}") to display one closing brace ("}"). Složené závorky v položce formátu jsou interpretovány postupně v pořadí, v jakém se vyskytují.Braces in a format item are interpreted sequentially in the order they are encountered. Interpretace vnořených složených závorek není podporována.Interpreting nested braces is not supported.

Způsob, jakým jsou interpretovány složené závorky vložené pomocí řídicích znaků, může vést k neočekávaným výsledkům.The way escaped braces are interpreted can lead to unexpected results. Zvažte například položku formátu "{{{0:D}}}", která je určena k zobrazení levé složené závorky, numerické hodnoty formátované jako desetinné číslo a uzavírací závorky.For example, consider the format item "{{{0:D}}}", which is intended to display an opening brace, a numeric value formatted as a decimal number, and a closing brace. Položka formátu je však ve skutečnosti interpretována následujícím způsobem:However, the format item is actually interpreted in the following manner:

  1. První dvě levé složené závorky ("{{") jsou tvořeny řídicími znaky, a proto je výsledkem jedna levá závorka.The first two opening braces ("{{") are escaped and yield one opening brace.

  2. Následující tři znaky ("{0:") jsou interpretovány jako začátek položky formátu.The next three characters ("{0:") are interpreted as the start of a format item.

  3. Další znak ("D") je interpretován jako specifikátor standardního číselného desítkového formátu, ale další dvě závorky uvozené řídicími znaky ("}}") tvoří ve výsledku jednu složenou závorku.The next character ("D") would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces ("}}") yield a single brace. Vzhledem k tomu, že výsledný řetězec ("D}") není specifikátorem standardního číselného formátu, je výsledný řetězec interpretován jako řetězec vlastního formátu, což znamená, že se zobrazí řetězcový literál "D}".Because the resulting string ("D}") is not a standard numeric format specifier, the resulting string is interpreted as a custom format string that means display the literal string "D}".

  4. Poslední složená závorka ("}") je interpretována jako konec položky formátu.The last brace ("}") is interpreted as the end of the format item.

  5. Konečný výsledek, který se zobrazí, je řetězcový literál "{D}".The final result that is displayed is the literal string, "{D}". Číselná hodnota, která měla být formátována, se nezobrazí.The numeric value that was to be formatted is not displayed.

Jedním ze způsobů, jak napsat kód tak, aby nedocházelo k chybné interpretaci složených závorek s řídicími znaky, je provést formátování složených závorek a položek formátu odděleně.One way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format item separately. To znamená, že se v první operaci formátování zobrazí literální znak levé složené závorky, v další operaci se zobrazí výsledek položky formátu a nakonec se v poslední operaci zobrazí literální znak pravé složené závorky.That is, in the first format operation display a literal opening brace, in the next operation display the result of the format item, then in the final operation display a literal closing brace. Tento postup znázorňuje následující příklad.The following example illustrates this approach.

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}

Pořadí zpracováníProcessing Order

Pokud volání IFormatProvider metody složeného formátování obsahuje argument null, jehož hodnota není, modul runtime volá ICustomFormatter svou IFormatProvider.GetFormat metodu pro vyžádání implementace.If the call to the composite formatting method includes an IFormatProvider argument whose value is not null, the runtime calls its IFormatProvider.GetFormat method to request an ICustomFormatter implementation. Pokud metoda může vracet ICustomFormatter implementaci, je ukládána do mezipaměti po dobu trvání volání metody složeného formátování.If the method is able to return an ICustomFormatter implementation, it's cached for the duration of the call of the composite formatting method.

Každá hodnota v seznamu parametrů, která odpovídá položce formátu, je převedena na řetězec následujícím způsobem:Each value in the parameter list that corresponds to a format item is converted to a string as follows:

  1. Pokud je nullhodnota, která má být formátována, je String.Empty vrácen prázdný řetězec.If the value to be formatted is null, an empty string String.Empty is returned.

  2. Je- ICustomFormatter li k dispozici implementace, modul runtime Format volá svou metodu.If an ICustomFormatter implementation is available, the runtime calls its Format method. Předá metodu hodnoty formatString položky formátu, pokud je k dispozici, nebo null Pokud není IFormatProvider , společně s implementací.It passes the method the format item's formatString value, if one is present, or null if it's not, along with the IFormatProvider implementation. Pokud volání ICustomFormatter.Format metody vrátí null, provádění pokračuje k dalšímu kroku. v opačném případě je vrácen výsledek ICustomFormatter.Format volání.If the call to the ICustomFormatter.Format method returns null, execution proceeds to the next step; otherwise, the result of the ICustomFormatter.Format call is returned.

  3. Pokud hodnota implementuje IFormattable rozhraní, je volána ToString(String, IFormatProvider) Metoda rozhraní.If the value implements the IFormattable interface, the interface's ToString(String, IFormatProvider) method is called. Metodě je předána hodnota formatString , pokud je k dispozici ve formátu položky nebo null Pokud není.The method is passed the formatString value, if one is present in the format item, or null if it's not. IFormatProvider Argument je určen následujícím způsobem:The IFormatProvider argument is determined as follows:

  4. ToString Metoda bez parametrů typu, která buď Přepisuje Object.ToString() nebo dědí chování své základní třídy, je volána.The type's parameterless ToString method, which either overrides Object.ToString() or inherits the behavior of its base class, is called. V tomto případě je řetězec formátu určený komponentou formatString v položce formátu, pokud je přítomen, ignorován.In this case, the format string specified by the formatString component in the format item, if it's present, is ignored.

Zarovnání se použije po provedení předchozích kroků.Alignment is applied after the preceding steps have been performed.

Příklady kóduCode Examples

Následující příklad ukazuje jeden řetězec vytvořený pomocí složeného formátování a druhý vytvořený pomocí ToString metody objektu.The following example shows one string created using composite formatting and another created using an object's ToString method. Oba typy formátování poskytují stejné výsledky.Both types of formatting produce equivalent results.

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") 

Za předpokladu, že aktuální den je čtvrtek v květnu, hodnota obou řetězců v předchozím příkladu je Thursday May v USA. Anglická jazyková verze.Assuming that the current day is a Thursday in May, the value of both strings in the preceding example is Thursday May in the U.S. English culture.

Console.WriteLinezpřístupňuje stejné funkce jako String.Format.Console.WriteLine exposes the same functionality as String.Format. Jediným rozdílem mezi těmito dvěma metodami je String.Format , že vrátí výsledek jako řetězec, zatímco Console.WriteLine zapíše výsledek do Console výstupního datového proudu přidruženého k objektu.The only difference between the two methods is that String.Format returns its result as a string, while Console.WriteLine writes the result to the output stream associated with the Console object. Následující příklad používá Console.WriteLine metodu k naformátování MyInt hodnoty na hodnotu měny.The following example uses the Console.WriteLine method to format the value of MyInt to a currency value.

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

Následující příklad znázorňuje formátování většího počtu objektů, včetně formátování jednoho objektu dvěma různými způsoby.The following example demonstrates formatting multiple objects, including formatting one object two different ways.

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                 

Následující příklad znázorňuje použití zarovnání ve formátování.The following example demonstrates the use of alignment in formatting. Argumenty, které jsou formátovány, jsou umístěny mezi znaky svislé|čáry () pro zvýraznění výsledného zarovnání.The arguments that are formatted are placed between vertical bar characters (|) to highlight the resulting alignment.

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   |

Viz také:See also