Cadeias de caracteres de formato de data e hora padrão

Artigo
06/05/2023

Uma cadeia de caracteres de formato de data e hora padrão usa um só caractere como especificador de formato para definir a representação do texto de um valor de DateTime ou DateTimeOffset. Qualquer cadeia de caracteres de formato de data e hora que contenha mais de um caractere, incluindo espaço em branco, é interpretada como uma cadeia de caracteres de formato de data e hora personalizado. Uma cadeia de caracteres de formato padrão ou personalizado pode ser usada de duas maneiras:

Para definir a cadeia de caracteres que resulta de uma operação de formatação.
Para definir a representação de texto de um valor de data e hora que possa ser convertido em valor de DateTime ou DateTimeOffset por uma operação de análise.

Dica

Baixe o Utilitário de Formatação, um aplicativo do Windows Forms do .NET que permite aplicar cadeias de caracteres de formato a valores numéricos ou de data e hora e exibir a cadeia de caracteres de resultado. O código-fonte está disponível para o C# e o Visual Basic.

Observação

Alguns dos exemplos de C# neste artigo são executados no executador de código embutido Try.NET e no playground. Clique no botão Executar para executar um exemplo em uma janela interativa. Ao executar o código, é possível modificá-lo e executar o código modificado clicando em Executar novamente. O código modificado será executado na janela interativa ou, se a compilação falhar, a janela interativa exibirá todos as mensagens de erro do compilador C#.

O fuso horário local do executador de código embutido Try.NET e do playground é o Tempo Universal Coordenado ou UTC. Isso pode afetar o comportamento e a saída dos exemplos que ilustram os tipos DateTime, DateTimeOffset e TimeZoneInfo e seus membros.

Tabela de especificadores de formato

A tabela a seguir descreve os especificadores de formato de data e hora padrão. Salvo indicação em contrário, um determinado especificador de formato de data e hora padrão produz uma representação de cadeia de caracteres idêntica independente de ela ser usada com um valor DateTime ou DateTimeOffset. Confira Configurações do Painel de Controle e Propriedades DateTimeFormatInfo para informações adicionais sobre como usar cadeias de caracteres de formato de data e hora padrão.

