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 | null—Bắt buộc. Ngày hiện tại được chọn.
onChange(date: Date | null) => void—Bắt buộc. Được gọi khi lựa chọn ngày thay đổi.
minDateDate—Ngày sớm nhất có thể chọn.
maxDateDate—Ngày muộn nhất có thể chọn.
localePartial<Locale>DEFAULT_LOCALEGhi đè các chuỗi ngôn ngữ.
initialMonthDate—Tháng hiển thị ban đầu (mặc định là giá trị hoặc ngày hôm nay).
sizeDatePickerSize—Thô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) => boolean—Hàm tùy chỉnh để vô hiệu hóa các ngày cụ thể.
displayFormatstring—Chuỗi định dạng tùy chỉnh cho giá trị hiển thị (ví dụ: "YYYY/MM/DD").
openboolean—Trạ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) => void—Callback 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 isToday và disablePast/disableFuture.
onMonthChange(month: Date) => void—Callback 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 open và onOpenChange:

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

shouldCloseOnSelect

Khi shouldCloseOnSelect là true, 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 là "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.