useDatePicker

Hook cốt lõi để chọn một ngày duy nhất. Quản lý trạng thái lịch, hành vi mở/đóng, điều hướng bằng bàn phím và định dạng ngày.

Import

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

Usage

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>
);
}

Tùy chọn

Tùy chọnKiểuMặc địnhMô tả
valueDate | nullBắt buộc. Ngày hiện tại được chọn.
onChange(date: Date | null) => voidBắt buộc. Được gọi khi lựa chọn ngày thay đổi.
minDateDateNgày sớm nhất có thể chọn.
maxDateDateNgày muộn nhất có thể chọn.
localePartial<Locale>DEFAULT_LOCALEGhi đè các chuỗi ngôn ngữ.
initialMonthDateTháng hiển thị ban đầu (mặc định là giá trị hoặc ngày hôm nay).
sizeDatePickerSizeThông số giao diện cho các component đã được tạo kiểu. Các hook headless sẽ bỏ qua điều này.
weekStartsOnWeekDay"sunday"Ngày đầu tiên trong 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ị (ví dụ: "YYYY/MM/DD").
openbooleanTrạng thái mở được kiểm soát. Khi được cung cấp, hook không quản lý trạng thái mở bên trong.
initialOpenbooleanfalseTrạng thái mở ban đầu (chế độ không kiểm soát).
onOpenChange(open: boolean) => voidCallback khi trạng thái mở thay đổi. Hoạt động với cả chế độ được kiểm soát và không kiểm soát.
requiredbooleanfalseKhi là true, handleClear không thực hiện hành động nào.
todayDatenew Date()Ghi đè ngày hôm nay cho các tính toán isTodaydisablePast/disableFuture.
onMonthChange(month: Date) => voidCallback khi tháng hiển thị thay đổi.
disablePastbooleanfalseVô hiệu hóa tất cả các ngày trước hôm nay.
disableFuturebooleanfalseVô hiệu hóa tất cả các ngày sau hôm nay.
showOutsideDaysbooleanfalseHiển thị các ngày từ các tháng liền kề để lấp đầy lưới 6 tuần.
highlightDatesDate[]Mảng các ngày cần làm nổi bật trong lịch.
shouldCloseOnSelectbooleanfalseTự động xác nhận và đóng khi nhấp vào ngày.
numberOfMonthsnumber1Số tháng hiển thị đồng thời.
captionLayoutCaptionLayout"buttons""buttons" cho mũi tên trước/sau, "dropdown" cho lựa chọn năm/tháng.
fromYearnumbercurrent year - 100Năm bắt đầu cho chế độ dropdown.
toYearnumbercurrent year + 10Năm kết thúc cho chế độ dropdown.

Giá trị trả về

TênKiểuMô tả
isOpenbooleanCho biết popup có đang mở hay không.
tempDateDate | nullNgày được chọn tạm thời (trước khi xác nhận).
currentMonthDateTháng đang được hiển thị.
localeLocaleĐối tượng locale đã được giải quyết với tất cả các chuỗi.
calendarCalendarMonthDữ liệu lịch cho tháng hiện tại (bao gồm month, days, weeks).
calendarsCalendarMonth[]Mảng các tháng lịch (độ dài = numberOfMonths).
getDayProps(date: Date, referenceMonth?: Date) => DayPropsTính toán các cờ cho một ô ngày trong lịch.
displayValuestringChuỗi đã định dạng của giá trị đã xác nhận.
hasValuebooleanCho biết một ngày có đang được xác nhận hay không.
canConfirmbooleanCho biết lựa chọn hiện tại có hợp lệ để xác nhận hay không.
handleDateClick(date: Date) => voidXử lý sự kiện nhấp vào một ô 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 (hủy các thay đổi chưa được xác nhận).
handleToggle() => voidBật/tắt popup.
handleConfirm() => voidXác nhận lựa chọn và đóng.
handleCancel() => voidHủy và hoàn nguyên về giá trị trước đó.
handleClear() => voidXóa giá trị (không thực hiện hành động nào nếu required).
handleGoToToday() => voidĐiều hướng lịch đến tháng của ngày hôm nay.
containerRefRefObject<HTMLDivElement | null>Gắn vào phần tử bao bọc để phát hiện nhấp chuột bên ngoài.
popupRefRefObject<HTMLDivElement | null>Gắn vào phần tử popup.
focusedDateDate | nullNgày đang được tập trung bằng bàn phím.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidTrình xử lý sự kiện bàn phím cho các phím mũi tên, Enter, Escape, Tab.
yearsnumber[]Mảng các năm cho chế độ tiêu đề dropdown.
monthsnumber[]Mảng các chỉ số tháng (0-11) cho chế độ tiêu đề dropdown.
handleYearSelect(year: number, calendarIndex?: number) => voidĐặt năm hiển thị (chế độ dropdown).
handleMonthSelect(month: number, calendarIndex?: number) => voidĐặt tháng hiển thị (chế độ dropdown).

Các hành vi chính

Trạng thái mở được kiểm soát và không kiểm soát

Theo mặc định, hook tự quản lý trạng thái mở/đóng. Để kiểm soát từ bên ngoài, hãy truyền vào openonOpenChange:

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

shouldCloseOnSelect

Khi shouldCloseOnSelecttrue, việc nhấp vào một ngày sẽ ngay lập tức xác nhận và đóng popup, bỏ qua bước xác nhận rõ ràng.

Điều hướng bằng bàn phím

PhímHành động
Mũi tên Lên/Xuống/Trái/PhảiDi chuyển tiêu điểm giữa các ngày
Enter / Phím cáchChọn ngày đang được tập trung
EscapeHủy và đóng
TabDi chuyển tiêu điểm trong popup

Tiêu đề Dropdown

Khi captionLayout"dropdown", phần đầu sẽ hiển thị các dropdown chọn năm và tháng thay vì các nút trước/sau. Sử dụng years, months, handleYearSelect, và handleMonthSelect để hiển thị các dropdown.