Component
Calendar
Lưới một tháng để chọn một ngày hoặc một khoảng ngày, inline, cho bề mặt đặt chỗ hoặc xem ngày còn trống, nơi ngày là trọng tâm của màn hình. Trong form, dùng DatePicker, vì DatePicker mở lưới này trong một popover.
Xem trước
import { Calendar } from "@/components/ui/calendar"
<Calendar />Cách dùng
Khi nào dùng
- Cả một tháng trên trang khi ngày là trọng tâm của màn hình, chẳng hạn lịch còn trống hoặc đặt chỗ.
- Giới hạn lựa chọn vào các ngày thật, với các ngày disabled hoặc một ngày tối thiểu và tối đa.
- Nhảy tới một tháng hoặc năm xa bằng các select caption, chẳng hạn ngày sinh.
Khi nào không dùng
- Chọn một ngày trong form, cạnh các field khác. Dùng DatePicker.
- Hiện sự kiện theo ngày của chúng. Đây là bộ chọn, không phải lịch trình.
Biến thể
weekStartsOn
Ngày đầu tuần: 0 là Chủ nhật hoặc 1 là Thứ hai. Theo locale khi không được đặt.
import { Calendar } from "@/components/ui/calendar"
<Calendar />
<Calendar weekStartsOn={1} />captionLayout
Cách caption chuyển giữa các tháng. dropdown là một select tháng và một select năm. dropdown-months và dropdown-years hiện một select và để phần kia là chữ. label là tháng và năm dưới dạng chữ. Với select năm và không có minDate hoặc maxDate, các năm chạy từ 100 năm trước hôm nay đến 100 năm sau. minDate và maxDate giới hạn các select và các button tháng trước, tháng sau.
import { Calendar } from "@/components/ui/calendar"
<Calendar captionLayout="label" />
<Calendar />
<Calendar captionLayout="dropdown-months" />
<Calendar captionLayout="dropdown-years" />Ví dụ
Trên trang
Calendar trên trang, khi ngày là trọng tâm của màn hình.
import { Calendar } from "@/components/ui/calendar"
<Calendar weekStartsOn={1} />Một khoảng
Hai tháng cho một khoảng bắc qua một tháng. Cú nhấn đầu đặt ngày bắt đầu, cú thứ hai đặt ngày kết thúc.
import { Calendar } from "@/components/ui/calendar"
<Calendar mode="range" numberOfMonths={2} />Caption chữ
Tháng và năm dưới dạng chữ, khi các button tháng trước và tháng sau là đủ.
import { Calendar } from "@/components/ui/calendar"
<Calendar captionLayout="label" />Nên và không nên
Nên
- Dùng Calendar inline khi ngày là toàn bộ mục đích của trang, chẳng hạn bề mặt đặt chỗ hoặc lịch còn trống.
- Dùng DatePicker trong form, cạnh các field Input.
- Tắt những ngày không bao giờ chọn được, chẳng hạn ngày đã qua hoặc ngày đóng cửa, bên cạnh minDate và maxDate.
- Dùng hai tháng cho các khoảng thường bắc qua một tháng.
- Giữ các select tháng và năm khi ngày có thể xa tháng đang hiện, chẳng hạn ngày sinh. Đặt minDate và maxDate để các select chỉ đưa lựa chọn thật.
Không nên
- Đừng dùng range cho một ngày; giữ mode single.
- Đừng đặt Calendar trong popover riêng của bạn cho một field của form; DatePicker đã làm việc đó, kèm xử lý focus.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| mode | enum | single | range | single | single chọn một Date; range chọn ngày bắt đầu và ngày kết thúc ({ from, to }). Sau một khoảng hoàn chỉnh, cú nhấn tiếp theo bắt đầu khoảng mới; nhấn vào ngày của khoảng một ngày sẽ xóa nó. Một khoảng không bao giờ bắc qua một ngày disabled. |
| value | string | - | - | Date đã chọn, hoặc ở mode range thì khoảng đã chọn ({ from, to }), khi bạn điều khiển nó. Một undefined tường minh xóa lựa chọn; bỏ value thì dùng state nội bộ. Ghép với onValueChange. |
| defaultValue | string | - | - | Date, hoặc ở mode range thì khoảng, được chọn ở lần render đầu, khi bạn không điều khiển nó. |
| onValueChange | function | - | - | Được gọi với Date đã chọn, hoặc undefined khi người dùng bỏ chọn. Ở mode range nó được gọi mỗi lần nhấn: { from } sau lần đầu, { from, to } sau lần thứ hai, undefined khi một khoảng một ngày bị xóa. |
| disabled | boolean | - | false | true tắt mọi ngày; một function nhận một Date và tắt từng ngày, chẳng hạn cuối tuần hoặc ngày đã qua. |
| minDate | string | - | - | Không ngày nào trước Date này được chọn hoặc điều hướng tới. |
| maxDate | string | - | - | Không ngày nào sau Date này được chọn hoặc điều hướng tới. |
| locale | string | - | - | Một đối tượng date-fns Locale cho tên tháng và tên thứ. Mặc định là enUS. |
| weekStartsOn | enum | 0 | 1 | - | Ngày đầu tuần: 0 là Chủ nhật hoặc 1 là Thứ hai. Theo locale khi không được đặt. |
| numberOfMonths | number | - | 1 | Số tháng hiện cùng lúc, cạnh nhau từ sm và xếp chồng khi dưới sm. Dùng hai tháng cho các khoảng thường bắc qua một tháng. |
| captionLayout | enum | label | dropdown | dropdown-months | dropdown-years | dropdown | Cách caption chuyển giữa các tháng. dropdown là một select tháng và một select năm. dropdown-months và dropdown-years hiện một select và để phần kia là chữ. label là tháng và năm dưới dạng chữ. Với select năm và không có minDate hoặc maxDate, các năm chạy từ 100 năm trước hôm nay đến 100 năm sau. minDate và maxDate giới hạn các select và các button tháng trước, tháng sau. |
| rangeStartLabel | string | - | start of range | Mode range. Được thêm vào tên truy cập của ngày bắt đầu; dịch nó theo locale. |
| rangeEndLabel | string | - | end of range | Mode range. Được thêm vào tên truy cập của ngày kết thúc; dịch nó theo locale. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Khung tháng, padding md. Khi numberOfMonths lớn hơn 1, các tháng nằm cạnh nhau từ sm và xếp chồng khi dưới sm. |
| label | Hàng caption, căn giữa giữa các button điều hướng. Mặc định là một select tháng và một select năm, chữ md medium. captionLayout label hiện tháng và năm dưới dạng chữ. |
| icon | Tabler ChevronLeft và CaretRight, 16px, secondary, trong các button tháng trước và tháng sau. |
| head | Một header cột thứ, chữ xs medium secondary. |
| item | Một ngày: ô và button của nó. Button cao bằng control md, vuông; ô mang nền được chọn. Hôm nay có outline bo tròn theo màu chữ hiện tại của button, tách khỏi focus ring bàn phím bên ngoài. Ở mode range, hai đầu lấy accent solid, bo tròn ở phía ngoài và vuông về phía dải. |
| range | Một ngày nằm giữa hai đầu của khoảng; các ô tạo thành một dải. |
Khả năng truy cập
Role: grid
| Phím | Hành động |
|---|---|
| Space, Enter | Chọn ngày đang focus. |
| ArrowDown, ArrowUp, ArrowLeft, ArrowRight | Chuyển focus tới ngày muộn hơn hoặc sớm hơn một tuần, hoặc ngày trước hoặc sau, bỏ qua các ngày disabled. |
| Home, End | Chuyển focus tới ngày đầu hoặc ngày cuối của tuần. |
| PageUp, PageDown | Chuyển focus tới cùng ngày đó ở tháng trước hoặc tháng sau. Shift nhảy theo năm. |
| ArrowUp, ArrowDown | Trên select tháng hoặc năm, chuyển qua các lựa chọn của nó và lưới đi theo. |
- Mỗi lần chỉ một button ngày nhận tab; các phím mũi tên chuyển focus trong lưới, theo mẫu grid của WAI-ARIA APG. Với nhiều tháng, focus đi từ tháng này sang tháng kế.
- Ô của ngày đã chọn có aria-selected, các ngày disabled có button disabled native, và caption là một live region polite, nên trình đọc màn hình nghe tháng mà nó dừng lại.
- Ở mode range, mọi ngày trong khoảng có aria-selected. Các button đầu và cuối thêm rangeStartLabel và rangeEndLabel ("start of range", "end of range") vào tên truy cập; khoảng một ngày nhận cả hai. Hai đầu khác phần giữa ở nền và hình, và trigger của DatePicker hoặc caption nêu các ngày, nên trạng thái không bao giờ chỉ dựa vào màu.
- Hàng header thứ là một hàng thật gồm các header cột.
- Lật bằng button tháng trước và tháng sau thì tháng mới trượt vào từ phía của nó; lật từ bàn phím thì đổi ngay, nên chuyển focus theo ngày không bao giờ chờ chuyển động.
- Các select tháng và năm nằm trong caption. Mỗi cái có tên truy cập. Đổi một cái thì lưới chuyển, và caption vẫn là live region polite, nên trình đọc màn hình nghe tháng mà nó dừng lại. captionLayout label giữ chữ đó hiện và không có select.
Cài đặt
npx werewolf-ui add calendarChạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.