Especificador de formato	Descrição	Exemplos
"d"	Padrão de data abreviada. Mais informações:especificador de formato de data abreviado ("d").	2009-06-15T13:45:30 -> 6/15/2009 (en-US) 2009-06-15T13:45:30 -> 15/06/2009 (fr-FR) 2009-06-15T13:45:30 -> 2009/06/15 (ja-JP)
"D"	Padrão de data completa. Para saber mais:especificador de formato de data completa ("D").	2009-06-15T13:45:30 -> Monday, June 15, 2009 (en-US) 2009-06-15T13:45:30 -> понедельник, 15 июня 2009 г. (ru-RU) 2009-06-15T13:45:30 -> Montag, 15. Juni 2009 (de-DE)
"f"	Padrão de data/hora completa (hora abreviada). Para saber mais: especificador de formato de data completa e hora abreviada ("f").	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45 μμ (el-GR)
"F"	Padrão de data/hora completa (hora completa). Para saber mais: especificador de formato de data completa e hora completa ("F").	2009-06-15T13:45:30 -> Monday, June 15, 2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 13:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 1:45:30 μμ (el-GR)
"g"	Padrão geral de data/hora (hora abreviada). Para saber mais: especificador de formato geral de data e hora abreviada ("g").	2009-06-15T13:45:30 -> 6/15/2009 1:45 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45 (zh-CN)
"G"	Padrão geral de data/hora (hora completa). Para saber mais: especificador de formato geral de data e hora completa ("G").	2009-06-15T13:45:30 -> 6/15/2009 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 15/06/2009 13:45:30 (es-ES) 2009-06-15T13:45:30 -> 2009/6/15 13:45:30 (zh-CN)
"M", "m"	Padrão de mês/dia. Para saber mais: especificador de formato de mês ("M", "m").	2009-06-15T13:45:30 -> June 15 (en-US) 2009-06-15T13:45:30 -> 15. juni (da-DK) 2009-06-15T13:45:30 -> 15 Juni (id-ID)
"O", "o"	padrão de data/hora de ida e volta. Para saber mais: especificador de formato de viagem de ida e volta ("O", "o").	Valores DateTime: 2009-06-15T13:45:30 (DateTimeKind.Local) --> 2009-06-15T13:45:30.0000000-07:00 2009-06-15T13:45:30 (DateTimeKind.Utc) --> 2009-06-15T13:45:30.0000000Z 2009-06-15T13:45:30 (DateTimeKind.Unspecified) --> 2009-06-15T13:45:30.0000000 Valores DateTimeOffset: 2009-06-15T13:45:30-07:00 --> 2009-06-15T13:45:30.0000000-07:00
"R", "r"	Padrão RFC1123. Para saber mais: especificador de formato RFC1123 ("R", "r").	DateTimeOffset input: 2009-06-15T13:45:30 -> segunda-feira, 15 de junho de 2009 20:45:30 GMT DateTime input: 2009-06-15T13:45:30 -> segunda-feira, 15 de junho de 2009 13:45:30 GMT
"s"	Padrão de data/hora classificável. Para saber mais: especificador de formato classificável ("s").	2009-06-15T13:45:30 (DateTimeKind.Local) -> 2009-06-15T13:45:30 2009-06-15T13:45:30 (DateTimeKind.Utc) -> 2009-06-15T13:45:30
"t"	Padrão de hora abreviada. Para saber mais: especificador de formato de hora abreviada ("t").	2009-06-15T13:45:30 -> 1:45 PM (en-US) 2009-06-15T13:45:30 -> 13:45 (hr-HR) 2009-06-15T13:45:30 -> 01:45 م (ar-EG)
"T"	Padrão de hora completa. Para saber mais: especificador de formato de hora completa ("T").	2009-06-15T13:45:30 -> 1:45:30 PM (en-US) 2009-06-15T13:45:30 -> 13:45:30 (hr-HR) 2009-06-15T13:45:30 -> 01:45:30 م (ar-EG)
"u"	Padrão classificável universal de data/hora. Para saber mais: especificador de formato de padrão classificável universal ("u").	Com um valor DateTime: 2009-06-15T13:45:30 -> 2009-06-15 13:45:30Z Com um valor DateTimeOffset: 2009-06-15T13:45:30 -> 2009-06-15 20:45:30Z
"U"	Padrão universal de data/hora completa. Para saber mais: especificador de formato de padrão universal completo ("U").	2009-06-15T13:45:30 -> Monday, June 15, 2009 8:45:30 PM (en-US) 2009-06-15T13:45:30 -> den 15 juni 2009 20:45:30 (sv-SE) 2009-06-15T13:45:30 -> Δευτέρα, 15 Ιουνίου 2009 8:45:30 μμ (el-GR)
"Y", "y"	Padrão ano mês. Para saber mais: especificador de formato de ano mês ("Y").	2009-06-15T13:45:30 -> June 2009 (en-US) 2009-06-15T13:45:30 -> juni 2009 (da-DK) 2009-06-15T13:45:30 -> Juni 2009 (id-ID)
Qualquer outro caractere único	Especificador desconhecido.	Gera uma FormatException de tempo de execução.

Como funcionam as cadeias de caracteres de formato padrão

Em uma operação de formatação, uma cadeia de formato padrão é simplesmente um alias para uma cadeia de caracteres de formato personalizado. A vantagem de usar um alias para se referir a uma cadeia de caracteres de formato personalizado é que, embora o alias permaneça invariável, a cadeia de caracteres de formato personalizado em si pode variar. Isso é importante porque as representações de cadeia de caracteres de valores de data e hora normalmente variam de acordo com a cultura. Por exemplo, a cadeia de caracteres de formato padrão "d" indica que um valor de data e hora deve ser exibido usando um formato de data abreviada. Para a cultura invariável, esse padrão é "MM/dd/aaaa". Para a cultura fr-FR, ele é " dd/MM/aaaa ". Para a cultura ja-JP, ele é " aaaa/MM/dd ".

