useDateTimePicker

Hook pour la sélection combinée de la date et de l’heure. Étend useDatePicker avec un état pour l’heure (heure, minute, seconde, période) et un sélecteur d’heure imbriqué.

Importer

import { useDateTimePicker } from "react-date-range-picker-headless";

Utilisation

import { useState } from "react";
import { useDateTimePicker } from "react-date-range-picker-headless";

function MyDateTimePicker() {
  const [dateTime, setDateTime] = useState<Date | null>(null);

  const picker = useDateTimePicker({
    value: dateTime,
    onChange: setDateTime,
    time: { precision: "minute", hourFormat: "24", minuteStep: 5 },
  });

  return (
    <div ref={picker.containerRef}>
      <button onClick={picker.handleToggle}>
        {picker.displayValue || picker.locale.dateTimePlaceholder}
      </button>
      {picker.isOpen && (
        <div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}>
          {/* Calendrier (identique à useDatePicker) */}
          <div>
            <button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
            <span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
            <button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
          </div>
          {/* ...grille du calendrier... */}

          {/* Affichage de l'heure */}
          <div>
            <span>Time: {picker.timeDisplayValue}</span>
          </div>

          {/* Contrôles de l'heure */}
          <div>
            <input
              type="number"
              value={picker.tempHour}
              onChange={(e) => picker.handleHourChange(Number(e.target.value))}
            />
            <span>:</span>
            <input
              type="number"
              value={picker.tempMinute}
              onChange={(e) => picker.handleMinuteChange(Number(e.target.value))}
            />
          </div>

          <button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
        </div>
      )}
    </div>
  );
}

Options

Option	Type	Défaut	Description
`value`	`Date \| null`	—	Requis. Valeur date-heure actuelle.
`onChange`	`(dateTime: Date \| null) => void`	—	Requis. Appelé lorsque la date-heure change.
`time`	`TimeConfig`	`{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }`	Configuration du sélecteur d’heure.
`minDate`	`Date`	—	Date la plus ancienne sélectionnable.
`maxDate`	`Date`	—	Date la plus récente sélectionnable.
`locale`	`Partial<Locale>`	`DEFAULT_LOCALE`	Surcharger les chaînes de la locale.
`initialMonth`	`Date`	—	Mois initial à afficher.
`size`	`DatePickerSize`	—	Transmission à l’UI.
`weekStartsOn`	`WeekDay`	`"sunday"`	Premier jour de la semaine.
`isDateUnavailable`	`(date: Date) => boolean`	—	Fonction personnalisée pour désactiver des dates spécifiques.
`displayFormat`	`string`	—	Chaîne de format personnalisée pour la valeur affichée.
`open`	`boolean`	—	État d’ouverture contrôlé.
`initialOpen`	`boolean`	`false`	État d’ouverture initial.
`onOpenChange`	`(open: boolean) => void`	—	Callback lorsque l’état d’ouverture change.
`required`	`boolean`	`false`	Si vrai, `handleClear` ne fait rien.
`today`	`Date`	`new Date()`	Surcharger la date d’aujourd’hui.
`onMonthChange`	`(month: Date) => void`	—	Callback lorsque le mois change.
`disablePast`	`boolean`	`false`	Désactiver les dates passées.
`disableFuture`	`boolean`	`false`	Désactiver les dates futures.
`showOutsideDays`	`boolean`	`false`	Afficher les jours des mois adjacents.
`highlightDates`	`Date[]`	—	Dates à surligner.
`shouldCloseOnSelect`	`boolean`	`false`	Pour les sélecteurs de date-heure, s’applique uniquement aux clics sur les préréglages, pas aux clics sur les dates.
`numberOfMonths`	`number`	`1`	Nombre de mois du calendrier.
`captionLayout`	`CaptionLayout`	`"buttons"`	Mode de disposition de la légende.
`fromYear`	`number`	année actuelle - 100	Année de début pour la liste déroulante.
`toYear`	`number`	année actuelle + 10	Année de fin pour la liste déroulante.

Valeurs de Retour

État de la Date

Nom	Type	Description
`isOpen`	`boolean`	Indique si la popup est ouverte.
`tempDate`	`Date \| null`	Date sélectionnée temporaire.
`currentMonth`	`Date`	Mois actuellement affiché.
`locale`	`Locale`	Objet de la locale résolu.

État de l’Heure

