Složené formátování

Funkce složeného formátování .NET přebírá jako vstup seznam objektů a řetězec složeného formátu. Složený řetězec formátu se skládá z pevného textu intermixovaného s indexovanými zástupnými symboly, označovanými jako formátovat položky. Tyto položky formátu odpovídají objektům v seznamu. 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.

Důležité

Místo použití složených formátových řetězců můžete použít interpolované řetězce , pokud je jazyk a jeho verze, které používáte, podporované. Interpolovaný řetězec obsahuje interpolované výrazy. Každý interpolovaný výraz se přeloží na hodnotu výrazu a zahrne se do výsledného řetězce při přiřazení řetězce. Další informace najdete v tématu Interpolace řetězců (referenční dokumentace jazyka C#) a interpolovaných řetězců (Referenční dokumentace jazyka Visual Basic).

Funkci složeného formátování podporují následující metody:

• String.Format, který vrátí formátovaný výsledný řetězec.
• StringBuilder.AppendFormat, který připojí formátovaný výsledný řetězec k objektu StringBuilder .
• Některá přetížení Console.WriteLine metody, která zobrazí formátovaný výsledný řetězec konzoly.
• Některá přetížení TextWriter.WriteLine metody, které zapisují formátovaný výsledný řetězec do datového proudu nebo souboru. Třídy odvozené z TextWriter, například StreamWriter a HtmlTextWriter, také sdílet tuto funkci.
• Debug.WriteLine(String, Object[]), který vypíše formátovanou zprávu do naslouchacích procesů trasování.
• , Trace.TraceError(String, Object[])Trace.TraceInformation(String, Object[])a Trace.TraceWarning(String, Object[]) metody, které výstup formátované zprávy trasovat naslouchací procesy.
• Metoda TraceSource.TraceInformation(String, Object[]) , která zapisuje informační metodu pro trasování naslouchacích procesů.

Složený formátovací řetězec

Složený řetězec formátu a seznam objektů se používají jako argumenty metod, které podporují funkci složeného formátování. 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. 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. Řetězcová reprezentace každého objektu nahrazuje odpovídající položku formátu.

Zvažte následující Format fragment kódu:

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

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

Pevný text je Name = a , hours = . Položky formátu jsou {0}, jejichž index 0 odpovídá objektu name, a {1:hh}, jehož index 1 odpovídá objektu DateTime.Now.

Syntaxe formátování položek

Jednotlivé položky formátu mají následující podobu a skládají se z následujících součástí:

{index[,alignment][:formatString]}

Jsou vyžadovány odpovídající složené závorky ({ a }).

Součást indexu

Povinná součást indexu , která se označuje také jako specifikátor parametru, je číslo začínající 0, které identifikuje odpovídající položku v seznamu objektů. To znamená, že položka formátu, jejíž specifikátor parametru je 0 formátovat první objekt v seznamu. Položka formátu, jejíž specifikátor parametru je 1 formátovat druhý objekt v seznamu atd. Následující příklad obsahuje čtyři specifikátory parametrů, číslované nuly až tři, které představují čísla menší než 10:

string primes = string.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                              2, 3, 5, 7);
Console.WriteLine(primes);

// The example displays the following output:
//      Four prime numbers: 2, 3, 5, 7

Dim primes As String = String.Format("Four prime numbers: {0}, {1}, {2}, {3}",
                                      2, 3, 5, 7)
Console.WriteLine(primes)

'The example displays the following output
'     Four prime numbers 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. Můžete například naformátovat stejnou číselnou hodnotu v šestnáctkovém, vědeckém a číselném formátu zadáním složeného řetězce formátu, například , jak "0x{0:X} {0:E} {0:N}"ukazuje následující příklad:

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. Pokud existují například tři objekty, můžete druhý, první a třetí objekt naformátovat zadáním složeného řetězce formátu, například {1} {0} {2}. Objekt, na který položka formátu neodkazuje, se ignoruje. A FormatException je vyvolán za běhu, pokud specifikátor parametru určuje položku mimo hranice seznamu objektů.

Komponenta zarovnání