Se uma cadeia de caracteres de formato padrão em uma operação de formatação aponta para uma cadeia de caracteres de formato personalizado de uma cultura, seu aplicativo pode definir a cultura específica cujas cadeias de caracteres de formato personalizado são usadas de uma dessas maneiras:

Você pode usar a cultura padrão (ou atual). O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura atual. Nesse caso, a cultura atual é en-US.

// Display using current (en-us) culture's short date format
DateTime thisDate = new DateTime(2008, 3, 15);
Console.WriteLine(thisDate.ToString("d"));           // Displays 3/15/2008

' Display using current (en-us) culture's short date format
Dim thisDate As Date = #03/15/2008#
Console.WriteLine(thisDate.ToString("d"))     ' Displays 3/15/2008

Você pode passar um objeto CultureInfo que representa a cultura cuja formatação deve ser usada para um método que possua um parâmetro IFormatProvider. O exemplo a seguir exibe uma data usando o formato de data abreviada da cultura pt-BR.

// Display using pt-BR culture's short date format
DateTime thisDate = new DateTime(2008, 3, 15);
CultureInfo culture = new CultureInfo("pt-BR");
Console.WriteLine(thisDate.ToString("d", culture));  // Displays 15/3/2008

' Display using pt-BR culture's short date format
Dim thisDate As Date = #03/15/2008#
Dim culture As New CultureInfo("pt-BR")
Console.WriteLine(thisDate.ToString("d", culture))   ' Displays 15/3/2008

Você pode passar um objeto DateTimeFormatInfo que fornece informações de formatação para um método que possua um parâmetro IFormatProvider. O exemplo a seguir exibe uma data usando o formato de data abreviada de um objeto DateTimeFormatInfo para a cultura hr-HR.

// Display using date format information from hr-HR culture
DateTime thisDate = new DateTime(2008, 3, 15);
DateTimeFormatInfo fmt = (new CultureInfo("hr-HR")).DateTimeFormat;
Console.WriteLine(thisDate.ToString("d", fmt));      // Displays 15.3.2008

' Display using date format information from hr-HR culture
Dim thisDate As Date = #03/15/2008#
Dim fmt As DateTimeFormatInfo = (New CultureInfo("hr-HR")).DateTimeFormat
Console.WriteLine(thisDate.ToString("d", fmt))   ' Displays 15.3.2008

Observação

Para obter informações sobre como personalizar os padrões ou as cadeias de caracteres usados na formatação de valores de data e hora, consulte o tópico da classe NumberFormatInfo.

Em alguns casos, a cadeia de caracteres de formato padrão funciona como uma abreviação conveniente de uma cadeia de caracteres de formato personalizado maior que é invariável. Quatro cadeias de caracteres de formato padrão se enquadram nesta categoria: "O" (ou "o"), "R" (ou "r"), "s" e "u". Estas cadeias de caracteres correspondem às cadeias de caracteres de formato personalizado definidas pela cultura invariável. Elas produzem representações de cadeias de caracteres de valores de data e hora que são feitos para ser idênticos entre culturas. A tabela a seguir fornece informações sobre essas quatro cadeias de caracteres de formato de data e hora padrão.

Cadeias de caracteres de formato padrão	Definidas pela propriedade DateTimeFormatInfo.InvariantInfo	Cadeia de caracteres de formato personalizado
"O" ou "o"	Nenhum	yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK
"R" ou "r"	RFC1123Pattern	ddd, dd MMM yyyy HH':'mm':'ss 'GMT'
"s"	SortableDateTimePattern	yyyy'-'MM'-'dd'T'HH':'mm':'ss
"u"	UniversalSortableDateTimePattern	yyyy'-'MM'-'dd HH':'mm':'ss'Z'

