Gestion des dates fr FR

Résumé : La gestion des dates est notoirement difficile en JavaScript à cause de la façon dont new Date() gère les fuseaux horaires. Cette page explique comment gérer les dates et heures de manière fiable dans votre application à l'aide du helper datetime.

Le modèle mental

StartER recommande une stratégie "UTC pour le stockage, fuseau horaire fixe pour l'UI".

1. Base de données / API : stockez et échangez toujours les dates en UTC (chaîne ISO 8601 se terminant par Z).
2. Logique interne : utilisez des objets Date natifs en UTC.
3. UI : affichez et capturez les dates dans le fuseau horaire du projet (celui où votre projet opère, par exemple "Europe/Paris").

Important

Évitez d'utiliser new Date("2026-05-05") directement. En JavaScript, une chaîne de date seule est interprétée comme minuit UTC. Pour les utilisateurs dans des fuseaux horaires à l'ouest, cela peut produire la date de la veille.

Le fuseau horaire est défini par la variable d'environnement VITE_TIMEZONE. Il est recommandé de le définir sur le fuseau horaire fixe du lieu où votre projet opère (par exemple "Europe/Paris").

Tip

Pour plus de détails, consultez The Subtle Trap of ISO Date Strings in JavaScript (en anglais).

Le helper datetime

StartER fournit un helper robuste et sans dépendance dans src/react/helpers/datetime.ts. Il utilise l'API native Intl pour gérer les décalages et le passage à l'heure d'été.

Le fuseau horaire par défaut est défini par la variable d'environnement VITE_TIMEZONE (par défaut Europe/Paris).

De l'API vers les champs de formulaire

Lorsque vous recevez une date UTC de votre API et que vous souhaitez l'afficher dans un formulaire :

import { toInputDate, toInputTime } from "../helpers/datetime";

const event = { start_time: "2026-05-05T10:00:00Z" };

// À Paris (UTC+2), cela produira :
const dateValue = toInputDate(event.start_time); // "2026-05-05"
const timeValue = toInputTime(event.start_time); // "12:00"

return (
  <form>
    <input type="date" defaultValue={dateValue} />
    <input type="time" defaultValue={timeValue} />
  </form>
);

Du formulaire vers l'API

Pour convertir des chaînes de date et d'heure séparées en un objet Date UTC :

import { fromInputParts } from "../helpers/datetime";

const handleSubmit = (formData) => {
  const iso = fromInputParts(formData.date, formData.time).toISOString();
  
  // Envoi sous forme de chaîne ISO à l'API
  await apiMutate("/api/events", "post", {
    start_time: iso
  });
};

Pour l'affichage

Pour afficher une date localisée à l'utilisateur :

import { toDisplayString, setDisplayOptions } from "../helpers/datetime";

// Par défaut : 5 mai 2026 à 12:00
const label = toDisplayString(event.start_time);

// Options personnalisées
const usLabel = toDisplayString(event.start_time, {
  timeZone: "America/New_York",
  locale: "en-US",
  dateStyle: "full",
});

// Les options peuvent être partagées entre plusieurs appels
setDisplayOptions({
  timeZone: "America/New_York",
  locale: "en-US",
  dateStyle: "full",
});

// Les options sont conservées pour le prochain appel
const usLabel2 = toDisplayString(event.start_time);

Bonnes pratiques

• Ne faites jamais confiance au fuseau horaire du navigateur de l'utilisateur pour la logique métier : fiez-vous toujours au fuseau horaire fixe du projet ou à l'UTC.
• Restez natif : le helper datetime est léger et évite la surcharge de grosses bibliothèques comme Moment.js ou Luxon.