Volitelná součást zarovnání je podepsané celé číslo označující upřednostňovanou šířku formátovaného pole. Pokud je hodnota zarovnání menší než délka formátovaného řetězce, zarovnání se ignoruje a délka formátovaného řetězce se použije jako šířka pole. Formátovaná data v poli jsou zarovnaná doprava, pokud je zarovnání kladné a zarovnané doleva, pokud je zarovnání záporné. Pokud je vyžadováno odsazení obsahu, jsou použity prázdné znaky. Čárka se vyžaduje, pokud je zadáno zarovnání .

Následující příklad definuje dvě pole, jedno obsahující jména zaměstnanců a druhá obsahující hodiny, které pracovaly za dva týdny. Složený formátovací řetězec zarovná názvy doleva v poli s 20 znaky a zarovná jejich hodiny do pole s 5 znaky. Standardní formátovací řetězec "N1" formátuje hodiny s jednou desetinnou číslicí.

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 counter = 0; counter < names.Length; counter++)
    Console.WriteLine("{0,-20} {1,5:N1}", names[counter], hours[counter]);

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

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}\n", "Name", "Hours")

For counter = 0 To names.Length - 1
    Console.WriteLine("{0,-20} {1,5:N1}", names(counter), hours(counter))
Next

'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

Formátovací komponenta řetězce

Volitelná komponenta formatString je formátovací řetězec, který je vhodný pro typ objektu, který je formátován. Můžete zadat:

• Standardní nebo vlastní řetězec číselného formátu, pokud je odpovídající objekt číselnou hodnotou.
• Standardní nebo vlastní řetězec formátu data a času, pokud je odpovídajícím objektem DateTime objekt.
• Řetězec formátu výčtu, pokud je odpovídající objekt hodnotou výčtu.

Pokud není zadán formátString , použije se obecný specifikátor formátu ("G") pro číselný typ, datum a čas nebo výčtu. Dvojtečka je vyžadována, pokud je zadán formátString .

Následující tabulka uvádí typy nebo kategorie typů v knihovně tříd .NET, které podporují předdefinovanou sadu formátových řetězců, a poskytuje odkazy na články, které uvádějí podporované řetězce formátu. Formátování řetězců je rozšiřitelný mechanismus, který umožňuje definovat nové formátovací řetězce pro všechny existující typy a definovat sadu formátových řetězců podporovaných typem definovaným aplikací.

Další informace najdete v IFormattable článcích o rozhraní a ICustomFormatter rozhraní.

Typ nebo kategorie typů	Seznamte se s
Typy data a času (DateTime, DateTimeOffset)	Řetězce standardního formátu data a času Řetězce vlastního formátu data a času
Typy výčtu (všechny typy odvozené od System.Enum)	Výčet řetězců formátu
Číselné typy (BigInteger, Byte, , Decimal, Double, Int32) Int64UInt64Int16SByteSingleUInt16UInt32	Standardní řetězce pro formátování čísel Vlastní řetězce číselného formátu
Guid	Guid.ToString(String)
TimeSpan	Standardní řetězce formátu TimeSpan Vlastní řetězce formátu TimeSpan

Zapouzdření složených závorek

Levá a pravá složená závorka se interpretuje jako počátek a konec položky formátu. Chcete-li zobrazit literální levou složenou závorku nebo pravou složenou závorku, musíte použít řídicí sekvenci. Zadáním dvou levých složených závorek ({{) v pevném textu zobrazíte jednu levou složenou závorku ({) nebo dvě pravá složená závorka (}}), aby se zobrazila jedna pravá složená závorka (}).

Řídicí složené závorky s položkou formátu se analyzují odlišně mezi rozhraním .NET a .NET Framework.

.NET

Složené závorky můžou být uvozené kolem položky formátu. Představte si například položku {{{0:D}}}formátu, která má zobrazit levou složenou závorku, číselnou hodnotu formátovanou jako desetinné číslo a pravou složenou závorku. Položka formátu je interpretována následujícím způsobem:

