Format et saisie

Un champ écrit ce qu'il sait relire. C'est toute la règle : quelle que soit la forme que prend le texte, le taper veut dire la même chose que le choisir.

Chaque exemple ci-dessous est un <tz-datetime-field>, et chaque option montrée fonctionne pareil sur le champ date et sur le champ période.

Par défaut : la forme de la locale

Rien à régler. Le champ écrit ce qu'écrit Intl pour cette locale, et accepte la même chose tapée en retour.

nothing chosen

Le même moment, trois locales — le champ appartient à la locale, pas à la librairie :

nothing chosen

nothing chosen

format

Un motif, utilisé pour écrire et pour lire. Ce que vous imposez est aussi ce que le champ acceptera à la saisie.

createDateTimeField(element, { timeZone: 'Europe/Paris', format: 'yyyy-MM-dd HH:mm' });

nothing chosen

format: "d MMMM yyyy 'à' HH:mm"

nothing chosen

Un motif qui nomme son mois ne peut pas être saisi

« sept. », « Sept » et « septembre » sont un même mois en trois orthographes, et choisir entre elles est la façon dont un champ enregistre discrètement la mauvaise date. parseWith refuse un tel motif plutôt que de deviner : un champ qui en utilise un est fait pour l'affichage, donc à associer à editable: false, comme ci-dessus.

Les jetons

yyyy yy	année
MMMM MMM MM M	mois : nom, nom court, 09, 9
dd d	jour
EEEE EEE	nom du jour, nom court
HH H	heure, sur 24
hh h	heure, sur 12
mm	minute
a	AM ou PM

Tout le reste est gardé tel quel ; 'du texte entre quotes' conserve ses lettres.

nothing chosen

dateStyle et timeStyle

Les formes propres à Intl. Elles s'appliquent quand le champ n'est pas saisissable, parce qu'on ne relit pas une forme que la locale a choisie elle-même.

createDateTimeField(element, {
  timeZone: 'Europe/Paris', editable: false,
  dateStyle: 'long', timeStyle: 'short',
});

nothing chosen

nothing chosen

nothing chosen

displayWith

Le dernier mot. Elle reçoit la valeur et le fuseau, et ce qu'elle rend est ce que le champ affiche.

createDateTimeField(element, {
  timeZone: 'Europe/Paris',
  editable: false,
  displayWith: (at, timeZone) => {
    const zoned = at.toZonedDateTimeISO(timeZone);
    return `${zoned.day}/${zoned.month} — semaine ${zoned.weekOfYear}`;
  },
});

nothing chosen

editable

true par défaut : le déclencheur est un champ de saisie. false en fait un bouton, et la valeur ne se choisit plus que dans le panneau.

nothing chosen

mask

Les séparateurs apparaissent à mesure que les chiffres arrivent, comme un numéro de carte prend ses espaces :

2 → 2        20 → 20/       2009 → 20/09/      20092026 → 20/09/2026

Tapez dans celui-ci pour le voir se faire :

nothing chosen

Et le même champ avec mask: false — chaque séparateur tapé à la main :

nothing chosen

Ça ne s'applique qu'aux motifs qui ne laissent aucun doute sur la fin de chaque partie — dd/MM/yyyy oui, d/M/yyyy non — et jamais pendant une suppression, parce qu'un séparateur remis là où on vient de l'enlever rend un champ impossible à corriger.

Les lettres n'entrent jamais dans le texte. Une date qui ne peut pas exister, ou qui tombe hors de min et max, est refusée, et le champ revient au moment qu'il tenait quand vous le quittez.

Le motif n'est jamais utilisé comme texte indicatif : un champ qui explique son propre format avant qu'on ait rien tapé n'invite pas à répondre. placeholder est là pour ce que vous voulez dire à la place.

nothing chosen

Les mêmes fonctions, toutes seules

Tout ce qui précède, ce sont ces quatre fonctions, exportées par @tzslot/dom.

import { formatWith, parseWith, patternFor, maskWith } from '@tzslot/dom';

formatWith('EEE d MMM', { date }, 'fr-FR');   // 'dim. 20 sept.'
parseWith('yyyy-MM-dd', '2026-02-31');        // null — ce jour n'existe pas
patternFor('en-US', { time: true });          // 'MM/dd/yyyy hh:mm a'
maskWith('dd/MM/yyyy', '2009');               // '20/09/'

Que parseWith rende null plutôt que le jour valide le plus proche, c'est tout l'intérêt : le 31 février est une faute de frappe, et un champ qui la transforme discrètement en 3 mars a enregistré quelque chose que personne n'a tapé.