As cadeias de caracteres de formato padrão também podem ser usadas em operações de análise com os métodos DateTime.ParseExact ou DateTimeOffset.ParseExact, o que exige que uma cadeia de caracteres de entrada atenda com exatidão a um padrão específico para que a operação de análise seja bem-sucedida. Muitas cadeias de caracteres de formato padrão são mapeadas em muitas cadeias de caracteres de formato personalizado. Assim, um valor de data e hora poderá ser representado em vários formatos e a operação de análise ainda terá êxito. Você pode determinar a cadeia ou as cadeias de caracteres de formato que correspondem a uma cadeia de formato padrão ao chamar o método DateTimeFormatInfo.GetAllDateTimePatterns(Char). O exemplo a seguir exibe as cadeias de caracteres de formato personalizado que são mapeados para a cadeia de caracteres de formato padrão “d” (padrão de data abreviada).

using System;
using System.Globalization;

public class Example
{
   public static void Main()
   {
      Console.WriteLine("'d' standard format string:");
      foreach (var customString in DateTimeFormatInfo.CurrentInfo.GetAllDateTimePatterns('d'))
          Console.WriteLine("   {0}", customString);
   }
}
// The example displays the following output:
//       'd' standard format string:
//          M/d/yyyy
//          M/d/yy
//          MM/dd/yy
//          MM/dd/yyyy
//          yy/MM/dd
//          yyyy-MM-dd
//          dd-MMM-yy

Imports System.Globalization

Module Example
    Public Sub Main()
        Console.WriteLine("'d' standard format string:")
        For Each customString In DateTimeFormatInfo.CurrentInfo.GetAllDateTimePatterns("d"c)
            Console.WriteLine("   {0}", customString)
        Next
    End Sub
End Module
' The example displays the following output:
'    'd' standard format string:
'       M/d/yyyy
'       M/d/yy
'       MM/dd/yy
'       MM/dd/yyyy
'       yy/MM/dd
'       yyyy-MM-dd
'       dd-MMM-yy

As seções a seguir descrevem os especificadores de formato padrão para valores DateTime e DateTimeOffset.

Formatos de data

Esse grupo inclui os seguintes formatos:

Especificador de formato de data abreviada ("d")
Especificador de formato de data completa ("D")

Especificador de formato de data abreviada ("d")

O especificador de formato padrão “d” representa uma cadeia de caracteres de formato de data e hora personalizado que é definida pela propriedade DateTimeFormatInfo.ShortDatePattern de uma cultura específica. Por exemplo, a cadeia de caracteres de formato personalizado retornada pela propriedade ShortDatePattern da cultura invariável é " MM/dd/aaaa ".

A tabela a seguir lista as propriedades do objeto DateTimeFormatInfo que controlam a formatação da cadeia de caracteres retornada.

Propriedade	Descrição
ShortDatePattern	Define o formato geral da cadeia de caracteres de resultado.
DateSeparator	Define a cadeia de caracteres que separa o ano, o mês e os componentes de dia de uma data.

O exemplo a seguir utiliza o especificador de formato "d" para exibir um valor de data e hora.

DateTime date1 = new DateTime(2008,4, 10);
Console.WriteLine(date1.ToString("d", DateTimeFormatInfo.InvariantInfo));
// Displays 04/10/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("en-US")));
// Displays 4/10/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("en-NZ")));
// Displays 10/04/2008
Console.WriteLine(date1.ToString("d",
                  CultureInfo.CreateSpecificCulture("de-DE")));
// Displays 10.04.2008

Dim date1 As Date = #4/10/2008#
Console.WriteLine(date1.ToString("d", DateTimeFormatInfo.InvariantInfo))
' Displays 04/10/2008
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("en-US")))
' Displays 4/10/2008                       
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("en-NZ")))
' Displays 10/04/2008                       
Console.WriteLine(date1.ToString("d", _
                  CultureInfo.CreateSpecificCulture("de-DE")))
' Displays 10.04.2008

Propriedade	Descrição
LongDatePattern	Define o formato geral da cadeia de caracteres de resultado.
DayNames	Define os nomes de dias localizados que podem aparecer na cadeia de caracteres de resultado.
MonthNames	Define os nomes dos meses localizados que podem aparecer na cadeia de caracteres de resultado.

