Formatage des dates

OpenMRS fournit plusieurs utilitaires pour travailler avec les dates. Ces utilitaires ont été conçus en tenant compte de la sensibilité aux paramètres locaux. Les formats de date acceptables varient en fonction de la langue et de la région, et les fonctions sont conçues pour tenir compte de ces variations.

Utilitaires de formatage des dates pour l’affichage

formatDate

Cet utilitaire accepte un objet Date et renvoie une chaîne de caractères. Il formate la date d’entrée en fonction de la locale courante et des paramètres donnés:

formatDate(date: Date, options?: {
  mode?: "standard" | "wide",
  time?: boolean | "for today",
  day?: boolean,
  month?: boolean,
  year?: boolean,
  noToday?: boolean,
  locale?: string,
  calendar?: string,
  numberingSystem?: string
}): string

Le paramètre mode peut être réglé sur standard ou wide. Pour les dates en anglais, le mode standard affiche une date comme 16-May-2023, tandis que le mode wide affiche une date comme 16 — May — 2023. Les autres locales peuvent utiliser des noms de mois, des calendriers et une ponctuation propres à la locale.

Par défaut, formatDate utilise { mode: "standard", time: "for today", day: true, month: true, year: true, noToday: false }. Si la date est aujourd’hui, Today est produit à la place du jour réel dans la langue locale, et l’heure est ajoutée parce que l’option time vaut "for today" par défaut. Passez { time: false } pour masquer l’heure pour la date du jour, ou { noToday: true } pour formater aujourd’hui comme une date ordinaire.

Lorsque l’option time vaut true, l’heure est ajoutée avec une virgule et un espace, par exemple 16-May-2023, 08:21. Ce format correspond à la sortie de Date.prototype.toLocaleString pour la plupart des langues.

Voici un exemple d’utilisation de formatDate avec un objet Date :

import { formatDate } from "@openmrs/esm-framework";
 
function AppointmentDetails({ appointment }: AppointmentDetailsProps) {
  return <span>{formatDate(appointment.scheduledDate, { mode: "standard" })}</span>;
}

Pour une locale anglaise, la valeur retournée serait une chaîne au format 18-May-2023.

formatPartialDate

Utilisez formatPartialDate lorsqu’une valeur peut ne contenir qu’une année, ou une année et un mois. C’est fréquent pour des dates cliniques approximatives. La fonction analyse la chaîne avec la locale courante, masque les parties absentes de l’entrée, puis délègue le formatage à formatDate.

formatPartialDate(dateString: string, options?: Partial<FormatDateOptions>): string | null

formatPartialDate("2021"); // "2021"
formatPartialDate("2021-04"); // "Apr 2021"
formatPartialDate("2021-04-09"); // "09-Apr-2021"

formatDatetime

Cette fonction utilitaire accepte un objet Date et renvoie une string. Elle formate la date pour afficher la date et l’heure, séparées par une virgule, selon la locale courante et les options fournies.

formatDatetime accepte les mêmes options que formatDate, sauf time, qui est toujours inclus:

formatDatetime(date: Date, options?: Partial<Omit<FormatDateOptions, "time">>): string

Voici un exemple d’utilisation de formatDatetime :

import { formatDatetime } from "@openmrs/esm-framework";
 
function AppointmentDetails({ appointment }: AppointmentDetailsProps) {
  return <span>{formatDatetime(appointment.scheduledDate)}</span>;
}

Pour une locale anglaise, la valeur retournée serait une chaîne comme 18-May-2023, 08:21.

formatTime

Cette fonction utilitaire accepte un objet Date et renvoie une chaîne. Elle formate l’heure selon la locale courante en utilisant le format 12 ou 24 heures.

formatTime(date: Date): string

Voici un exemple d’utilisation de formatTime :

import { formatTime } from "@openmrs/esm-framework";
 
function AppointmentDetails({ appointment }: AppointmentDetailsProps) {
  return <span>{formatTime(appointment.scheduledDate)}</span>;
}

