DateTimeFormatter Classe

Definição

Namespace:

Windows.Globalization.DateTimeFormatting

Formata datas e horas.

public ref class DateTimeFormatter sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class DateTimeFormatter final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class DateTimeFormatter

function DateTimeFormatter(yearFormat, monthFormat, dayFormat, dayOfWeekFormat, hourFormat, minuteFormat, secondFormat, languages, geographicRegion, calendar, clock)

Public NotInheritable Class DateTimeFormatter

Herança

Object Platform::Object IInspectable DateTimeFormatter

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Exemplos

Use a classe DateTimeFormatter para formatar uma data.

// Format a date via a string template. Note that the order specifed in the string pattern does
// not determine the order of the parts of the formatted string. The user's language and region
// preferences will determine the pattern of the date returned based on the specified parts.

var formatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day dayofweek year");
DateTime dateToFormat = DateTime.Now;
var mydate = formatter.Format(dateToFormat);

Gramática padrãoA gramática a seguir define o que é aceito para um padrão:

<pattern> ::= [<literal-text>] <datetime-pattern> [<literal-text>] |
              [<literal-text>] <datetime-pattern> <pattern>

<literal-text> ::= <literal-character>+

<literal-character> ::= [^{}] | "{openbrace}" | "{closebrace}"

<datetime-pattern> ::= <date-pattern> | <time-pattern>

<date-pattern> ::= <era> | <year> | <month> | <day> | <dayofweek>

<time-pattern> ::= <period> | <hour> | <minute> | <second> | <timezone>

<era> ::= "{era.abbreviated" [<ideal-length>] "}"

<year> ::= "{year.full" [<ideal-length>] "}" |
           "{year.abbreviated" [<ideal-length>] "}"

<month> ::= "{month.full}" |
            "{month.solo.full}" |
            "{month.abbreviated" [<ideal-length>] "}"
            "{month.solo.abbreviated" [<ideal-length>] "}"
            "{month.integer" [<ideal-length>] "}"

<dayofweek> ::= "{dayofweek.full}" |
                "{dayofweek.solo.full}" |
                "{dayofweek.abbreviated" [<ideal-length>] "}"
                "{dayofweek.solo.abbreviated" [<ideal-length>] "}"

<day> ::= "{day.integer" [<ideal-length>] "}"

<period> ::= "{period.abbreviated" [<ideal-length>] "}"

<hour> ::= "{hour.integer" [<ideal-length>] "}"

<minute> ::= "{minute.integer" [<ideal-length>] "}"

<second> ::= "{second.integer" [<ideal-length>] "}"

<timezone> ::= "{timezone.full}" |
                "{timezone.abbreviated" [<ideal-length>] "}"

<ideal-length> ::= "(" <non-zero-digit> ")"

<non-zero-digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

Gramática de modeloA gramática a seguir define o que é aceito para um modelo:

<template> ::= <opt-whitespace> <date> <opt-whitespace> |
               <opt-whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <specific-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <specific-date> <opt-whitespace> |
               <opt-whitespace> <relative-date> <whitespace> <time> <opt-whitespace> |
               <opt-whitespace> <time> <whitespace> <relative-date> <opt-whitespace>

<opt-whitespace> ::= [<whitespace>] 

<whitespace> ::= " "+ 

<date> ::= <year> | <month> | <day> | <month-year> | <relative-date> | <specific-date>

<relativedate> ::= <dayofweek> | <month-day> | <relative-longdate>

<specificdate> ::= <shortdate> | <longdate>

<month-day> ::= <month> <whitespace> <day> |
                <day> <whitespace> <month>

<relative-longdate> ::= <month> <whitespace> <day> <whitespace> <dayofweek> |
                        <month> <whitespace> <dayofweek> <whitespace> <day> |
                        <day> <whitespace> <month> <whitespace> <dayofweek> |
                        <day> <whitespace> <dayofweek> <whitespace> <month> |
                        <dayofweek> <whitespace> <day> <whitespace> <month> |
                        <dayofweek> <whitespace> <month> <whitespace> <day>