Propriedade	Descrição
LongDatePattern	Define o formato do componente de data da cadeia de caracteres de resultado.
ShortTimePattern	Define o formato do componente de hora da cadeia de caracteres de resultado.
DayNames	Define os nomes de dias localizados que podem aparecer na cadeia de caracteres de resultado.
MonthNames	Define os nomes dos meses localizados que podem aparecer na cadeia de caracteres de resultado.
TimeSeparator	Define a cadeia de caracteres que separa os componentes de hora, minuto e segundo de uma hora.
AMDesignator	Define a cadeia de caracteres que indica as horas da meia-noite até antes do meio-dia em um relógio de 12 horas.
PMDesignator	Define a cadeia de caracteres que indica as horas do meio-dia até antes da meia-noite em um relógio de 12 horas.

Propriedade	Descrição
FullDateTimePattern	Define o formato geral da cadeia de caracteres de resultado.
DayNames	Define os nomes de dias localizados que podem aparecer na cadeia de caracteres de resultado.
MonthNames	Define os nomes dos meses localizados que podem aparecer na cadeia de caracteres de resultado.
TimeSeparator	Define a cadeia de caracteres que separa os componentes de hora, minuto e segundo de uma hora.
AMDesignator	Define a cadeia de caracteres que indica as horas da meia-noite até antes do meio-dia em um relógio de 12 horas.
PMDesignator	Define a cadeia de caracteres que indica as horas do meio-dia até antes da meia-noite em um relógio de 12 horas.

Propriedade	Descrição
ShortDatePattern	Define o formato do componente de data da cadeia de caracteres de resultado.
LongTimePattern	Define o formato do componente de hora da cadeia de caracteres de resultado.
DateSeparator	Define a cadeia de caracteres que separa o ano, o mês e os componentes de dia de uma data.
TimeSeparator	Define a cadeia de caracteres que separa os componentes de hora, minuto e segundo de uma hora.
AMDesignator	Define a cadeia de caracteres que indica as horas da meia-noite até antes do meio-dia em um relógio de 12 horas.
PMDesignator	Define a cadeia de caracteres que indica as horas do meio-dia até antes da meia-noite em um relógio de 12 horas.

Propriedade	Descrição
RFC1123Pattern	Define o formato da cadeia de caracteres de resultado.
AbbreviatedDayNames	Define os nomes de dias abreviados que podem aparecer na cadeia de caracteres de resultado.
AbbreviatedMonthNames	Define os nomes dos meses abreviados que podem aparecer na cadeia de caracteres de resultado.

Propriedade	Descrição
MonthDayPattern	Define o formato geral da cadeia de caracteres de resultado.
MonthNames	Define os nomes dos meses localizados que podem aparecer na cadeia de caracteres de resultado.

Propriedade	Descrição
YearMonthPattern	Define o formato geral da cadeia de caracteres de resultado.
MonthNames	Define os nomes dos meses localizados que podem aparecer na cadeia de caracteres de resultado.

Cadeias de caracteres de formato de data e hora padrão

Tabela de especificadores de formato

Como funcionam as cadeias de caracteres de formato padrão

Formatos de data

Especificador de formato de data abreviada ("d")

Especificador de formato de data completa ("D")

Formatos de data e hora

Especificador de formato de data completa e hora abreviada ("f")

Especificador de formato de data completa e hora completa (“F”)

Especificador de formato de data geral e hora abreviada (“g”)

Especificador de formato de data geral e hora completa (“G”)

Especificador de formato de ida e volta ("O", "o")

Especificador de formato RFC1123 ("R", "r")

Especificador de formato classificável ("s")

Especificador de formato classificável universal ("u")

Especificador de formato completo universal ("U")

Formatos de hora

Especificador de formato de hora abreviada ("t")

Especificador de formato de hora completa ("T")

Formatos de data parcial

Especificador de formato de mês ("M", "m")

Especificador de formato de ano mês ("Y", "y")

Configurações do Painel de Controle

Propriedades DateTimeFormatInfo

Confira também

Comentários

Recursos adicionais