Yugen UI

TimePicker

TimePicker là ô nhập kiểu combobox để chọn giờ trong danh sách hoặc gõ tự do.

Danh sách giờ cách nhau increment phút giữa startHour và endHour; gõ "9", "930", "9h30", "21:15" hay "9:30 PM" rồi Enter / rời ô để xác nhận; trong lúc gõ, danh sách đánh dấu giờ gần nhất. onTimeChange(event, { selectedTime, selectedTimeText, errorType }) báo lỗi "invalid-input" / "out-of-start-bound" / "out-of-end-bound" để hiển thị qua <Field>. Chu kỳ giờ mặc định theo locale (vi-VN → 24 giờ). Dùng chung vỏ ô nhập (fieldAppearanceClass) và option của Combobox.
Gõ 9, 930, 9:30 PM, 21:15 hoặc chọn trong danh sách
Chưa chọn giờ

Import

Cài từ npm, chép mã nguồn vào dự án bằng @yugen-ui/cli hoặc shadcn CLI, hoặc import thẳng khi làm việc trong repo này.

TSX
// npm install yugen-uiimport { TimePicker, Field, formatTime, parseTimeString, getTimesInRange } from "yugen-ui";

Biến thể

Mỗi ô là một mẫu độc lập: hover để Copy, hoặc bấm Code để xem mã nguồn.

Giờ làm việc, bước 15 phút

startHour / endHour (endHour không gồm) giới hạn danh sách; gõ "7" hay "19:00" báo lỗi ngoài khoảng.

Từ 13:30 đến 17:00

minTime / maxTime & dateAnchor

Chỉ so phần giờ; giờ trả về gắn vào ngày của dateAnchor.

12 giờ (SA / CH, AM / PM)

hourCycle="h12" dùng nhãn buổi của locale; locale="en-US" mặc định 12 giờ.

Kích thước, appearance & disabled

small 24px, medium 32px, large 40px; appearance như Input / Combobox.

Cách dùng

Nên
  • Bọc trong <Field> và hiển thị thông báo theo errorType của onTimeChange.
  • Chọn increment phù hợp (15 / 30 phút) để danh sách ngắn gọn — giờ lẻ vẫn gõ được.
  • Đặt startHour / endHour hoặc minTime / maxTime thay vì kiểm tra thủ công sau khi chọn.
Không nên
  • Không dùng TimePicker cho khoảng thời lượng ("2 giờ 30 phút") — dùng SpinButton.
  • Không tự định dạng giờ khác nhau giữa các màn hình — dùng hourCycle / locale.

Props

Prop · KiểuMặc địnhMô tả
value / defaultValueDate | nullMặc định: —Giờ đã chọn (controlled / uncontrolled).
onTimeChange(event, { selectedTime, selectedTimeText, errorType? }) => voidMặc định: —Chọn option hoặc xác nhận chữ gõ (Enter / rời ô).
onValueChange(value: Date | null) => voidMặc định: —Gọi khi giờ đã chọn đổi; null khi xoá trống hoặc chữ gõ không hợp lệ.
incrementnumberMặc định: 30Bước giữa các option (phút).
startHour / endHournumberMặc định: 0 / 24Giờ đầu (gồm) và giờ cuối (không gồm).
minTime / maxTimeDateMặc định: —Giờ sớm / muộn nhất (gồm, chỉ so phần giờ).
hourCycle"h23" | "h12"Mặc định: theo locale24 giờ hoặc 12 giờ có nhãn buổi.
localestringMặc định: "vi-VN"Quyết định hourCycle mặc định và nhãn SA/CH, AM/PM.
dateAnchorDateMặc định: ngày của value / hôm nayNgày gắn vào giờ trả về.
formatDateToTimeString(date: Date) => stringMặc định: —Định dạng hiển thị tuỳ biến.
appearance"outline" | "underline" | "filled-darker" | "filled-lighter"Mặc định: "outline"Kiểu vỏ ô nhập.
size"small" | "medium" | "large"Mặc định: "medium"Chiều cao 24 / 32 / 40px.
disabled / required / id / aria-*—Mặc định: —Field tự truyền khi bọc trong <Field>.
formatTime / parseTimeString / getTimesInRange / getTimeBoundsErrorhelperMặc định: —Hàm thuần để định dạng, phân tích chữ gõ, sinh danh sách giờ và kiểm tra khoảng.

Messages

Chữ có sẵn của component: nhãn, aria-label, thông báo cho trình đọc màn hình.

Mặc định là tiếng Anh. Đổi qua prop messages của YugenProvider, theo namespace bên dưới; messagesVi chứa bản tiếng Việt. Xem Ngôn ngữ giao diện.

messages.timePicker

Khoá · KiểuMặc định (tiếng Anh)messagesVi
placeholderstring

Placeholder của ô nhập.

Mặc định (tiếng Anh)"Select a time…"messagesVi"Chọn giờ…"
noOptionsstring

Nội dung khi khoảng giờ rỗng.

Mặc định (tiếng Anh)"No matching times"messagesVi"Không có giờ phù hợp"
listLabelstring

aria-label của danh sách giờ khi ô nhập không có nhãn riêng.

Mặc định (tiếng Anh)"Select a time"messagesVi"Chọn giờ"
closeListstring

aria-label nút mũi tên khi danh sách đang mở.

Mặc định (tiếng Anh)"Close time list"messagesVi"Đóng danh sách giờ"
openListstring

aria-label nút mũi tên khi danh sách đang đóng.

Mặc định (tiếng Anh)"Open time list"messagesVi"Mở danh sách giờ"