1. První dvě počáteční složené závorky ({{) jsou uvozené a poskytují jednu levou složenou závorku.
2. Další tři znaky ({0:) se interpretují jako začátek položky formátu.
3. Další znak (D) je interpretován jako specifikátor standardního číselného formátu Decimal.
4. Další složená závorka (}) se interpretuje jako konec položky formátu.
5. Poslední dvě uzavírací závorky jsou uvozené a poskytují jednu pravou složenou závorku.
6. Konečný výsledek, který se zobrazí, je literál řetězec, {6324}.

int value = 6324;
string output = string.Format("{{{0:D}}}", value);

Console.WriteLine(output);
// The example displays the following output:
//       {6324}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}", value)

Console.WriteLine(output)

'The example displays the following output
'      {6324}

.NET Framework

Složené závorky v položce formátu se interpretují postupně v pořadí, ve kterém jsou zjištěny. Interpretace vnořených závorek se nepodporuje.

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. Představte si například položku {{{0:D}}}formátu, která má zobrazit levou složenou závorku, číselnou hodnotu formátovanou jako desetinné číslo a pravou složenou závorku. Položka formátu je však interpretována následujícím způsobem:

1. První dvě počáteční složené závorky ({{) jsou uvozené a poskytují jednu levou složenou závorku.
2. Další tři znaky ({0:) se interpretují jako začátek položky formátu.
3. Další znak (D) by byl interpretován jako specifikátor standardního číselného formátu Decimal, ale další dva řídicí složené závorky (}}) poskytují jednu složenou závorku. Vzhledem k tomu, že výsledný řetězec (D}) není standardní specifikátor číselného formátu, výsledný řetězec se interpretuje jako řetězec vlastního formátu, který znamená zobrazit literálový řetězec D}.
4. Poslední složená závorka (}) se interpretuje jako konec položky formátu.
5. Konečný výsledek, který se zobrazí, je literál řetězec, {D}. Číselná hodnota, která se má formátovat, se nezobrazí.

int value = 6324;
string output = string.Format("{{{0:D}}}",
                              value);
Console.WriteLine(output);

// The example displays the following output:
//       {D}

Dim value As Integer = 6324
Dim output As String = String.Format("{{{0:D}}}",
                                     value)
Console.WriteLine(output)

'The example displays the following output:
'      {D}

Jedním ze způsobů, jak napsat kód, aby nedocházelo k chybné interpretaci řídicích závorek a formátování položek, je formátování složených závorek a formátování položek samostatně. To znamená, že v první operaci formátu zobrazte literálovou levou složenou závorku. V další operaci zobrazte výsledek položky formátu a v konečné operaci zobrazte literálovou pravou složenou závorku. Tento přístup ilustruje následující příklad:

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}

Zpracování objednávky

Pokud volání složené metody formátování obsahuje IFormatProvider argument, jehož hodnota není null, modul runtime volá jeho IFormatProvider.GetFormat metodu k vyžádání ICustomFormatter implementace. Pokud metoda může vrátit ICustomFormatter implementaci, je uložena v mezipaměti během volání složené metody formátování.

Každá hodnota v seznamu parametrů, která odpovídá položce formátu, se převede na řetězec následujícím způsobem:

1. Pokud je nullhodnota, která má být naformátována, vrátí se prázdný řetězec String.Empty .

2. ICustomFormatter Pokud je k dispozici implementace, modul runtime volá svou Format metodu. Modul runtime předá hodnotu položky formatString formátu (nebo null pokud není k dispozici) metodě. Modul runtime také předá implementaci IFormatProvider metodě. Pokud volání ICustomFormatter.Format metody vrátí null, provádění pokračuje k dalšímu kroku. V opačném případě se vrátí výsledek ICustomFormatter.Format volání.

