useDateTimePicker

Hook do jednoczesnego wyboru daty i godziny. Rozszerza useDatePicker o stan czasu (godzina, minuta, sekunda, okres) oraz zagnieżdżony selektor czasu.

Import

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

Użycie

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}>
{/* Kalendarz (tak samo jak w 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>
{/* ...siatka kalendarza... */}
{/* Wyświetlanie czasu */}
<div>
<span>Time: {picker.timeDisplayValue}</span>
</div>
{/* Kontrolki czasu */}
<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>
);
}

Opcje

OpcjaTypDomyślnieOpis
valueDate | nullWymagane. Aktualna wartość daty i godziny.
onChange(dateTime: Date | null) => voidWymagane. Wywoływane, gdy data i godzina ulegną zmianie.
timeTimeConfig{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }Konfiguracja selektora czasu.
minDateDateNajwcześniejsza możliwa do wybrania data.
maxDateDateNajpóźniejsza możliwa do wybrania data.
localePartial<Locale>DEFAULT_LOCALEZastępuje ciągi znaków z lokalizacji.
initialMonthDatePoczątkowy miesiąc do wyświetlenia.
sizeDatePickerSizePrzekazywane do interfejsu użytkownika.
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.
openbooleanKontrolowany stan otwarcia.
initialOpenbooleanfalsePoczątkowy stan otwarcia.
onOpenChange(open: boolean) => voidFunkcja zwrotna wywoływana przy zmianie stanu otwarcia.
requiredbooleanfalseGdy true, handleClear nie wykonuje żadnej operacji.
todayDatenew Date()Zastępuje dzisiejszą datę.
onMonthChange(month: Date) => voidFunkcja zwrotna wywoływana przy zmianie miesiąca.
disablePastbooleanfalseWyłącza przeszłe daty.
disableFuturebooleanfalseWyłącza przyszłe daty.
showOutsideDaysbooleanfalsePokazuje dni z sąsiednich miesięcy.
highlightDatesDate[]Daty do wyróżnienia.
shouldCloseOnSelectbooleanfalseW przypadku selektorów daty i godziny, dotyczy tylko kliknięć na presety, a nie na daty.
numberOfMonthsnumber1Liczba miesięcy kalendarza.
captionLayoutCaptionLayout"buttons"Tryb układu nagłówka.
fromYearnumbercurrent year - 100Rok początkowy dla listy rozwijanej.
toYearnumbercurrent year + 10Rok końcowy dla listy rozwijanej.

Zwracane wartości

Stan daty

NazwaTypOpis
isOpenbooleanCzy okienko jest otwarte.
tempDateDate | nullTymczasowo wybrana data.
currentMonthDateAktualnie wyświetlany miesiąc.
localeLocaleRozwiązany obiekt lokalizacji.

Stan czasu

NazwaTypOpis
isTimePickerOpenbooleanCzy podpanel selektora czasu jest otwarty.
tempHournumberAktualna tymczasowa wartość godziny.
tempMinutenumberAktualna tymczasowa wartość minuty.
tempSecondnumberAktualna tymczasowa wartość sekundy.
tempPeriodTimePeriodAktualny okres AM/PM ("AM" lub "PM").

Akcje daty

NazwaTypOpis
handleDateClick(date: Date) => voidObsługuje kliknięcie komórki dnia.
handlePrevMonth() => voidPrzechodzi do poprzedniego miesiąca.
handleNextMonth() => voidPrzechodzi do następnego miesiąca.
handleOpen() => voidOtwiera okienko.
handleClose() => voidZamyka okienko.
handleToggle() => voidPrzełącza widoczność okienka.
handleConfirm() => voidZatwierdza datę i godzinę, a następnie zamyka.
handleCancel() => voidAnuluje i cofa zmiany.
handleClear() => voidCzyści wartość.
handleGoToToday() => voidPrzechodzi do dzisiaj.

Akcje czasu

NazwaTypOpis
handleHourChange(hour: number) => voidAktualizuje godzinę.
handleMinuteChange(minute: number) => voidAktualizuje minutę.
handleSecondChange(second: number) => voidAktualizuje sekundę.
handlePeriodChange(period: TimePeriod) => voidPrzełącza AM/PM.
handleTimePickerOpen() => voidOtwiera podpanel selektora czasu.
handleTimePickerClose() => voidZamyka podpanel selektora czasu.
handleTimePickerConfirm() => voidZatwierdza podpanel selektora czasu.
handleTimePickerCancel() => voidAnuluje podpanel selektora czasu.

Wartości obliczone

NazwaTypOpis
calendarCalendarMonthDane kalendarza dla bieżącego miesiąca.
calendarsCalendarMonth[]Tablica miesięcy kalendarza.
getDayProps(date: Date, referenceMonth?: Date) => DayPropsWłaściwości komórki dnia.
displayValuestringSformatowany ciąg daty i godziny.
timeDisplayValuestringSformatowany ciąg godziny.
hasValuebooleanCzy wartość jest zatwierdzona.
canConfirmbooleanCzy zatwierdzenie jest prawidłowe.
containerRefRefObject<HTMLDivElement | null>Referencja do kontenera.
popupRefRefObject<HTMLDivElement | null>Referencja do okienka.
timePickerRefRefObject<HTMLDivElement | null>Referencja do podpanelu selektora czasu.
focusedDateDate | nullData zaznaczona za pomocą klawiatury.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidObsługa klawiatury.
resolvedTimeConfigRequired<TimeConfig>Rozwiązana konfiguracja czasu z wypełnionymi wartościami domyślnymi.
yearsnumber[]Lata dla trybu listy rozwijanej.
monthsnumber[]Miesiące dla trybu listy rozwijanej.
handleYearSelect(year: number, calendarIndex?: number) => voidUstawia rok.
handleMonthSelect(month: number, calendarIndex?: number) => voidUstawia miesiąc.

Kluczowe zachowania

Konfiguracja czasu

Opcja time akceptuje obiekt 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

W przypadku selektorów daty i godziny, shouldCloseOnSelect jest wyzwalane tylko przy kliknięciach na presety, a nie na daty. Dzieje się tak, ponieważ użytkownik musi jeszcze ustawić godzinę po wybraniu daty.

resolvedTimeConfig

Zwracana wartość resolvedTimeConfig zawiera w pełni rozwiązaną konfigurację czasu ze wszystkimi wypełnionymi wartościami domyślnymi. Użyj jej podczas budowania komponentów interfejsu użytkownika związanych z czasem, aby uniknąć ponownego obliczania wartości domyślnych.