انتخابگر تاریخ (Date Picker)
کامپوننت انتخابگر تاریخ با پشتیبانی از تقویم شمسی (جلالی) و انتخاب بازه.
نصب (Installation)
1npx @quark-lab/rad-ui add date-pickerکامپوننتهای Calendar، Popover و Button بهصورت خودکار بهعنوان وابستگی نصب میشوند.
برای استفاده از مثال پیشتنظیمها، کامپوننت Select را جداگانه نصب کنید: npx @quark-lab/rad-ui add select
نمونهها (Examples)
استفاده پایه (Basic)
انتخاب تکتاریخ با پاپاور و تقویم شمسی.
مشاهده کد
1"use client";
2
3import * as React from "react";
4import { DatePicker } from "@/components/ui/date-picker";
5
6export default function DatePickerDemo() {
7 const [date, setDate] = React.useState<Date>();
8
9 return (
10 <DatePicker
11 date={date}
12 onDateChange={setDate}
13 placeholder="انتخاب تاریخ"
14 />
15 );
16}انتخاب بازه تاریخ (Range Picker)
انتخاب بازه تاریخی با نمایش دو ماه.
مشاهده کد
1"use client";
2
3import * as React from "react";
4import { addDays } from "date-fns";
5import type { DateRange } from "react-day-picker";
6import { DateRangePicker } from "@/components/ui/date-picker";
7
8export default function DateRangePickerDemo() {
9 const [dateRange, setDateRange] = React.useState<DateRange | undefined>({
10 from: new Date(),
11 to: addDays(new Date(), 7),
12 });
13
14 return (
15 <DateRangePicker
16 dateRange={dateRange}
17 onDateRangeChange={setDateRange}
18 placeholder="انتخاب بازه تاریخ"
19 />
20 );
21}با پیشتنظیمها (With Presets)
انتخاب سریع تاریخ با پیشتنظیمهای آماده مانند امروز، فردا و هفته آینده.
مشاهده کد
1"use client";
2
3import * as React from "react";
4import { addDays } from "date-fns";
5import { Calendar as CalendarIcon } from "lucide-react";
6import { cn } from "@/lib/utils";
7import { Button } from "@/components/ui/button";
8import { Calendar } from "@/components/ui/calendar";
9import {
10 Popover,
11 PopoverContent,
12 PopoverTrigger,
13} from "@/components/ui/popover";
14import {
15 Select,
16 SelectContent,
17 SelectItem,
18 SelectTrigger,
19 SelectValue,
20} from "@/components/ui/select";
21
22export default function DatePickerWithPresets() {
23 const [date, setDate] = React.useState<Date>();
24
25 return (
26 <Popover>
27 <PopoverTrigger asChild>
28 <Button
29 variant="outline"
30 className={cn(
31 "w-[280px] justify-start text-start font-normal",
32 !date && "text-muted-foreground"
33 )}
34 >
35 <CalendarIcon className="me-2 h-4 w-4" />
36 {date
37 ? date.toLocaleDateString("fa-IR")
38 : "انتخاب تاریخ"}
39 </Button>
40 </PopoverTrigger>
41 <PopoverContent className="flex w-auto flex-col gap-2 p-2">
42 <Select
43 onValueChange={(value) =>
44 setDate(addDays(new Date(), parseInt(value)))
45 }
46 >
47 <SelectTrigger>
48 <SelectValue placeholder="انتخاب سریع" />
49 </SelectTrigger>
50 <SelectContent position="popper">
51 <SelectItem value="0">امروز</SelectItem>
52 <SelectItem value="1">فردا</SelectItem>
53 <SelectItem value="3">سه روز بعد</SelectItem>
54 <SelectItem value="7">هفته آینده</SelectItem>
55 </SelectContent>
56 </Select>
57 <div className="rounded-md border border-border">
58 <Calendar mode="single" selected={date} onSelect={setDate} />
59 </div>
60 </PopoverContent>
61 </Popover>
62 );
63}
64
65// نکته: برای این مثال به کامپوننت Select نیاز دارید.
66// npx @quark-lab/rad-ui add selectمرجع API (API Reference)
DatePicker
پراپهای کامپوننت انتخابگر تاریخ.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
date | Date | undefined | undefined | تاریخ انتخابشده |
onDateChange | (date: Date | undefined) => void | - | تابع رویداد تغییر تاریخ |
placeholder | string | "انتخاب تاریخ" | متن جایگزین وقتی تاریخی انتخاب نشده |
disabled | boolean | false | غیرفعال کردن انتخابگر تاریخ |
className | string | - | کلاسهای CSS سفارشی برای دکمه تریگر |
calendarClassName | string | - | کلاسهای CSS سفارشی برای تقویم |
DateRangePicker
پراپهای کامپوننت انتخابگر بازه تاریخ.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
dateRange | DateRange | undefined | undefined | بازه تاریخی انتخابشده |
onDateRangeChange | (range: DateRange | undefined) => void | - | تابع رویداد تغییر بازه تاریخ |
placeholder | string | "انتخاب بازه تاریخ" | متن جایگزین وقتی بازهای انتخاب نشده |
numberOfMonths | number | 2 | تعداد ماههای نمایشدادهشده |
disabled | boolean | false | غیرفعال کردن انتخابگر بازه تاریخ |
className | string | - | کلاسهای CSS سفارشی برای دکمه تریگر |
دسترسیپذیری (Accessibility)
کیبورد (Keyboard)
EnterیاSpace- باز کردن پاپاورEscape- بستن پاپاور- کلیدهای جهتدار - ناوبری در تقویم
فوکوس (Focus)
پس از باز شدن پاپاور، فوکوس به تقویم منتقل میشود. با بستن پاپاور، فوکوس به دکمه تریگر بازمیگردد.
بهترین شیوهها (Best Practices)
نمایش تاریخ (Date Display)
کامپوننت بهصورت پیشفرض تاریخ را با فرمت شمسی نمایش میدهد. از toLocaleDateString("fa-IR") استفاده میشود.
پیشتنظیمها (Presets)
برای تجربه کاربری بهتر، پیشتنظیمهایی مانند «امروز»، «فردا» و «هفته آینده» اضافه کنید. برای این مثال به کامپوننت Select نیاز دارید.
متن جایگزین (Placeholder)
همیشه یک متن جایگزین فارسی مانند «انتخاب تاریخ» نمایش دهید تا کاربر متوجه عملکرد دکمه شود.
نحوه استفاده (Usage)
استفاده ساده (Simple Usage)
سادهترین حالت استفاده از انتخابگر تاریخ.
مشاهده کد
1"use client";
2
3import * as React from "react";
4import { DatePicker } from "@/components/ui/date-picker";
5
6export default function DatePickerUsage() {
7 const [date, setDate] = React.useState<Date>();
8
9 return (
10 <DatePicker
11 date={date}
12 onDateChange={setDate}
13 placeholder="انتخاب تاریخ"
14 />
15 );
16}مثالهای پیشرفته (Advanced Examples)
با حالت تاریختولد (Date of Birth)
استفاده از منوی کشویی ماه و سال برای انتخاب سریعتر تاریخ تولد.
مشاهده کد
1import { DatePicker } from "@/components/ui/date-picker";
2
3<DatePicker
4 date={date}
5 onDateChange={setDate}
6 placeholder="تاریخ تولد"
7 captionLayout="dropdown"
8/>فرمت سفارشی (Custom Format)
نمایش تاریخ با فرمت سفارشی.
مشاهده کد
1const formatDate = (date: Date) => {
2 return new Intl.DateTimeFormat("fa-IR", {
3 year: "numeric",
4 month: "long",
5 day: "numeric",
6 }).format(date);
7};
8
9// نمونه خروجی: ۱۰ فروردین ۱۴۰۵