Formatação compostaComposite Formatting

O recurso de formatação de composição do .NET utiliza uma lista de objetos e uma cadeia de caracteres de formato de composição como entrada.The .NET composite formatting feature takes a list of objects and a composite format string as input. Uma cadeia de formato de composição consiste em um texto fixo intercalado com espaços reservados indexados, chamados de itens de formato, que correspondem aos objetos na lista.A composite format string consists of fixed text intermixed with indexed placeholders, called format items, that correspond to the objects in the list. A operação de formatação produz uma cadeia de caracteres de resultado que consiste no texto fixo original intercalado com a representação de cadeia de caracteres dos objetos na lista.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.

Importante

Em vez de usar cadeias de caracteres de formato composto, você pode usar cadeias de caracteres interpoladas se o idioma e a versão de idioma que você está usando são compatíveis com elas.Instead of using composite format strings, you can use interpolated strings if the language and language version that you're using support them. Uma cadeia de caracteres interpolada é uma cadeia de caracteres que contém expressões interpoladas.An interpolated string is a string that contains interpolated expressions. Cada expressão interpolada é resolvida com o valor da expressão e incluída na cadeia de caracteres resultante quando a cadeia de caracteres é atribuída.Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. Para saber mais, confira Interpolação de cadeia de caracteres (Referência de C#) ou Cadeias de caracteres interpoladas (Referência do Visual Basic).For more information, see String interpolation (C# Reference) and Interpolated strings (Visual Basic Reference).

O recurso de formatação de composição tem suporte de métodos como:The composite formatting feature is supported by methods such as the following:

Cadeia de formato de composiçãoComposite Format String

Uma cadeia de formato de composição e uma lista de objetos são usadas como argumentos dos métodos que dão suporte ao recurso de formatação de composição.A composite format string and object list are used as arguments of methods that support the composite formatting feature. Uma cadeia de formato de composição consiste em zero ou mais sequências de texto fixo intercaladas com um ou mais itens de formato.A composite format string consists of zero or more runs of fixed text intermixed with one or more format items. O texto fixo é qualquer cadeia de caracteres que você escolher e cada item de formato corresponde a um objeto ou a uma estrutura demarcada na lista.The fixed text is any string that you choose, and each format item corresponds to an object or boxed structure in the list. O recurso de formatação de composição retorna uma nova cadeia de caracteres de resultado em que cada item de formato é substituído pela representação de cadeia de caracteres do objeto correspondente na lista.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.

Considere o fragmento de código Format a seguir.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)

O texto fixo é "Name = "e", hours = ".The fixed text is "Name = " and ", hours = ". Os itens de formato são "{0}", cujo índice é 0, que corresponde ao objeto name, e "{1:hh}", cujo índice é 1, que corresponde ao objeto 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.

Sintaxe do item de formatoFormat Item Syntax

Cada item de formato assume a forma a seguir e consiste nos seguintes componentes:Each format item takes the following form and consists of the following components:

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

As chaves correspondentes ("{" e "}") são necessárias.The matching braces ("{" and "}") are required.

Componente de índiceIndex Component

O componente obrigatório index, também chamado de especificador de parâmetro, é um número iniciado por 0 que identifica um item correspondente na lista de objetos.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. Ou seja, o item de formato cujo especificador de parâmetro é 0 formata o primeiro objeto na lista, o item de formato cujo especificador de parâmetro é 1 formata o segundo objeto na lista e assim por diante.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. O exemplo a seguir inclui quatro especificadores de parâmetros, numerados de zero a três, para representar números primos menores que dez: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ários itens de formato podem fazer referência ao mesmo elemento na lista de objetos ao especificar o mesmo especificador de parâmetro.Multiple format items can refer to the same element in the list of objects by specifying the same parameter specifier. Por exemplo, você pode formatar o mesmo valor numérico em formato hexadecimal, científico e numérico especificando uma cadeia de caracteres de formato composto como: "0x{0:X} {0:E} {0:N}", como mostrado no exemplo a seguir.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

Cada item de formato pode fazer referência a qualquer objeto na lista.Each format item can refer to any object in the list. Por exemplo, se houver três objetos, você poderá formatar o segundo, o primeiro e o terceiro objetos especificando uma cadeia de formato de composição como esta: "{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}". Um objeto que não é referenciado por um item de formato é ignorado.An object that is not referenced by a format item is ignored. Uma FormatException será lançada no tempo de execução se um especificador de parâmetro designar um item fora dos limites da lista de objetos.A FormatException is thrown at runtime if a parameter specifier designates an item outside the bounds of the list of objects.

Componente de alinhamentoAlignment Component

O componente opcional alignment é um inteiro com sinal que indica a largura preferencial do campo formatado.The optional alignment component is a signed integer indicating the preferred formatted field width. Se o valor de alignment for menor que o comprimento da cadeia de caracteres formatada, alignment será ignorado e o comprimento da cadeia de caracteres formatada será usado como a largura do campo.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. Os dados formatados no campo serão alinhados à direita se alignment for positivo e serão alinhados à esquerda se alignment for negativo.The formatted data in the field is right-aligned if alignment is positive and left-aligned if alignment is negative. Se for necessário preenchimento, espaços em branco serão usados.If padding is necessary, white space is used. A vírgula é necessária se alignment for especificado.The comma is required if alignment is specified.

