useDateTimePicker

Hook để chọn ngày và giờ kết hợp. Mở rộng useDatePicker với trạng thái thời gian (giờ, phút, giây, buổi) và một bộ chọn thời gian lồng nhau.

Import

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

Cách sử dụng

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}>
{/* Lịch (giống như 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>
{/* ...lưới lịch... */}
{/* Hiển thị thời gian */}
<div>
<span>Time: {picker.timeDisplayValue}</span>
</div>
{/* Điều khiển thời gian */}
<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>
);
}

Tùy chọn

Tùy chọnKiểuMặc địnhMô tả
valueDate | nullBắt buộc. Giá trị ngày-giờ hiện tại.
onChange(dateTime: Date | null) => voidBắt buộc. Được gọi khi ngày-giờ thay đổi.
timeTimeConfig{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }Cấu hình bộ chọn thời gian.
minDateDateNgày có thể chọn sớm nhất.
maxDateDateNgày có thể chọn muộn nhất.
localePartial<Locale>DEFAULT_LOCALEGhi đè các chuỗi bản địa hóa.
initialMonthDateTháng ban đầu để hiển thị.
sizeDatePickerSizeTruyền qua cho UI.
weekStartsOnWeekDay"sunday"Ngày đầu tiên của tuần.
isDateUnavailable(date: Date) => booleanHàm tùy chỉnh để vô hiệu hóa các ngày cụ thể.
displayFormatstringChuỗi định dạng tùy chỉnh cho giá trị hiển thị.
openbooleanTrạng thái mở được kiểm soát.
initialOpenbooleanfalseTrạng thái mở ban đầu.
onOpenChange(open: boolean) => voidCallback khi trạng thái mở thay đổi.
requiredbooleanfalseKhi là true, handleClear không làm gì cả.
todayDatenew Date()Ghi đè ngày hôm nay.
onMonthChange(month: Date) => voidCallback khi tháng thay đổi.
disablePastbooleanfalseVô hiệu hóa các ngày trong quá khứ.
disableFuturebooleanfalseVô hiệu hóa các ngày trong tương lai.
showOutsideDaysbooleanfalseHiển thị các ngày của tháng liền kề.
highlightDatesDate[]Các ngày cần làm nổi bật.
shouldCloseOnSelectbooleanfalseĐối với bộ chọn ngày-giờ, chỉ áp dụng cho các lần nhấp vào cài đặt trước, không áp dụng cho các lần nhấp vào ngày.
numberOfMonthsnumber1Số lượng tháng lịch.
captionLayoutCaptionLayout"buttons"Chế độ bố cục tiêu đề.
fromYearnumbercurrent year - 100Năm bắt đầu cho danh sách thả xuống.
toYearnumbercurrent year + 10Năm kết thúc cho danh sách thả xuống.

Giá trị trả về

Trạng thái Ngày

TênKiểuMô tả
isOpenbooleanPopup có đang mở hay không.
tempDateDate | nullNgày được chọn tạm thời.
currentMonthDateTháng đang được hiển thị.
localeLocaleĐối tượng bản địa hóa đã được giải quyết.

Trạng thái Thời gian

TênKiểuMô tả
isTimePickerOpenbooleanBảng phụ của bộ chọn thời gian có đang mở hay không.
tempHournumberGiá trị giờ tạm thời hiện tại.
tempMinutenumberGiá trị phút tạm thời hiện tại.
tempSecondnumberGiá trị giây tạm thời hiện tại.
tempPeriodTimePeriodBuổi AM/PM hiện tại ("AM" hoặc "PM").

Hành động Ngày

TênKiểuMô tả
handleDateClick(date: Date) => voidXử lý nhấp vào ô ngày.
handlePrevMonth() => voidĐiều hướng đến tháng trước.
handleNextMonth() => voidĐiều hướng đến tháng sau.
handleOpen() => voidMở popup.
handleClose() => voidĐóng popup.
handleToggle() => voidChuyển đổi trạng thái popup.
handleConfirm() => voidXác nhận ngày + giờ và đóng.
handleCancel() => voidHủy và hoàn tác.
handleClear() => voidXóa giá trị.
handleGoToToday() => voidĐiều hướng đến hôm nay.

Hành động Thời gian

TênKiểuMô tả
handleHourChange(hour: number) => voidCập nhật giờ.
handleMinuteChange(minute: number) => voidCập nhật phút.
handleSecondChange(second: number) => voidCập nhật giây.
handlePeriodChange(period: TimePeriod) => voidChuyển đổi AM/PM.
handleTimePickerOpen() => voidMở bảng phụ của bộ chọn thời gian.
handleTimePickerClose() => voidĐóng bảng phụ của bộ chọn thời gian.
handleTimePickerConfirm() => voidXác nhận bảng phụ của bộ chọn thời gian.
handleTimePickerCancel() => voidHủy bảng phụ của bộ chọn thời gian.

Giá trị được tính toán

TênKiểuMô tả
calendarCalendarMonthDữ liệu lịch cho tháng hiện tại.
calendarsCalendarMonth[]Mảng các tháng lịch.
getDayProps(date: Date, referenceMonth?: Date) => DayPropsProps của ô ngày.
displayValuestringChuỗi ngày-giờ đã định dạng.
timeDisplayValuestringChuỗi thời gian đã định dạng.
hasValuebooleanGiá trị đã được xác nhận hay chưa.
canConfirmbooleanViệc xác nhận có hợp lệ hay không.
containerRefRefObject<HTMLDivElement | null>Ref của container.
popupRefRefObject<HTMLDivElement | null>Ref của popup.
timePickerRefRefObject<HTMLDivElement | null>Ref của bảng phụ bộ chọn thời gian.
focusedDateDate | nullNgày được tập trung bằng bàn phím.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidTrình xử lý bàn phím.
resolvedTimeConfigRequired<TimeConfig>Cấu hình thời gian đã được giải quyết với các giá trị mặc định được điền vào.
yearsnumber[]Các năm cho chế độ thả xuống.
monthsnumber[]Các tháng cho chế độ thả xuống.
handleYearSelect(year: number, calendarIndex?: number) => voidĐặt năm.
handleMonthSelect(month: number, calendarIndex?: number) => voidĐặt tháng.

Các hành vi chính

Cấu hình Thời gian

Tùy chọn time chấp nhận một đối tượng 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

Đối với bộ chọn ngày-giờ, shouldCloseOnSelect chỉ kích hoạt khi nhấp vào các giá trị đặt trước, không phải khi nhấp vào ngày. Điều này là do người dùng vẫn cần đặt thời gian sau khi chọn một ngày.

resolvedTimeConfig

Giá trị trả về resolvedTimeConfig chứa cấu hình thời gian đã được giải quyết hoàn chỉnh với tất cả các giá trị mặc định được điền vào. Sử dụng giá trị này khi xây dựng các thành phần UI liên quan đến thời gian để tránh tính toán lại các giá trị mặc định.