<month-year> ::= <month> <whitespace> <year> |
                 <year> <whitespace> <month>


<shortdate> ::= "shortdate" |
                <month> <whitespace> <day> <whitespace> <year> |
                <month> <whitespace> <year> <whitespace> <day> |
                <day> <whitespace> <month> <whitespace> <year> |
                <day> <whitespace> <year> <whitespace> <month> |
                <year> <whitespace> <day> <whitespace> <month> |
                <year> <whitespace> <month> <whitespace> <day>


<longdate> ::= "longdate" |
               <year> <whitespace> <month> <whitespace> <day> <whitespace> <dayofweek> |
               <year> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <day> |
               <year> <whitespace> <day> <whitespace> <month> <whitespace> <dayofweek> |
               <year> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <month> |
               <year> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <year> <whitespace> <day> <whitespace> <dayofweek> |
               <month> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <day> |
               <day> <whitespace> <year> <whitespace> <month> <whitespace> <dayofweek> |
               <day> <whitespace> <year> <whitespace> <dayofweek> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <day> <whitespace> <month> |
               <dayofweek> <whitespace> <year> <whitespace> <month> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <year> <whitespace> <dayofweek> |
               <month> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <day> |
               <day> <whitespace> <month> <whitespace> <year> <whitespace> <dayofweek> |
               <day> <whitespace> <dayofweek> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <day> <whitespace> <year> <whitespace> <month> |
               <dayofweek> <whitespace> <month> <whitespace> <year> <whitespace> <day> |
               <month> <whitespace> <day> <whitespace> <dayofweek> <whitespace> <year> |
               <month> <whitespace> <dayofweek> <whitespace> <day> <whitespace> <year> |
               <day> <whitespace> <month> <whitespace> <dayofweek> <whitespace> <year> |
               <day> <whitespace> <dayofweek> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <day> <whitespace> <month> <whitespace> <year> |
               <dayofweek> <whitespace> <month> <whitespace> <day> <whitespace> <year>

<time> ::= <hour> | 
           <hour> <whitespace> <timezone> |
           <timezone> <whitespace> <hour> |
           <shorttime> |
           <longtime>

<shorttime> ::= "shorttime" |
                <hour> <whitespace> <minute> |
                <minute> <whitespace> <hour> |
                <timezone> <whitespace> <hour> <whitespace> <minute> |
                <timezone> <whitespace> <minute> <whitespace> <hour> |
                <hour> <whitespace> <timezone> <whitespace> <minute> |
                <minute> <whitespace> <timezone> <whitespace> <hour> |
                <hour> <whitespace> <minute> <whitespace> <timezone> |
                <minute> <whitespace> <hour> <whitespace> <timezone>

<longtime> ::= "longtime" |
               <hour> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <minute> |
               <timezone> <whitespace> <hour> <whitespace> <minute> <whitespace> <second> |
               <timezone> <whitespace> <hour> <whitespace> <second> <whitespace> <minute> |
               <timezone> <whitespace> <minute> <whitespace> <hour> <whitespace> <second> |
               <timezone> <whitespace> <minute> <whitespace> <second> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <minute> <whitespace> <hour> |
               <timezone> <whitespace> <second> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <timezone> <whitespace> <minute> <whitespace> <second> |
               <hour> <whitespace> <timezone> <whitespace> <second> <whitespace> <minute> |
               <minute> <whitespace> <timezone> <whitespace> <hour> <whitespace> <second> |
               <minute> <whitespace> <timezone> <whitespace> <second> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <minute> <whitespace> <hour> |
               <second> <whitespace> <timezone> <whitespace> <hour> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <timezone> <whitespace> <second> |
               <hour> <whitespace> <second> <whitespace> <timezone> <whitespace> <minute> |
               <minute> <whitespace> <hour> <whitespace> <timezone> <whitespace> <second> |
               <minute> <whitespace> <second> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <minute> <whitespace> <timezone> <whitespace> <hour> |
               <second> <whitespace> <hour> <whitespace> <timezone> <whitespace> <minute> |
               <hour> <whitespace> <minute> <whitespace> <second> <whitespace> <timezone> |
               <hour> <whitespace> <second> <whitespace> <minute> <whitespace> <timezone> |
               <minute> <whitespace> <hour> <whitespace> <second> <whitespace> <timezone> |
               <minute> <whitespace> <second> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <minute> <whitespace> <hour> <whitespace> <timezone> |
               <second> <whitespace> <hour> <whitespace> <minute> <whitespace> <timezone>

