Sdílet prostřednictvím

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ý formátovací řetězec se skládá z pevného textu prokládaného indexovanými zástupnými symboly, označovanými jako formátovací 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 vyhodnotí jako jeho hodnota a je zahrnut do výsledného řetězce, když je řetězec přiřazen. 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:

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

Složený formátovací řetězec 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 nuly nebo více úseků pevného textu proložených s jednou nebo více položkami formátu. Pevný text je libovolný řetězec, který zvolíte, a každá položka formátu odpovídá objektu nebo krabicové 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[,width][:formatString]}

Je třeba použít odpovídající složené závorky ({ a }).

Součást indexu

Povinná komponenta index , 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átuje první objekt v seznamu. Položka formátu, jejíž specifikátor parametru je 1, formátuje druhý objekt v seznamu a tak dále. 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ů.

Šířková komponenta

Volitelná width komponenta je podepsané celé číslo označující upřednostňovanou šířku formátovaného pole. Pokud je hodnota width menší než délka formátovaného řetězce, width bude ignorována a délka formátovaného řetězce se použije jako šířka pole. Formátovaná data v poli jsou zarovnaná doprava, pokud width jsou kladná a zarovnaná doleva, pokud width je záporná. Pokud je potřeba vyplnění, použijí se prázdné znaky. Je-li zadán width, je čárka vyžadována.

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á jména doleva v poli o 20 znacích a jejich hodiny doprava v poli o 5 znacích. 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á formatString komponenta je formátovací řetězec, který je vhodný pro typ formátovaného objektu. 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 formatString není zadaný, použije se specifikátor obecného formátu ("G") pro číselný typ, datum a čas nebo typ výčtu. Pokud je zadáno formatString, je nutné uvést dvojtečku.

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 článcích o rozhraní IFormattable a ICustomFormatter.

Typ nebo kategorie typu Podívejte se
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) Řetězce formátování výčtů
Číselné typy (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) 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

Únik složených závorek

Otevírací a uzavírací složené závorky jsou interpretovány jako začá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 escape 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 dvou pravých složených závorek (}}), aby se zobrazila jedna pravá složená závorka (}).

Escapované složené závorky s položkou formátu se parsují odlišně mezi .NET a .NET Framework.

.SÍŤ

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

  1. První dvě otevírací složené závorky ({{) jsou escapované a poskytují jednu otevírací 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 ukončení položky formátu.
  5. Poslední dvě zavírací závorky jsou uniknuté a vytvářejí jednu zavírací 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í, v jakém se vyskytují. Interpretace vnořených závorek není podporována.

Způsob interpretace složených závorek může vést k neočekávaným výsledkům. Představte si například položku formátu {{{0:D}}}, která má zobrazit otevírací složenou závorku, číselnou hodnotu ve formátu desetinného čísla a uzavírací složenou závorku. Položka formátu je však interpretována následujícím způsobem:

  1. První dvě otevírací složené závorky ({{) jsou escapované a poskytují jednu otevírací 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 desetinný, ale další dvě uniknuté 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 uniklých závorek a formátovacích položek, je formátovat závorky a položky samostatně. To znamená, že v první operaci formátu zobrazte literálovou levou složenou závorku. Při další operaci zobrazte výsledek formátované položky a při závěrečné operaci zobrazte doslovnou uzavírací 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 hodnota, která má být naformátována, null, vrátí se prázdný řetězec String.Empty.

  2. Pokud je k dispozici implementace ICustomFormatter, runtime volá její metodu Format. Modul runtime předá metodě hodnotu položky formátu formatString (nebo null, pokud není přítomna). 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ě je vrácen výsledek volání ICustomFormatter.Format.

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

  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í vytvářejí ekvivalentní 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($"{myNumber:C}");

// 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 ukazuje použití šířky 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é