useDatePicker

Der zentrale Hook für die Auswahl eines einzelnen Datums. Verwaltet den Kalenderstatus, das Öffnungs-/Schließverhalten, die Tastaturnavigation und die Datumsformatierung.

Importieren

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

Verwendung

import { useState } from "react";
import { useDatePicker } from "react-date-range-picker-headless";
function MyDatePicker() {
const [date, setDate] = useState<Date | null>(null);
const picker = useDatePicker({
value: date,
onChange: setDate,
});
return (
<div ref={picker.containerRef}>
<button onClick={picker.handleToggle}>
{picker.displayValue || picker.locale.placeholder}
</button>
{picker.isOpen && (
<div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}>
{/* Calendar header */}
<button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
<span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
<button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
{/* Calendar grid */}
{picker.calendar.weeks.flat().map((day, i) => {
if (!day) return <span key={i} />;
const dp = picker.getDayProps(day);
return (
<button key={i} onClick={() => picker.handleDateClick(day)} disabled={dp.isDisabled}>
{dp.day}
</button>
);
})}
{/* Footer */}
<button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
</div>
)}
</div>
);
}

Optionen

OptionTypStandardBeschreibung
valueDate | nullErforderlich. Das aktuell ausgewählte Datum.
onChange(date: Date | null) => voidErforderlich. Wird aufgerufen, wenn sich die Datumsauswahl ändert.
minDateDateFrühestes auswählbares Datum.
maxDateDateSpätestes auswählbares Datum.
localePartial<Locale>DEFAULT_LOCALEÜberschreibt die Locale-Texte.
initialMonthDateDer initial anzuzeigende Monat (standardmäßig der Wert oder heute).
sizeDatePickerSizeUI-Durchleitung für gestylte Komponenten. Headless-Hooks ignorieren dies.
weekStartsOnWeekDay"sunday"Erster Tag der Woche.
isDateUnavailable(date: Date) => booleanBenutzerdefinierte Funktion, um bestimmte Daten zu deaktivieren.
displayFormatstringBenutzerdefinierte Formatzeichenfolge für den Anzeigewert (z.B. "YYYY/MM/DD").
openbooleanKontrollierter geöffneter Zustand. Wenn angegeben, verwaltet der Hook den geöffneten Zustand nicht intern.
initialOpenbooleanfalseInitialer geöffneter Zustand (unkontrollierter Modus).
onOpenChange(open: boolean) => voidCallback, wenn sich der geöffnete Zustand ändert. Funktioniert sowohl im kontrollierten als auch im unkontrollierten Modus.
requiredbooleanfalseWenn true, ist handleClear eine Leerausführung (no-op).
todayDatenew Date()Überschreibt das heutige Datum für isToday- und disablePast/disableFuture-Berechnungen.
onMonthChange(month: Date) => voidCallback, wenn der angezeigte Monat wechselt.
disablePastbooleanfalseDeaktiviert alle Daten vor dem heutigen Tag.
disableFuturebooleanfalseDeaktiviert alle Daten nach dem heutigen Tag.
showOutsideDaysbooleanfalseZeigt Tage aus benachbarten Monaten an, um das 6-Wochen-Raster zu füllen.
highlightDatesDate[]Array von Daten, die im Kalender hervorgehoben werden sollen.
shouldCloseOnSelectbooleanfalseAutomatische Bestätigung und Schließen bei Klick auf ein Datum.
numberOfMonthsnumber1Anzahl der gleichzeitig anzuzeigenden Monate.
captionLayoutCaptionLayout"buttons""buttons" für Vor/Zurück-Pfeile, "dropdown" für Jahr/Monat-Auswahl.
fromYearnumberaktuelles Jahr - 100Startjahr für den Dropdown-Modus.
toYearnumberaktuelles Jahr + 10Endjahr für den Dropdown-Modus.

Rückgabewerte

NameTypBeschreibung
isOpenbooleanOb das Popup geöffnet ist.
tempDateDate | nullTemporär ausgewähltes Datum (vor der Bestätigung).
currentMonthDateDer aktuell angezeigte Monat.
localeLocaleAufgelöstes Locale-Objekt mit allen Zeichenketten.
calendarCalendarMonthKalenderdaten für den aktuellen Monat (beinhaltet month, days, weeks).
calendarsCalendarMonth[]Array von Kalendermonaten (Länge = numberOfMonths).
getDayProps(date: Date, referenceMonth?: Date) => DayPropsBerechnet Flags für eine Kalendertag-Zelle.
displayValuestringFormatierte Zeichenkette des bestätigten Wertes.
hasValuebooleanOb ein Datum aktuell bestätigt ist.
canConfirmbooleanOb die aktuelle Auswahl zur Bestätigung gültig ist.
handleDateClick(date: Date) => voidBehandelt einen Klick auf eine Tageszelle.
handlePrevMonth() => voidNavigiert zum vorherigen Monat.
handleNextMonth() => voidNavigiert zum nächsten Monat.
handleOpen() => voidÖffnet das Popup.
handleClose() => voidSchließt das Popup (verwirft nicht übernommene Änderungen).
handleToggle() => voidSchaltet das Popup um.
handleConfirm() => voidBestätigt die Auswahl und schließt.
handleCancel() => voidBricht ab und kehrt zum vorherigen Wert zurück.
handleClear() => voidLöscht den Wert (Leerausführung, wenn required).
handleGoToToday() => voidNavigiert den Kalender zum heutigen Monat.
containerRefRefObject<HTMLDivElement | null>An das Wrapper-Element anhängen zur Erkennung von Klicks außerhalb.
popupRefRefObject<HTMLDivElement | null>An das Popup-Element anhängen.
focusedDateDate | nullAktuell per Tastatur fokussiertes Datum.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidTastaturereignis-Handler für Pfeiltasten, Enter, Escape, Tab.
yearsnumber[]Array der Jahre für den Dropdown-Beschriftungsmodus.
monthsnumber[]Array der Monatsindizes (0-11) für den Dropdown-Beschriftungsmodus.
handleYearSelect(year: number, calendarIndex?: number) => voidSetzt das angezeigte Jahr (Dropdown-Modus).
handleMonthSelect(month: number, calendarIndex?: number) => voidSetzt den angezeigten Monat (Dropdown-Modus).

Schlüsselverhalten

Kontrollierter vs. unkontrollierter geöffneter Zustand

Standardmäßig verwaltet der Hook das Öffnen/Schließen intern. Um es extern zu steuern, übergeben Sie open und onOpenChange:

const [isOpen, setIsOpen] = useState(false);
const picker = useDatePicker({
value: date,
onChange: setDate,
open: isOpen,
onOpenChange: setIsOpen,
});

shouldCloseOnSelect

Wenn shouldCloseOnSelect auf true gesetzt ist, wird durch Klicken auf ein Datum das Popup sofort bestätigt und geschlossen, wodurch der explizite Bestätigungsschritt übersprungen wird.

Tastaturnavigation

TasteAktion
Pfeil hoch/runter/links/rechtsFokus zwischen den Tagen verschieben
Enter / LeertasteDas fokussierte Datum auswählen
EscapeAbbrechen und schließen
TabFokus innerhalb des Popups verschieben

Beschriftungs-Dropdown

Wenn captionLayout auf "dropdown" gesetzt ist, zeigt die Kopfzeile Auswahl-Dropdowns für Jahr und Monat anstelle von Vor/Zurück-Schaltflächen an. Verwenden Sie years, months, handleYearSelect und handleMonthSelect, um die Dropdowns zu rendern.