Compartilhar via

DateTimeFormatter Classe

  • Referência

Definição

Namespace:
Windows.Globalization.DateTimeFormatting
Editar

Formata datas e horas.

public ref class DateTimeFormatter sealed
/// [Windows.Foundation.Metadata.Activatable(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [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)]
class DateTimeFormatter final
/// [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.Activatable(typeof(Windows.Globalization.DateTimeFormatting.IDateTimeFormatterFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[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)]
public sealed class DateTimeFormatter
[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.

ModeloLanguageRelógioSaídaPadrão equivalente
longdatept-BR<não especificado>Segunda-feira, 2 de setembro de 2013{dayofweek.full}, {month.full} {day.integer}, {year.full}
longdatefr-FR<não especificado>lundi 2 septembre 2013{dayofweek.full} {day.integer} {month.full} {year.full}
shortdatept-BR<não especificado>9‎/‎2‎/‎2013{month.integer}/{day.integer}/{year.full}
shortdatefr-FR<não especificado>02‎/‎09‎/‎2013{day.integer(2)}/{month.integer(2)}/{year.full}
dia do mês dayofweekpt-BR<não especificado>Segunda-feira, 2 de setembro{dayofweek.full}, {month.full} {day.integer}
dayofweek do dia do mêspt-BR<não especificado>Segunda-feira, 2 de setembro{dayofweek.full}, {month.full} {day.integer}
Longa datapt-BR<não especificado>6:01:24 AM{hour.integer}:{minute.integer(2)}:{second.integer(2)} {period.abbreviated}
Longa datapt-BR24HourClock‎17‎:‎32‎:‎45{hour.integer}:{minute.integer(2)}:{second.integer(2)}
Longa datafr-FR<não especificado>17‎:‎32‎:‎45{hour.integer(2)}:{minute.integer(2)}:{second.integer(2)}
shorttimept-BR<não especificado>6h01{hour.integer}:{minute.integer(2)} {period.abbreviated}
shorttimept-BR24HourClock17‎:‎32{hour.integer}:{minute.integer(2)}
shorttimefr-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ãoIdiomaRelógioSaí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-US24HourClock17: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.

Aplica-se a

Confira também