3. Pokud hodnota implementuje IFormattable rozhraní, volá se metoda rozhraní ToString(String, IFormatProvider) . Pokud je v položce formátu, je hodnota formatString předána metodě. null V opačném případě se předá. Argument IFormatProvider je určen následujícím způsobem:

   • Pokud je pro číselnou hodnotu volána složená metoda formátování s argumentem bez hodnoty null IFormatProvider , modul runtime požaduje NumberFormatInfo objekt z jeho IFormatProvider.GetFormat metody. Pokud není možné zadat jednu, pokud je nullhodnota argumentu , nebo pokud složená metoda formátování nemá IFormatProvider parametr, NumberFormatInfo použije se objekt pro aktuální jazykovou verzi.

   • Pro hodnotu data a času, pokud je volána složená metoda formátování s argumentem non-null IFormatProvider , modul runtime vyžádá DateTimeFormatInfo objekt z jeho IFormatProvider.GetFormat metody. V následujících situacích DateTimeFormatInfo se místo toho použije objekt pro aktuální jazykovou verzi:

     • Metoda IFormatProvider.GetFormat nemůže zadat DateTimeFormatInfo objekt.
     • Hodnota argumentu je null.
     • Složená metoda formátování nemá IFormatProvider parametr.

   • Pro objekty jiných typů, pokud je volána složená metoda formátování s argumentem IFormatProvider , jeho hodnota je předána přímo implementaci IFormattable.ToString . null Jinak se předá implementaciIFormattable.ToString.

4. Volá se metoda bez ToString parametrů typu, která buď přepíše Object.ToString() nebo dědí chování své základní třídy. V tomto případě je formátovací řetězec určený formatString komponentou v položce formátu, pokud je k dispozici, ignorován.

Zarovnání se použije po provedení předchozích kroků.

Příklady kódu

Následující příklad ukazuje jeden řetězec vytvořený pomocí složeného formátování a druhý vytvořený pomocí metody objektu ToString . Oba typy formátování poskytují stejné výsledky.

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 americké anglické jazykové verzi.

Console.WriteLine zveřejňuje stejné funkce jako String.Format. Jediným rozdílem mezi těmito dvěma metodami je, že String.Format vrátí výsledek jako řetězec, zatímco Console.WriteLine zapíše výsledek do výstupního datového proudu přidruženého k objektu Console . Následující příklad používá metodu Console.WriteLine k formátování hodnoty myNumber na hodnotu měny:

int myNumber = 100;
Console.WriteLine("{0:C}", myNumber);

// The example displays the following output
// if en-US is the current culture:
//        $100.00

Dim myNumber As Integer = 100
Console.WriteLine("{0:C}", myNumber)

'The example displays the following output
'if en-US Is the current culture:
'       $100.00

Následující příklad ukazuje formátování více objektů, včetně formátování jednoho objektu dvěma různými způsoby:

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í. Argumenty formátované jsou umístěny mezi svislými znaky pruhu (|) pro zvýraznění výsledného zarovnání.

string firstName = "Fred";
string lastName = "Opals";
int myNumber = 100;

string formatFirstName = string.Format("First Name = |{0,10}|", firstName);
string formatLastName = string.Format("Last Name =  |{0,10}|", lastName);
string formatPrice = string.Format("Price =      |{0,10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
Console.WriteLine(formatPrice);
Console.WriteLine();

formatFirstName = string.Format("First Name = |{0,-10}|", firstName);
formatLastName = string.Format("Last Name =  |{0,-10}|", lastName);
formatPrice = string.Format("Price =      |{0,-10:C}|", myNumber);
Console.WriteLine(formatFirstName);
Console.WriteLine(formatLastName);
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 firstName As String = "Fred"
Dim lastName As String = "Opals"
Dim myNumber As Integer = 100

Dim formatFirstName As String = String.Format("First Name = |{0,10}|", firstName)
Dim formatLastName As String = String.Format("Last Name =  |{0,10}|", lastName)
Dim formatPrice As String = String.Format("Price =      |{0,10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
Console.WriteLine(formatPrice)
Console.WriteLine()

formatFirstName = String.Format("First Name = |{0,-10}|", firstName)
formatLastName = String.Format("Last Name =  |{0,-10}|", lastName)
formatPrice = String.Format("Price =      |{0,-10:C}|", myNumber)
Console.WriteLine(formatFirstName)
Console.WriteLine(formatLastName)
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é

• WriteLine
• String.Format
• Interpolace řetězců (C#)
• Interpolace řetězců (Visual Basic)
• Typy formátování
• Standardní řetězce pro formátování čísel
• Vlastní řetězce číselného formátu
• Řetězce standardního formátu data a času
• Řetězce vlastního formátu data a času
• Standardní řetězce formátu TimeSpan
• Vlastní řetězce formátu TimeSpan
• Výčet řetězců formátu