useDatePicker

Główny hook do wyboru pojedynczej daty. Zarządza stanem kalendarza, zachowaniem otwierania/zamykania, nawigacją za pomocą klawiatury i formatowaniem daty.

Import

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

Użycie

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}>
{/* Nagłówek kalendarza */}
<button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
<span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
<button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
{/* Siatka kalendarza */}
{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>
);
})}
{/* Stopka */}
<button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
</div>
)}
</div>
);
}

Opcje

OpcjaTypDomyślnieOpis
valueDate | nullWymagane. Aktualnie wybrana data.
onChange(date: Date | null) => voidWymagane. Wywoływane, gdy zmieni się wybrana data.
minDateDateNajwcześniejsza data do wyboru.
maxDateDateNajpóźniejsza data do wyboru.
localePartial<Locale>DEFAULT_LOCALEZastąp ciągi znaków lokalizacji.
initialMonthDateMiesiąc do wyświetlenia na początku (domyślnie wartość lub dzisiaj).
sizeDatePickerSizePrzekazywanie do UI dla stylizowanych komponentów. Hooki headless ignorują to.
weekStartsOnWeekDay"sunday"Pierwszy dzień tygodnia.
isDateUnavailable(date: Date) => booleanNiestandardowa funkcja do wyłączania określonych dat.
displayFormatstringNiestandardowy ciąg formatujący dla wyświetlanej wartości (np. "RRRR/MM/DD").
openbooleanKontrolowany stan otwarcia. Gdy podany, hook nie zarządza stanem otwarcia wewnętrznie.
initialOpenbooleanfalsePoczątkowy stan otwarcia (tryb niekontrolowany).
onOpenChange(open: boolean) => voidCallback, gdy zmienia się stan otwarcia. Działa zarówno w trybie kontrolowanym, jak i niekontrolowanym.
requiredbooleanfalseGdy true, handleClear nic nie robi.
todayDatenew Date()Zastąp dzisiejszą datę dla obliczeń isToday i disablePast/disableFuture.
onMonthChange(month: Date) => voidCallback, gdy zmienia się wyświetlany miesiąc.
disablePastbooleanfalseWyłącz wszystkie daty przed dzisiaj.
disableFuturebooleanfalseWyłącz wszystkie daty po dzisiaj.
showOutsideDaysbooleanfalsePokaż dni z sąsiednich miesięcy, aby wypełnić siatkę 6 tygodni.
highlightDatesDate[]Tablica dat do podświetlenia w kalendarzu.
shouldCloseOnSelectbooleanfalseAutomatycznie potwierdź i zamknij po kliknięciu daty.
numberOfMonthsnumber1Liczba miesięcy do jednoczesnego wyświetlenia.
captionLayoutCaptionLayout"buttons""buttons" dla strzałek poprzedni/następny, "dropdown" dla wyboru roku/miesiąca.
fromYearnumberbieżący rok - 100Rok początkowy dla trybu rozwijanego.
toYearnumberbieżący rok + 10Rok końcowy dla trybu rozwijanego.

Zwracane wartości

NazwaTypOpis
isOpenbooleanCzy okienko jest otwarte.
tempDateDate | nullTymczasowo wybrana data (przed potwierdzeniem).
currentMonthDateAktualnie wyświetlany miesiąc.
localeLocaleRozwiązany obiekt lokalizacji ze wszystkimi ciągami znaków.
calendarCalendarMonthDane kalendarza dla bieżącego miesiąca (zawiera month, days, weeks).
calendarsCalendarMonth[]Tablica miesięcy kalendarza (długość = numberOfMonths).
getDayProps(date: Date, referenceMonth?: Date) => DayPropsOblicz flagi dla komórki dnia kalendarza.
displayValuestringSformatowany ciąg znaków potwierdzonej wartości.
hasValuebooleanCzy data jest obecnie potwierdzona.
canConfirmbooleanCzy bieżący wybór jest ważny do potwierdzenia.
handleDateClick(date: Date) => voidObsłuż kliknięcie komórki dnia.
handlePrevMonth() => voidPrzejdź do poprzedniego miesiąca.
handleNextMonth() => voidPrzejdź do następnego miesiąca.
handleOpen() => voidOtwórz okienko.
handleClose() => voidZamknij okienko (odrzuca niezatwierdzone zmiany).
handleToggle() => voidPrzełącz okienko.
handleConfirm() => voidPotwierdź wybór i zamknij.
handleCancel() => voidAnuluj i przywróć poprzednią wartość.
handleClear() => voidWyczyść wartość (nic nie robi, jeśli required).
handleGoToToday() => voidPrzejdź w kalendarzu do dzisiejszego miesiąca.
containerRefRefObject<HTMLDivElement | null>Dołącz do elementu otaczającego w celu wykrywania kliknięć na zewnątrz.
popupRefRefObject<HTMLDivElement | null>Dołącz do elementu okienka.
focusedDateDate | nullAktualnie sfokusowana data za pomocą klawiatury.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidHandler zdarzeń klawiatury dla klawiszy strzałek, Enter, Escape, Tab.
yearsnumber[]Tablica lat dla trybu nagłówka z listą rozwijaną.
monthsnumber[]Tablica indeksów miesięcy (0-11) dla trybu nagłówka z listą rozwijaną.
handleYearSelect(year: number, calendarIndex?: number) => voidUstaw wyświetlany rok (tryb rozwijany).
handleMonthSelect(month: number, calendarIndex?: number) => voidUstaw wyświetlany miesiąc (tryb rozwijany).

Kluczowe zachowania

Kontrolowany vs Niekontrolowany stan otwarcia

Domyślnie hook zarządza otwieraniem/zamykaniem wewnętrznie. Aby kontrolować to zewnętrznie, przekaż open i onOpenChange:

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

shouldCloseOnSelect

Gdy shouldCloseOnSelect ma wartość true, kliknięcie daty natychmiast potwierdza i zamyka okienko, pomijając krok jawnego potwierdzenia.

Nawigacja za pomocą klawiatury

KlawiszAkcja
Strzałki w górę/dół/lewo/prawoPrzesuwaj fokus między dniami
Enter / SpacjaWybierz sfokusowaną datę
EscapeAnuluj i zamknij
TabPrzesuwaj fokus wewnątrz okienka

Nagłówek z listą rozwijaną

Gdy captionLayout ma wartość "dropdown", nagłówek wyświetla listy rozwijane do wyboru roku i miesiąca zamiast przycisków poprzedni/następny. Użyj years, months, handleYearSelect i handleMonthSelect do renderowania list rozwijanych.