<year> ::= "year" | "year.full" | "year.abbreviated"

<month> ::= "month" | "month.full" | "month.abbreviated" | "month.numeric"

<day> ::= "day"

<dayofweek> ::= "dayofweek" | "dayofweek.full" | "dayofweek.abbreviated"

<hour> ::= "hour"

<minute> ::= "minute"

<second> ::= "second"

<timezone> ::= "timezone" | "timezone.full" | "timezone.abbreviated"

Comentários

Observação

Essa API está sendo atualizada para dar suporte à alteração da era japonesa de maio de 2019. Se o aplicativo der suporte ao calendário japonês, você deverá validar se ele lida corretamente com a nova era. Confira Preparar seu aplicativo para a alteração da era japonesa para obter mais informações.

Observação

Se seu aplicativo passar marcas de idioma usadas nessa classe para qualquer função de Suporte à Linguagem Nacional , ele deverá primeiro converter as marcas chamando ResolveLocaleName.

Alguns dos construtores para DateTimeFormatter tomam um parâmetro de cadeia de caracteres formatTemplate que especifica os componentes solicitados a serem formatados. Esse parâmetro pode ser um modelo de formato ou um padrão de formato. Modelos de formato são convenientes de usar e fornecer formatação que é típica para o idioma, relógio e calendário que você especificar. Os padrões de formato fornecem maior controle de saída do que modelos de formato. Se você precisar de formatação que não seja padrão, use padrões de formato em vez de modelos.

Em um modelo de formato, você especifica os componentes (hora, data, dia da semana etc.) que deseja incluir na saída formatada. O formatador formata os componentes conforme apropriado para o idioma, relógio e calendário especificados. A ordem dos componentes em seu modelo não importa; o formatador ordena os componentes de acordo com a ordem mostrada na linguagem de modelo de formato abaixo.

Alguns modelos comumente usados são listados na tabela a seguir. Em modelos com mais de um componente, o componente pode ser qualquer uma das variações de componente com suporte e os componentes podem estar em qualquer ordem. Por exemplo, há suporte para "dayofweek.full year month.numeric day". (Veja abaixo, após os Exemplos, para a gramática que define modelos válidos.)

Importante

Você não pode combinar componentes arbitrariamente e necessariamente obter um modelo válido. Os únicos modelos válidos são aqueles definidos pela gramática fornecida.

Modelo
longdate
shortdate
Longa data
shorttime
dayofweek
dayofweek.full
dayofweek.abbreviated
dia
mês
month.full
month.abreviado
month.numeric
year
year.full
year.abreviado
dayofweek day month year
mês do dia dayofweek
ano do mês do dia
mês do dia
mês, ano
hour
minute
second
minuto de hora segundo
minuto de hora
timezone
timezone.full
timezone.abreviado
hora do dia do mês do ano

A tabela a seguir mostra a saída de exemplo de formatadores criados com vários valores de modelo, idioma e relógio. A coluna "Padrão equivalente" fornece um padrão que produz a mesma saída que o modelo.

