Compartilhar via

Usar modelos e padrões para formatar datas e horas

  • Artigo

Use classes no namespace Windows.Globalization.DateTimeFormatting com modelos e padrões personalizados para mostrar datas e horas exatamente no formato desejado.

Introdução

A classe DateTimeFormatter fornece várias maneiras de formatar corretamente datas e horas para idiomas e regiões em todo o mundo. É possível utilizar formatos padrão para ano, mês, dia e assim por diante. Ou você pode transmitir um modelo de formato para o argumento formatTemplate do construtor DateTimeFormatter, como "longdate" ou "month day".

Porém, quando você deseja ainda mais controle sobre a ordem e o formato dos componentes do objeto DateTime que deseja exibir, pode transmitir um padrão de formato para o argumento formatTemplate do construtor. Um padrão de formato usa uma sintaxe especial, que permite obter componentes individuais de um objeto DateTime (apenas o nome do mês ou apenas o valor do ano, por exemplo) para exibi-los em qualquer formato personalizado que escolher. Além disso, o padrão pode ser localizado para se adaptar a outros idiomas e regiões.

Observação: esta é apenas uma visão geral dos padrões de formato. Para uma discussão mais completa sobre modelos de formato e padrões de formato, consulte a seção Comentários da classe DateTimeFormatter.

A diferença entre modelos de formato e padrões de formato

Um modelo de formato é uma cadeia de caracteres de formato independente da cultura. Portanto, se você construir um DateTimeFormatter usando um modelo de formato, o formatador exibirá seus componentes de formato na ordem correta para o idioma atual. Por outro lado, um padrão de formato é específico de cada cultura. Se você construir um DateTimeFormatter usando um padrão de formato, o formatador utilizará o padrão exatamente como fornecido. Consequentemente, um padrão não é necessariamente válido entre culturas.

Vamos ilustrar essa distinção com um exemplo: Transmitiremos um modelo de formato simples (não um padrão) ao construtor DateTimeFormatter. Este é o modelo de formato "month day".

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

Ele cria um formatador com base no valor de idioma e região do contexto atual. A ordem dos componentes em um modelo de formato não importa. O formatador os mostra na ordem correta para o idioma atual. Portanto, ele exibe "January 1" para inglês (Estados Unidos), "1 janvier" para francês (França) e "1月1日" para japonês.

Por outro lado, um padrão de formato é específico de cada cultura. Vamos acessar o padrão de formato do nosso modelo de formato.

IReadOnlyList<string> monthDayPatterns = dateFormatter.Patterns;

Isso produz resultados diferentes dependendo da linguagem de tempo de execução e da região. Regiões diferentes podem utilizar componentes diferentes, em ordens diferentes, com ou sem caracteres e espaçamento adicionais.

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

No exemplo acima, inserimos uma cadeia de caracteres de formato independente de cultura e obtivemos de volta uma cadeia de caracteres de formato específico de cultura (que era uma função do idioma e da região que estavam em vigor quando chamamos dateFormatter.Patterns). Portanto, se você construir um DateTimeFormatter a partir de um padrão de formato específico de cada cultura, ele apenas será válido para idiomas/regiões específicos.

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

O formatador acima retorna valores específicos de cada cultura para os componentes individuais dentro dos colchetes {}. Porém, a ordem dos componentes em um padrão de formato não varia. Você recebe exatamente o que pede, que pode ou não ser culturalmente apropriado. Esse formatador é válido para inglês (Estados Unidos), mas não para francês (França) nem para japonês.

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, um padrão correto hoje pode não estar correto no futuro. Países ou regiões podem alterar seus sistemas de calendário, o que altera um modelo de formato. O Windows atualiza a saída de formatadores com base em modelos de formato para acomodar essas alterações. Por isso, você apenas deve utilizar a sintaxe de padrão em uma ou mais dessas condições.

  • Você não depende de uma saída específica para um formato.
  • Você não precisa do formato para seguir algum padrão específico de cultura.
  • Você pretende especificamente que o padrão não varie entre culturas.
  • Você pretende localizar a própria cadeia de caracteres de padrão de formato real.

Veja a seguir um resumo da distinção entre modelos de formato e padrões de formato.

Modelos de formato, como "month day"

  • Representação abstrata de um formato DateTime, que inclui valores para o mês, dia, etc., em qualquer ordem.
  • Garantia de retorno de um formato padrão válido em todos os valores de região de idioma com suporte pelo Windows.
  • Garantia de fornecer uma cadeia de caracteres formatada culturalmente apropriada para a região de idioma especificada.
  • Nem todas as combinações de componentes são válidas. Por exemplo, "dayofweek day" não é válido.

Padrões de formato, como "{month.full} {day.integer}"

  • Cadeia de caracteres explicitamente ordenada que expressa o nome completo do mês, seguido por um espaço, seguido pelo número inteiro do dia, nessa ordem ou qualquer padrão de formato específico.
  • Pode não corresponder a um formato padrão válido para qualquer par idioma/região.
  • Não é garantido que seja culturalmente apropriado.
  • Qualquer combinação de componentes pode ser especificada, em qualquer ordem.

Exemplos

Suponha que você queira mostrar o mês e o dia atuais junto com a hora atual, em um formato específico. Por exemplo, você gostaria que os usuários na localidade inglês dos EUA vissem algo assim:

June 25 | 1:38 PM

A parte de data corresponde ao modelo de formato "month day" e a parte de tempo corresponde ao modelo de formato de "hour minute". Portanto, pode construir formatters para os modelos de formato de data e hora relevantes e, em seguida, concatenar sua saída usando uma cadeia de caracteres de formato localizável.

var dateToFormat = System.DateTime.Now;
var resourceLoader = Windows.ApplicationModel.Resources.ResourceLoader.GetForCurrentView();

var dateFormatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day");
var timeFormatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("hour minute");

var date = dateFormatter.Format(dateToFormat);
var time = timeFormatter.Format(dateToFormat);

string output = string.Format(resourceLoader.GetString("CustomDateTimeFormatString"), date, time);

CustomDateTimeFormatString é um identificador de recurso que faz referência a um recurso localizável em um arquivo de recursos (.resw). Para um idioma padrão do inglês (Estados Unidos), isso seria definido como um valor de "{0} | {1}" junto com um comentário indicando que "{0}" é a data e "{1}" é a hora. Dessa forma, os tradutores podem ajustar os itens de formato conforme necessário. Por exemplo, eles podem alterar a ordem dos itens se parecer mais natural em algum idioma ou região ter a hora anterior à data. Ou podem substituir "|" por algum outro caractere separador.

Outra maneira de implementar este exemplo é consultar os dois formatadores para seus padrões de formato, concatená-los juntos e, em seguida, construir um terceiro formatador a partir do padrão de formato resultante.

var resourceLoader = Windows.ApplicationModel.Resources.ResourceLoader.GetForCurrentView();

var dateFormatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("month day");
var timeFormatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter("hour minute");

string dateFormatterPattern = dateFormatter.Patterns[0];
string timeFormatterPattern = timeFormatter.Patterns[0];

string pattern = string.Format(resourceLoader.GetString("CustomDateTimeFormatString"), dateFormatterPattern, timeFormatterPattern);

var patternFormatter = new Windows.Globalization.DateTimeFormatting.DateTimeFormatter(pattern);

string output = patternFormatter.Format(System.DateTime.Now);

APIs importantes