useTimePicker

Hook cấp thấp cho bộ chọn thời gian kiểu bánh xe cuộn. Quản lý việc chọn giờ/phút/giây dựa trên cuộn với hành vi snap. Hook này thường được sử dụng nội bộ bởi giao diện bảng điều khiển thời gian, nhưng có thể được sử dụng trực tiếp cho các triển khai bộ chọn thời gian tùy chỉnh.

Import

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

Usage

import { useState } from "react";
import { useTimePicker } from "react-date-range-picker-headless";
function MyTimePicker() {
const [hour, setHour] = useState(12);
const [minute, setMinute] = useState(0);
const picker = useTimePicker({
hour,
minute,
onHourChange: setHour,
onMinuteChange: setMinute,
precision: "minute",
hourFormat: "24",
minuteStep: 5,
});
return (
<div style={{ display: "flex", gap: 8 }}>
{/* Hour column */}
<div
ref={picker.hourListRef}
onScroll={picker.handleHourScroll}
style={{ height: picker.itemHeight * 5, overflow: "auto" }}
>
{picker.hours.map((h) => (
<div
key={h}
onClick={() => picker.handleHourClick(h)}
style={{
height: picker.itemHeight,
fontWeight: h === hour ? "bold" : "normal",
}}
>
{String(h).padStart(2, "0")}
</div>
))}
</div>
{/* Minute column */}
{picker.showMinutes && (
<div
ref={picker.minuteListRef}
onScroll={picker.handleMinuteScroll}
style={{ height: picker.itemHeight * 5, overflow: "auto" }}
>
{picker.minutes.map((m) => (
<div
key={m}
onClick={() => picker.handleMinuteClick(m)}
style={{
height: picker.itemHeight,
fontWeight: m === minute ? "bold" : "normal",
}}
>
{String(m).padStart(2, "0")}
</div>
))}
</div>
)}
{/* Period toggle (12-hour mode) */}
{picker.is12Hour && <button onClick={picker.handlePeriodToggle}>{picker.period}</button>}
</div>
);
}

Tùy chọn

Tùy chọnKiểuMặc địnhMô tả
hournumberBắt buộc. Giờ hiện tại. Chế độ 24h: 0-23, chế độ 12h: 1-12.
minutenumberBắt buộc. Phút hiện tại.
secondnumberGiây hiện tại.
periodTimePeriodBuổi AM/PM hiện tại (bắt buộc cho chế độ 12h).
onHourChange(hour: number) => voidBắt buộc. Trình xử lý thay đổi giờ.
onMinuteChange(minute: number) => voidBắt buộc. Trình xử lý thay đổi phút.
onSecondChange(second: number) => voidTrình xử lý thay đổi giây.
onPeriodChange(period: TimePeriod) => voidTrình xử lý thay đổi AM/PM.
precisionTimePrecision"minute"Độ chính xác thời gian: "hour", "minute", hoặc "second".
hourFormatHourFormat"24"Định dạng giờ "12" hoặc "24".
minuteStepMinuteStep5Bước tăng phút.
secondStepSecondStep1Bước tăng giây.
itemHeightnumber32Chiều cao (tính bằng px) của mỗi mục cuộn.

Giá trị trả về

TênKiểuMô tả
hoursnumber[]Mảng các giá trị giờ. 24h: [0..23], 12h: [1..12].
minutesnumber[]Mảng các giá trị phút dựa trên minuteStep (ví dụ: [0, 5, 10, ...]).
secondsnumber[]Mảng các giá trị giây dựa trên secondStep.
hourIndexnumberChỉ số của giờ hiện tại trong mảng hours.
minuteIndexnumberChỉ số của phút hiện tại trong mảng minutes.
secondIndexnumberChỉ số của giây hiện tại trong mảng seconds.
showMinutesbooleanLiệu cột phút có nên được hiển thị không (độ chính xác là "minute" hoặc "second").
showSecondsbooleanLiệu cột giây có nên được hiển thị không (độ chính xác là "second").
is12HourbooleanLiệu có đang sử dụng định dạng 12 giờ hay không.
periodTimePeriodBuổi AM/PM hiện tại.
handlePeriodToggle() => voidChuyển đổi giữa AM và PM.
hourListRefRefObject<HTMLDivElement | null>Ref cho vùng chứa cuộn giờ.
minuteListRefRefObject<HTMLDivElement | null>Ref cho vùng chứa cuộn phút.
secondListRefRefObject<HTMLDivElement | null>Ref cho vùng chứa cuộn giây.
handleHourScroll() => voidTrình xử lý cuộn cho cột giờ — snap vào mục gần nhất.
handleMinuteScroll() => voidTrình xử lý cuộn cho cột phút.
handleSecondScroll() => voidTrình xử lý cuộn cho cột giây.
handleHourClick(hour: number) => voidChọn trực tiếp một giá trị giờ.
handleMinuteClick(minute: number) => voidChọn trực tiếp một giá trị phút.
handleSecondClick(second: number) => voidChọn trực tiếp một giá trị giây.
scrollToValues() => voidCuộn tất cả các cột đến giá trị hiện tại của chúng một cách có lập trình.
itemHeightnumberChiều cao mục đã được xác định (px).
centerIndexnumberChỉ số của mục hiển thị ở giữa (dành cho tính toán scroll snap).

Các hành vi chính

Scroll Snap

Các vùng chứa cuộn sử dụng hành vi snap: khi người dùng cuộn và thả ra, hook sẽ tự động snap vào giá trị hợp lệ gần nhất và kích hoạt callback thay đổi tương ứng.

Chế độ 12 giờ

Khi hourFormat"12", mảng hours chứa [1, 2, ..., 12] thay vì [0, 1, ..., 23]. Các giá trị trả về periodhandlePeriodToggle quản lý trạng thái AM/PM.

Giá trị bước nhảy

Phút và giây được lọc theo các giá trị bước nhảy tương ứng của chúng. Ví dụ, minuteStep: 15 sẽ tạo ra [0, 15, 30, 45].

scrollToValues

Gọi scrollToValues() sau khi mount hoặc khi thay đổi giá trị theo chương trình để đảm bảo các vùng chứa cuộn được định vị chính xác.