Modelo	Language	Relógio	Saída	Padrão equivalente
longdate	pt-BR	<não especificado>	Segunda-feira, 2 de setembro de 2013	{dayofweek.full}, {month.full} {day.integer}, {year.full}
longdate	fr-FR	<não especificado>	lundi 2 septembre 2013	{dayofweek.full} {day.integer} {month.full} {year.full}
shortdate	pt-BR	<não especificado>	9‎/‎2‎/‎2013	{month.integer}/{day.integer}/{year.full}
shortdate	fr-FR	<não especificado>	02‎/‎09‎/‎2013	{day.integer(2)}/{month.integer(2)}/{year.full}
dia do mês dayofweek	pt-BR	<não especificado>	Segunda-feira, 2 de setembro	{dayofweek.full}, {month.full} {day.integer}
dayofweek do dia do mês	pt-BR	<não especificado>	Segunda-feira, 2 de setembro	{dayofweek.full}, {month.full} {day.integer}
Longa data	pt-BR	<não especificado>	6:01:24 AM	{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}
Longa data	pt-BR	24HourClock	‎17‎:‎32‎:‎45	{hour.integer}:{minute.integer(2)}:{second.integer(2)}
Longa data	fr-FR	<não especificado>	17‎:‎32‎:‎45	{hour.integer(2)}:{minute.integer(2)}:{second.integer(2)}
shorttime	pt-BR	<não especificado>	6h01	{hour.integer}:{minute.integer(2)} {period.abbreviated}
shorttime	pt-BR	24HourClock	17‎:‎32	{hour.integer}:{minute.integer(2)}
shorttime	fr-FR	<não especificado>	17‎:‎32	{hour.integer(2)}:{minute.integer(2)}

Os padrões de formato são compostos por uma cadeia de caracteres literal com campos delimitados por chaves, como "{day.numeric}/{month.numeric}/{year.full}". Alguns campos comumente usados são listados na tabela a seguir. (Veja abaixo, após os Exemplos, para a gramática que define padrões válidos.)

Importante

Você não pode combinar campos arbitrariamente e necessariamente obter um padrão válido. Os únicos padrões válidos são aqueles definidos pela gramática fornecida.

