Como usar padrões para formatar datas e horas (HTML)

  • Artigo

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Use a API Windows.Globalization.DateTimeFormatting com padrões personalizados para exibir datas e horas no formato exato que você deseja.

Windows.Globalization.DateTimeFormatting fornece várias maneiras de formatar corretamente as datas e horas para idiomas e regiões ao redor do mundo. Na maioria das vezes, você pode usar formatos padrão para ano, mês, dia e assim por diante. Ou pode usar modelos de cadeias de caracteres padrão, como "data completa" ou "dia do mês", para garantir que o formato de DateTime resultante seja apropriado para a cultura, o idioma e a região do usuário. Entretanto, em alguns casos, talvez seja preferível ter maior controle sobre a ordem e o formato dos componentes da cadeia de caracteres DateTime que você deseja exibir. Isso porque sua meta pode ser determinada cultura ou região conhecida ou você quer exibir componentes em um formato não padrão.

Para essa finalidade, você pode usar uma sintaxe especial para o parâmetro do modelo da cadeia de caracteres, chamada "padrão". A sintaxe de padrões permite que você obtenha os componentes individuais de um objeto DateTime— como o nome do mês ou o valor do ano — a fim de exibi-los em qualquer formato personalizado que você escolher.

O que você precisa saber

Tecnologias

Pré-requisitos

É importante notar que, ao usar padrões, você está essencialmente construindo um formato personalizado que não tem garantia de ser válido entre culturas. Por exemplo, considere o modelo "dia do mês":

var datefmt = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day");

Isso cria um formatador com base no valor do idioma ou da região do contexto atual. Portanto, ele sempre exibe o mês e o dia juntos em um formato global apropriado. Por exemplo, ele exibe "January 1" para inglês (EUA), mas "1 janvier" para francês (França) e "1月1日" para japonês. Isso se deve ao fato de o modelo ser baseado em uma cadeia de caracteres de padrão específico a uma cultura, que pode ser acessada por meio da propriedade do padrão:

var monthdaypattern = datefmt.patterns;

Isso produz resultados diferentes, dependendo do idioma e da região do formatador. Note que diferentes regiões podem usar diferentes componentes, em ordens diferentes, com ou sem espaçamento de caracteres adicionais:

En-US: "{month.full} {day.integer}"
Fr-FR: "{day.integer} {month.full}"
Ja-JP: "{month.integer}月{day.integer}日"

Você pode usar padrões para construir um DateTimeFormatter personalizado, por exemplo, este baseado no padrão Inglês dos EUA:

var datefmt = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("{month.full} {day.integer}");

O Windows retorna valores específicos de cultura para os componentes individuais dentro de colchetes {}. Mas, com a sintaxe de padrões, a ordem dos componentes é invariável. Você obtém exatamente o que deseja, o que talvez não seja apropriado em termos de cultura:

En-US: January 1
Fr-FR: janvier 1 (inappropriate for France; non-standard order)
Ja-JP: 1月1 (inappropriate for Japan; the day symbol is missing)

Além disso, não há garantia de que os padrões permanecerão consistentes ao longo do tempo. Os países ou regiões podem alterar seus sistemas de calendário, o que modifica um modelo de formato. O Windows atualiza a saída dos formatadores para acomodar essas alterações. Portanto, você só deve usar a sintaxe de padrões para formatar DateTimes quando:

  • Você não depende de determinada saída para um formato
  • Você não precisa do formato para seguir algum padrão de cultura específico
  • Você pretende especificamente que o padrão seja invariável entre culturas
  • Você pretende localizar o padrão

Para resumir as diferenças entre os modelos de cadeia de caracteres padrão e padrões de cadeia de caracteres não padrão:

Modelos de cadeias de caracteres, como "month day":

  • Representação abstrata de um formato de DateTime que inclui valores para o mês e o dia, em alguma ordem.
  • Garante retornar um formato padrão válido em todos os valores da região de idioma com suporte do Windows.
  • Garante fornecer uma cadeia de caracteres formatada culturalmente de forma adequada para a região de idioma determinada.
  • Nem todas as combinações de componentes são válidas. Por exemplo, não há modelo de cadeia de caracteres para "dayofweek day".

Padrões de cadeias de caracteres, como "{month.full} {day.integer}":

  • Ordenou explicitamente a cadeia de caracteres que expressa o nome completo do mês, seguido por um espaço, seguido pelo número inteiro de dias, nessa ordem.
  • Pode não corresponder a um formato padrão válido para qualquer par de idioma-região.
  • Não garante ser culturalmente apropriada.
  • Qualquer combinação de componentes pode ser especificada, em qualquer ordem.

Instruções

Suponha que você queira mostrar o mês e o dia atuais juntamente com a hora atual, em um formato específico. Por exemplo, você quer que os usuários do Inglês dos EUA vissem algo parecido com isto:

June 25 | 1:38 PM

A parte da data corresponde ao modelo "dia do mês", e a parte da hora corresponde ao modelo "hora-minuto". Assim, você pode criar um formato personalizado para concatenar os padrões que formam esses modelos.

Primeiro, obtenha os formatadores para os modelos de hora e data relevantes e obtenha os padrões desses modelos:

// Get formatters for the date part and the time part.
var dtf = Windows.Globalization.DateTimeFormatting;
var mydate = dtf.DateTimeFormatter("month day");
var mytime = dtf.DateTimeFormatter("hour minute");

// Get the patterns from these formatters.
var mydatepattern = mydate.patterns[0];
var mytimepattern = mytime.patterns[0];

Você deve armazenar seu formato personalizado como uma cadeia de recurso localizável. Por exemplo, a cadeia de caracteres para Inglês (Estados Unidos) seria "{date} | {time}". Os localizadores podem ajustar essa cadeia de caracteres conforme necessário. Por exemplo, eles podem mudar a ordem dos componentes, caso pareça mais natural em algum idioma ou região que a hora preceda a data. Ou eles podem substituir "|" por algum outro caractere separador. No tempo de execução, você substituir as partes de {date} e {time} da cadeia de caracteres pelo padrão relevante:

// Assemble the custom pattern. This string comes from a resource, and should be localizable. 
var mydateplustime = WinJS.Resources.getString("date_plus_time");
mydateplustime = mydateplustime.replace("{date}", mydatepattern);
mydateplustime = mydateplustime.replace("{time}", mytimepattern);

Você pode agora construir um novo formatador com base no padrão personalizado:

// Get the custom formatter.
var mydateplustimefmt = new dtf.DateTimeFormatter(mydateplustime);

Tópicos relacionados

Exemplo de data e hora

Windows.Globalization.DateTimeFormatting

Windows.Foundation.DateTime