La valeur retournée dépend de la locale. Par exemple, elle peut être 08:21 dans une locale au format 24 heures ou 08:21 AM dans une locale au format 12 heures.

Durées

Utilisez formatDuration lorsque vous avez déjà une valeur structurée Intl.DurationInput, ou formatDurationBetween lorsque vous voulez calculer et formater la durée entre deux dates.

formatDuration(duration: Intl.DurationInput, options?: Intl.DurationFormatOptions): string
formatDurationBetween(
  startDate: dayjs.ConfigType,
  endDate?: dayjs.ConfigType,
  options?: DurationUnit | DurationOptionsWithFormat
): string | null

import { formatDurationBetween } from "@openmrs/esm-framework";
 
formatDurationBetween("2022-01-01", "2024-07-30"); // "2 yrs"
formatDurationBetween("2022-01-01", "2024-07-30", {
  largestUnit: "years",
  smallestUnit: "days",
  formatOptions: { style: "long" },
}); // "2 years, 6 months, 29 days"

Le helper de plus bas niveau duration retourne l’objet structuré Intl.DurationInput au lieu d’un texte formaté. Il utilise les mêmes seuils de sélection automatique que formatDurationBetween et accepte les noms d’unités au singulier ou au pluriel, comme "year" ou "years".

isOmrsDateStrict

Cet utilitaire vérifie strictement si une chaîne de date correspond au format date-heure de payload OpenMRS. Le format doit être YYYY-MM-DDTHH:mm:ss.SSSZZ. Il accepte une chaîne omrsPayloadString et retourne un boolean.

  isOmrsDateStrict(omrsPayloadString: string): boolean

isOmrsDateToday

Cette fonction vérifie si la date fournie est aujourd’hui. Elle accepte une entrée de type DateInput et retourne un boolean.

  isOmrsDateToday(date: DateInput): boolean

parseDate

Cette fonction utilitaire analyse une dateString arbitraire en une Date. Elle utilise dayjs(dateString).

Voici un exemple d’utilisation de parseDate avec une chaîne date-heure OpenMRS.

import { formatDate, parseDate } from "@openmrs/esm-framework";
 
function EncounterDate({ encounter }: EncounterDateProps) {
  return <span>{formatDate(parseDate(encounter.encounterDateTime))}</span>;
}

Pour une locale française, la valeur retournée serait une chaîne de caractères dans le format propre à la locale, par exemple 18 mai 2023.

toDateObjectStrict

Cette fonction utilitaire convertit une chaîne date-heure de payload OpenMRS en objet Date. Elle accepte omrsDateString et retourne un Date ou null.

  toDateObjectStrict(omrsDateString: string): Date | null

toOmrsIsoString

Cette fonction utilitaire formate la date d’entrée en une chaîne en utilisant le format YYYY-MM-DDTHH:mm:ss.SSSZZ. Il est principalement utilisé pour formater les dates avant de soumettre les données dans les payloads.

  toOmrsIsoString(date: DateInput, toUTC?: boolean): string

Le paramètre toUTC est optionnel et vaut false par défaut. Lorsqu’il est défini à true, la date sera convertie en UTC avant le formatage.

Voici un exemple d’utilisation de toOmrsIsoString dans un payload:

body: {
  visit: visitUuid,
  patientUuid: patientUuid,
  startedAt: toOmrsIsoString(new Date()),
}

Calendriers de locale

O3 peut formater les dates avec des calendriers propres à une locale. Le shell de l’application enregistre les préférences de calendrier de l’implémentation depuis la configuration styleguide preferredCalendar, et formatDate accepte aussi une option calendar pour les remplacements ponctuels.

Utilisez registerDefaultCalendar(locale, calendar) pour enregistrer un calendrier par défaut pour une locale, getDefaultCalendar(locale) pour inspecter le calendrier résolu, et convertToLocaleCalendar(date, locale) lorsque vous travaillez avec des valeurs de calendrier de @internationalized/date.