O exemplo a seguir define duas matrizes, uma contendo os nomes dos funcionários e outra contendo as horas trabalhadas por eles em um período de duas semanas.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. A cadeia de caracteres de formato de composição alinha à esquerda os nomes em um campo de 20 caracteres e alinha à direita as horas em um campo de 5 caracteres.The composite format string left-aligns the names in a 20-character field, and right-aligns their hours in a 5-character field. Observe que a cadeia de caracteres de formato padrão "N1" também é usada para formatar horas com um dígito fracionário.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

Componente da cadeia de caracteres de formatoFormat String Component

O componente opcional formatString é uma cadeia de caracteres de formato que é apropriada para o tipo de objeto que está sendo formatado.The optional formatString component is a format string that is appropriate for the type of object being formatted. Especifique uma cadeia de caracteres de formato numérico padrão ou personalizado se o objeto correspondente é um valor numérico, uma cadeia de caracteres de formato de data e hora padrão ou personalizado, se o objeto é um objeto DateTime ou uma cadeia de caracteres de formato de enumeração se o objeto correspondente é um valor de enumeração.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. Se formatString não for especificado, o especificador de formato geral ("G") para um tipo numérico, de data e hora ou enumeração será usado.If formatString is not specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. Os dois-pontos são necessários quando formatString é especificado.The colon is required if formatString is specified.

A tabela a seguir lista tipos ou categorias de tipos na biblioteca de classes do .NET Framework que dão suporte a um conjunto predefinido de cadeias de caracteres de formato e fornece links para tópicos que relacionam as cadeias de caracteres de formato com suporte.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. Observe que a formatação de cadeias de caracteres é um mecanismo extensível que possibilita definir novas cadeias de caracteres de formato para todos os tipos existentes, bem como definir um conjunto de cadeias de caracteres de formato com suporte por um tipo definido por aplicativo.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. Para saber mais, veja os tópicos de interface IFormattable e ICustomFormatter.For more information, see the IFormattable and ICustomFormatter interface topics.

Tipo ou categoria de tipoType or type category ConsulteSee
Tipos de data e hora (DateTime, DateTimeOffset)Date and time types (DateTime, DateTimeOffset) Cadeias de caracteres de formato de data e hora padrãoStandard Date and Time Format Strings

Cadeias de caracteres de formato de data e hora personalizadoCustom Date and Time Format Strings
Tipos de enumeração (todos os tipos derivados de System.Enum)Enumeration types (all types derived from System.Enum) Cadeias de Caracteres de Formato de EnumeraçãoEnumeration Format Strings
Tipos numéricos (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64)Numeric types (BigInteger, Byte, Decimal, Double, Int16, Int32, Int64, SByte, Single, UInt16, UInt32, UInt64) Cadeias de Caracteres de Formato Numérico PadrãoStandard Numeric Format Strings

Cadeias de caracteres de formato numérico personalizadoCustom Numeric Format Strings
Guid Guid.ToString(String)
TimeSpan Cadeias de caracteres de formato TimeSpan padrãoStandard TimeSpan Format Strings

Cadeias de caracteres de formato TimeSpan personalizadoCustom TimeSpan Format Strings

Chaves de escapeEscaping Braces

As chaves de abertura e fechamento são interpretadas como o início e o fim de um item de formato.Opening and closing braces are interpreted as starting and ending a format item. Consequentemente, você deve usar uma sequência de escape para exibir uma chave de abertura ou fechamento literal.Consequently, you must use an escape sequence to display a literal opening brace or closing brace. Especifique duas chaves de abertura ("{{") no texto fixo para exibir uma chave de abertura ("{"), ou duas chaves de fechamento ("}}") para exibir uma chave de fechamento ("}").Specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), or two closing braces ("}}") to display one closing brace ("}"). As chaves em um item de formato são interpretadas sequencialmente na ordem em que são encontradas.Braces in a format item are interpreted sequentially in the order they are encountered. Não há suporte para interpretação de chaves aninhadas.Interpreting nested braces is not supported.

