Utiliser des modèles de format des dates et heures

  • Article

Utilisez des classes dans l’espace de noms Windows.Globalization.DateTimeFormatting avec des gabarits et des modèles personnalisés pour afficher les dates et les heures dans le format souhaité.

Introduction

La classe DateTimeFormatter fournit différentes façons de mettre en forme correctement les dates et les heures pour les langues et régions du monde entier. Vous pouvez utiliser des formats standard pour l’année, le mois, le jour, et ainsi de suite. Vous pouvez également transférer un modèle de format à l’argument formatTemplate du constructeur DateTimeFormatter, tel que « forme longue de la date » ou « mois jour ».

Toutefois, lorsque vous souhaitez contrôler encore plus l’ordre et le format des composants de l’objet DateHeure que vous souhaitez afficher, vous pouvez passer un modèle de format à l’argument formatTemplate du constructeur. Un modèle de format utilise une syntaxe spéciale, qui vous permet d’obtenir des composants individuels d’un objet DateHeure (juste le nom du mois, ou simplement la valeur d’année, par exemple) pour les afficher dans le format personnalisé que vous choisissez. En outre, le modèle peut être localisé pour s’adapter à d’autres langues et régions.

Notez qu’il s’agit uniquement d’une vue d’ensemble des modèles de format. Pour une présentation plus complète des modèles de format et des modèles de format, reportez-vous à la section Remarque de la classe DateTimeFormatter.

Différence entre les gabarits de format et les modèles de format

Un modèle de format est une chaîne de format indépendant de la culture. Par conséquent, si vous définissez un DateTimeFormatter à l’aide d’un gabarit de format, le formateur affiche vos composants de format dans l’ordre approprié pour la langue actuelle. À l’inverse, un modèle de format est spécifique à une culture. Si vous créez un DateTimeFormatter à l’aide d’un modèle de format, le formateur utilise le modèle exactement comme indiqué. Par conséquent, un modèle n’est pas nécessairement valable dans toutes les cultures.

Prenons un exemple. Nous transmettons un gabarit de format simple (et non un modèle) au constructeur DateTimeFormatter. Il s’agit du gabarit de format « mois jour ».

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

Il crée un formateur basé sur les valeurs de langue et de région du contexte actuel. L’ordre des composants dans un gabarit de format n’a pas d’importance. Le formateur les affiche dans le bon ordre pour la langue concernée. On aura donc « January 1 » en anglais (États-Unis), « 1er janvier » en français (France) et « 1月1日 » en japonais.

En revanche, un modèle de format est propre à la culture. Accédons au modèle de format pour notre modèle de format.

IReadOnlyList<string> monthDayPatterns = dateFormatter.Patterns;

Les résultats varient selon la langue et la région d’exécution. Des régions différentes peuvent utiliser des composants différents, dans des ordres différents, avec ou sans caractères supplémentaires et espacement.

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

Dans l’exemple ci-dessus, nous avons saisi une chaîne de format indépendante de la culture et nous avons obtenu en retour une chaîne de format spécifique à la culture (qui était fonction de la langue et de la région en vigueur au moment de l’appel de dateFormatter.Patterns). Par conséquent, si vous créez un DateTimeFormatter à partir d’un modèle de format spécifique à la culture, il sera valide uniquement pour des langues/régions spécifiques.

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

Le formateur ci-dessus retourne des valeurs propres à la culture pour les composants individuels entre les crochets {}. Mais l’ordre des composants dans un modèle de format est invariable. Vous obtenez précisément ce que vous demandez, ce qui peut être approprié ou non d’un point de vue culturel. Ce formateur est valide pour l’anglais (États-Unis), mais pas pour le français (France) ni pour le japonais.

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)

En outre, un modèle qui est correct aujourd’hui ne le sera peut-être plus à l’avenir. Les pays ou régions peuvent modifier leurs systèmes de calendrier, ce qui modifie un gabarit de format. Windows met à jour la sortie des formateurs en fonction des modèles de format pour prendre en charge ces modifications. Par conséquent, vous devez uniquement utiliser la syntaxe de modèle dans au moins un de ces cas.

  • Vous n’êtes pas tributaire d’un format de sortie particulier.
  • Vous n’avez pas besoin que le format suive une norme spécifique à une culture.
  • Vous souhaitez que le modèle soit invariant d’une culture à l’autre.
  • Vous comptez localiser la chaîne de modèle du format elle-même.

Voici un résumé de la différence entre les gabarits de format et les modèles de format.

Mettre en forme des modèles, tels que « mois jour »

  • Représentation abstraite d’un format DateHeure qui inclut dans n’importe quel ordre des valeurs pour le mois, le jour, etc.
  • Garantie de retour d’un format standard valide pour toutes les valeurs de langue et de région prises en charge par Windows.
  • Garantie de restitution d’une chaîne de format appropriée sur le plan culturel pour la région linguistique donnée.
  • Toutes les combinaisons de composants ne sont pas valides. Par exemple, « jourdelasemaine jour » est non valide.

Modèles de format, tels que « {month.full} {day.integer} »

  • Chaîne classée de manière explicite qui exprime le nom complet du mois, suivi d’un espace, suivi de l’entier du jour, dans cet ordre, ou tout autre modèle de format spécifique que vous spécifiez.
  • Peut ne pas correspondre à un format standard valide pour une paire langue-région.
  • Il n’est pas garanti qu’il soit approprié d’un point de vue culturel.
  • Toute combinaison de composants peut être spécifiée, dans n’importe quel ordre.

Exemples

Supposons que vous souhaitiez afficher le mois et le jour actuels ainsi que l’heure actuelle, dans un format spécifique. Par exemple, vous aimeriez que les locuteurs de l’anglais américain reçoivent un message de ce type :

June 25 | 1:38 PM

Les parties date et heure correspondent respectivement aux gabarits de format « mois jour » et « heure minute ». Vous pouvez donc construire des formateurs pour les gabarits de format de date et d’heure concernés, puis concaténer leurs résultats à l’aide d’une chaîne de format localisable.

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 est un identificateur de ressource faisant référence à une ressource localisable dans un fichier de ressources (.resw). Pour une langue par défaut définie sur l’anglais (États-Unis), cette valeur est définie sur « {0} | {1} » ainsi qu’un commentaire indiquant que « {0} » est la date et « {1} », l’heure. Les traducteurs peuvent ainsi ajuster les éléments de format selon leurs besoins. Par exemple, ils peuvent modifier l’ordre des éléments s’il semble plus naturel dans une langue ou une région de faire précéder l’heure par la date. Ils peuvent également remplacer « | » par un autre séparateur.

Une autre façon de mettre en œuvre cet exemple consiste à demander aux deux formateurs leurs modèles de format, à les concaténer, puis à construire un troisième formateur à partir du modèle de format résultant.

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);

API importantes