Campo Padrão de formato
{openbrace}
{closebrace}
{dayofweek.solo.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{dayofweek.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{dia.<type>} em que <o tipo> é inteiro/inteiro(n)
{mês.<type>} em que <o tipo> é completo/abreviado/abreviado(n) /integer/integer(n)
{month.solo.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{ano.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{era.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{hora.<type>} em que <o tipo> é inteiro/inteiro(n)
{ponto final.<type>} em que <o tipo> é completo/abreviado/abreviado(n)
{minute.<type>} em que <o tipo> é inteiro/inteiro(n)
{segundo.<type>} em que <o tipo> é inteiro/inteiro(n)
{fuso horário.<type>} em que <o tipo> é completo/abreviado/abreviado(n)

Observação

• Use {openbrace} ou {closebrace} para especificar que "{" ou "}" aparece como parte da cadeia de caracteres literal.

• solo especifica o formulário autônomo. Para idiomas com distinções de maiúsculas e minúsculas, o caso genitivo é o caso não marcado. Para obter o caso nominativo, use solo.
• integer(2) para o quinto dia do mês (por exemplo) é "05", enquanto integer(1) produz "5". inteiro produz o melhor n para uma determinada combinação de idioma/calendário.
• Durante anos, o total produz todos os dígitos ("2013"). abreviado é sinônimo de abreviado(2), que é o ano de 2 dígitos para o calendário gregoriano ("13"). (Outros calendários podem eventualmente usar outra coisa como padrão; mantivemos abreviado para ter a semântica do melhor para uma determinada combinação de idioma/calendário.) abreviado(n) é truncado para os n dígitos menos significativos (por exemplo, 2013 com n =1 é "3").

A tabela a seguir mostra a saída de exemplo de formatadores criados com vários valores de padrão, linguagem e relógio.

Padrão	Idioma	Relógio	Saída
{dayofweek.full}, {month.full} {day.integer}, {year.full}	pt-BR	<não especificado>	Segunda-feira, 2 de setembro de 2013
{dayofweek.full}, {day.integer(2)} {month.full}, {year.full}	fr-FR	<não especificado>	lundi, 02 septembre, 2013
{month.integer}/{day.integer}/{year.full}	en-US	<não especificado>	9/‎2/2013
{month.integer}/{day.integer}/{year.abbreviated}	en-US	<não especificado>	9/‎2/13
{month.integer(2)}/{day.integer(2)}/{year.abbreviated}	en-US	<não especificado>	09/‎02/13
{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}	en-US	<não especificado>	6:01:24 AM
{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}	en-US	24HourClock	17:32:45

Construtores

DateTimeFormatter(HourFormat, MinuteFormat, SecondFormat)	Cria um objeto DateTimeFormatter inicializado com formatos de hora, minuto e segundo.
DateTimeFormatter(String)	Cria um objeto DateTimeFormatter inicializado por uma cadeia de caracteres de modelo de formato.
DateTimeFormatter(String, IIterable<String>)	Cria um objeto DateTimeFormatter inicializado por uma cadeia de caracteres de modelo de formato e uma lista de idiomas.
DateTimeFormatter(String, IIterable<String>, String, String, String)	Cria um objeto DateTimeFormatter inicializado por uma cadeia de caracteres de modelo de formato, lista de idiomas, região geográfica, calendário e relógio.
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat)	Cria um objeto DateTimeFormatter inicializado com formatos de ano, mês, dia e dia da semana.
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>)	Cria um objeto DateTimeFormatter inicializado com ano, mês, dia, dia da semana, hora, minuto e segundo formatos e uma lista de idiomas.
DateTimeFormatter(YearFormat, MonthFormat, DayFormat, DayOfWeekFormat, HourFormat, MinuteFormat, SecondFormat, IIterable<String>, String, String, String)	Cria um objeto DateTimeFormatter com todos os formatos e identificadores especificados.

Propriedades

Calendar	Obtém o calendário usado ao formatar datas.
Clock	Obtém o relógio usado ao formatar horários.
GeographicRegion	Obtém ou define a região usada ao formatar datas e horas.
IncludeDay	Obtém o DayFormat no modelo.
IncludeDayOfWeek	Obtém o DayOfWeekFormat no modelo.
IncludeHour	Obtém o HourFormat no modelo.
IncludeMinute	Obtém o MinuteFormat no modelo.
IncludeMonth	Obtém o MonthFormat no modelo.
IncludeSecond	Obtém o SecondFormat no modelo.
IncludeYear	Obtém o YearFormat no modelo.
Languages	Obtém a lista de prioridades de identificadores de idioma usados ao formatar datas e horas.
LongDate	Obtém o objeto DateTimeFormatter que formata datas de acordo com a escolha do usuário pelo padrão de data longa.
LongTime	Obtém o objeto DateTimeFormatter que formata horários de acordo com a escolha do usuário pelo padrão de longo tempo.
NumeralSystem	Obtém ou define o sistema de numeração usado para formatar datas e horas.
Patterns	Obtém os padrões correspondentes a esse modelo que são usados ao formatar datas e horas.
ResolvedGeographicRegion	Obtém a região geográfica que foi usada mais recentemente para formatar datas e horas.
ResolvedLanguage	Obtém o idioma que foi usado mais recentemente para formatar datas e horas.
ShortDate	Obtém o objeto DateTimeFormatter que formata datas de acordo com a escolha do usuário pelo padrão de data curta.
ShortTime	Obtém o objeto DateTimeFormatter que formata horários de acordo com a escolha do usuário pelo padrão de tempo curto.
Template	Obtém uma representação de cadeia de caracteres desse modelo de formato.

Métodos

Format(DateTime)	Retorna uma representação de cadeia de caracteres da data e hora fornecidas.
Format(DateTime, String)	Retorna uma cadeia de caracteres que representa a data e a hora especificadas no fuso horário especificado, em conformidade com o modelo que o formatador está usando no momento.

Confira também

• Exemplo de formatação de data e hora
• Exemplo de formatação de data e hora (Windows 10)