A forma como as chaves de escape são interpretadas pode levar a resultados inesperados.The way escaped braces are interpreted can lead to unexpected results. Por exemplo, considere o item de formato "{{{0:D}}}", que deve exibir uma chave de abertura, um valor numérico formatado como número decimal e uma chave de fechamento.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. No entanto, o item de formato na verdade é interpretado da seguinte forma:However, the format item is actually interpreted in the following manner:

  1. As duas primeiras chaves de abertura ("{{") são escapadas e produzem uma chave de abertura.The first two opening braces ("{{") are escaped and yield one opening brace.

  2. Os três caracteres seguintes ("{0:") são interpretados como o início de um item de formato.The next three characters ("{0:") are interpreted as the start of a format item.

  3. O caractere seguinte ("D") seria interpretado como o especificador de formato numérico Decimal padrão, mas as duas chaves de escape seguintes ("}} ") produzem uma única chave.The next character ("D") would be interpreted as the Decimal standard numeric format specifier, but the next two escaped braces ("}}") yield a single brace. Como a cadeia de caracteres resultante ("D}") não é um especificador de formato numérico padrão, ela é interpretada como uma cadeia de formato personalizado que visa exibir a cadeia de caracteres literal "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. A última chave ("}") é interpretada como o final do item de formato.The last brace ("}") is interpreted as the end of the format item.

  5. O resultado final que é exibido é a cadeia de caracteres literal, "{D}".The final result that is displayed is the literal string, "{D}". O valor numérico que deveria ser formatado não é exibido.The numeric value that was to be formatted is not displayed.

Uma maneira de escrever seu código para evitar a interpretação incorreta de chaves de escape e itens de formato é formatar as chaves e os itens de formato separadamente.One way to write your code to avoid misinterpreting escaped braces and format items is to format the braces and format item separately. Ou seja, na primeira operação de formato exibir uma chave de abertura literal, na operação seguinte exibir o resultado do item de formato e, na operação final, exibir uma chave de fechamento literal.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. O exemplo a seguir ilustra esta abordagem.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}

Ordem de processamentoProcessing Order

Se a chamada ao método de formatação composto inclui um argumento IFormatProvider cujo valor não é null, o tempo de execução chama seu método IFormatProvider.GetFormat para solicitar uma implementação de ICustomFormatter.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. Se o método conseguir retornar uma implementação de ICustomFormatter, ela será armazenada em cache durante a chamada do método de formatação composta.If the method is able to return an ICustomFormatter implementation, it's cached for the duration of the call of the composite formatting method.

Cada valor na lista de parâmetros que corresponde a um item de formato é convertido em uma cadeia de caracteres da seguinte maneira:Each value in the parameter list that corresponds to a format item is converted to a string as follows:

  1. Se o valor a ser formatado for null, uma cadeia de caracteres vazia String.Empty será retornada.If the value to be formatted is null, an empty string String.Empty is returned.

  2. Se uma implementação de ICustomFormatter estiver disponível, o tempo de execução chamará seu método Format.If an ICustomFormatter implementation is available, the runtime calls its Format method. Ele passará ao método o valor formatString do item de formato, se houver ou null se não houver, junto com a implementação de IFormatProvider.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. Se a chamada ao método ICustomFormatter.Format retorna null, a execução continua para a próxima etapa; caso contrário, o resultado da chamada ICustomFormatter.Format é retornado.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. Se o valor implementa a interface IFormattable, o método ToString(String, IFormatProvider) da interface é chamado.If the value implements the IFormattable interface, the interface's ToString(String, IFormatProvider) method is called. O método receberá o valor formatString se houver um no item de formato, ou null se não houver.The method is passed the formatString value, if one is present in the format item, or null if it's not. O argumento IFormatProvider é determinado da seguinte forma:The IFormatProvider argument is determined as follows:

  4. O método sem parâmetros ToString do tipo, o qual substitui Object.ToString() ou herda o comportamento da sua classe base, é chamado.The type's parameterless ToString method, which either overrides Object.ToString() or inherits the behavior of its base class, is called. Nesse caso, a cadeia de caracteres de formato especificada pelo componente formatString no item de formato, se houver, será ignorada.In this case, the format string specified by the formatString component in the format item, if it's present, is ignored.

O alinhamento é aplicado após as etapas anteriores terem sido executadas.Alignment is applied after the preceding steps have been performed.

Exemplos de códigoCode Examples

O exemplo a seguir mostra uma cadeia de caracteres criada usando formatação de composição e outra criada usando o método ToString de um objeto.The following example shows one string created using composite formatting and another created using an object's ToString method. Os dois tipos de formatação produzem resultados equivalentes.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") 

Supondo que o dia atual seja uma quinta-feira de maio, o valor de ambas as cadeias de caracteres no exemplo anterior será Thursday May na cultura do inglês nos EUA.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.WriteLine expõe a mesma funcionalidade que String.Format.Console.WriteLine exposes the same functionality as String.Format. A única diferença entre os dois métodos é que String.Format retorna o resultado como uma cadeia de caracteres, enquanto que Console.WriteLine grava o resultado no fluxo de saída associado ao objeto Console.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. O exemplo a seguir usa o método Console.WriteLine para formatar o valor de MyInt como um valor de moeda.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

O exemplo a seguir demonstra a formatação de vários objetos, incluindo a formatação de um objeto de duas maneiras diferentes.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                 

O exemplo a seguir demonstra o uso de alinhamento na formatação.The following example demonstrates the use of alignment in formatting. Os argumentos formatados são colocados entre caracteres de barra vertical (|) para realçar o alinhamento resultante.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   |

Consulte tambémSee also