Nom	Type	Description
`isTimePickerOpen`	`boolean`	Indique si le sous-panneau du sélecteur d’heure est ouvert.
`tempHour`	`number`	Valeur de l’heure temporaire actuelle.
`tempMinute`	`number`	Valeur de la minute temporaire actuelle.
`tempSecond`	`number`	Valeur de la seconde temporaire actuelle.
`tempPeriod`	`TimePeriod`	Période AM/PM actuelle (`"AM"` ou `"PM"`).

Actions de Date

Nom	Type	Description
`handleDateClick`	`(date: Date) => void`	Gérer le clic sur la cellule du jour.
`handlePrevMonth`	`() => void`	Naviguer au mois précédent.
`handleNextMonth`	`() => void`	Naviguer au mois suivant.
`handleOpen`	`() => void`	Ouvrir la popup.
`handleClose`	`() => void`	Fermer la popup.
`handleToggle`	`() => void`	Basculer la popup.
`handleConfirm`	`() => void`	Confirmer la date + l’heure et fermer.
`handleCancel`	`() => void`	Annuler et revenir en arrière.
`handleClear`	`() => void`	Effacer la valeur.
`handleGoToToday`	`() => void`	Naviguer à aujourd’hui.

Actions de l’Heure

Nom	Type	Description
`handleHourChange`	`(hour: number) => void`	Mettre à jour l’heure.
`handleMinuteChange`	`(minute: number) => void`	Mettre à jour la minute.
`handleSecondChange`	`(second: number) => void`	Mettre à jour la seconde.
`handlePeriodChange`	`(period: TimePeriod) => void`	Basculer AM/PM.
`handleTimePickerOpen`	`() => void`	Ouvrir le sous-panneau du sélecteur d’heure.
`handleTimePickerClose`	`() => void`	Fermer le sous-panneau du sélecteur d’heure.
`handleTimePickerConfirm`	`() => void`	Confirmer le sous-panneau du sélecteur d’heure.
`handleTimePickerCancel`	`() => void`	Annuler le sous-panneau du sélecteur d’heure.

Valeurs Calculées

Nom	Type	Description
`calendar`	`CalendarMonth`	Données du calendrier pour le mois en cours.
`calendars`	`CalendarMonth[]`	Tableau des mois du calendrier.
`getDayProps`	`(date: Date, referenceMonth?: Date) => DayProps`	Props de la cellule du jour.
`displayValue`	`string`	Chaîne de date-heure formatée.
`timeDisplayValue`	`string`	Chaîne d’heure formatée.
`hasValue`	`boolean`	Indique si une valeur est confirmée.
`canConfirm`	`boolean`	Indique si la confirmation est valide.
`containerRef`	`RefObject<HTMLDivElement \| null>`	Ref du conteneur.
`popupRef`	`RefObject<HTMLDivElement \| null>`	Ref de la popup.
`timePickerRef`	`RefObject<HTMLDivElement \| null>`	Ref du sous-panneau du sélecteur d’heure.
`focusedDate`	`Date \| null`	Date focalisée par le clavier.
`handleKeyDown`	`(e: KeyboardEvent<HTMLElement>) => void`	Gestionnaire de clavier.
`resolvedTimeConfig`	`Required<TimeConfig>`	Configuration de l’heure résolue avec les valeurs par défaut remplies.
`years`	`number[]`	Années pour le mode liste déroulante.
`months`	`number[]`	Mois pour le mode liste déroulante.
`handleYearSelect`	`(year: number, calendarIndex?: number) => void`	Définir l’année.
`handleMonthSelect`	`(month: number, calendarIndex?: number) => void`	Définir le mois.

Comportements Clés

Configuration de l’Heure

L’option time accepte un objet TimeConfig :

interface TimeConfig {
  precision?: "hour" | "minute" | "second"; // default: "minute"
  hourFormat?: "12" | "24"; // default: "24"
  minuteStep?: 1 | 2 | 3 | 5 | 10 | 15 | 20 | 30; // default: 5
  secondStep?: 1 | 2 | 3 | 5 | 10 | 15 | 20 | 30; // default: 1
  itemHeight?: number; // default: 32
}

shouldCloseOnSelect

Pour les sélecteurs de date et heure, shouldCloseOnSelect ne se déclenche que sur les clics de préréglages, et non sur les clics de date. C’est parce que l’utilisateur doit encore régler l’heure après avoir sélectionné une date.

resolvedTimeConfig

La valeur de retour resolvedTimeConfig contient la configuration de l’heure entièrement résolue avec toutes les valeurs par défaut. Utilisez-la lors de la création de composants d’interface utilisateur liés à l’heure pour éviter de recalculer les valeurs par défaut.