انتخابگر تاریخ (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)
dateDate | undefinedundefinedتاریخ انتخاب‌شده
onDateChange(date: Date | undefined) => void-تابع رویداد تغییر تاریخ
placeholderstring"انتخاب تاریخ"متن جایگزین وقتی تاریخی انتخاب نشده
disabledbooleanfalseغیرفعال کردن انتخابگر تاریخ
classNamestring-کلاس‌های CSS سفارشی برای دکمه تریگر
calendarClassNamestring-کلاس‌های CSS سفارشی برای تقویم

DateRangePicker

پراپ‌های کامپوننت انتخابگر بازه تاریخ.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
dateRangeDateRange | undefinedundefinedبازه تاریخی انتخاب‌شده
onDateRangeChange(range: DateRange | undefined) => void-تابع رویداد تغییر بازه تاریخ
placeholderstring"انتخاب بازه تاریخ"متن جایگزین وقتی بازه‌ای انتخاب نشده
numberOfMonthsnumber2تعداد ماه‌های نمایش‌داده‌شده
disabledbooleanfalseغیرفعال کردن انتخابگر بازه تاریخ
classNamestring-کلاس‌های 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)

استفاده از منوی کشویی ماه و سال برای انتخاب سریع‌تر تاریخ تولد.

از captionLayout="dropdown" برای انتخاب سریع ماه و سال استفاده کنید.
مشاهده کد
1import { DatePicker } from "@/components/ui/date-picker";
2
3<DatePicker
4  date={date}
5  onDateChange={setDate}
6  placeholder="تاریخ تولد"
7  captionLayout="dropdown"
8/>

فرمت سفارشی (Custom Format)

نمایش تاریخ با فرمت سفارشی.

از Intl.DateTimeFormat برای فرمت‌بندی سفارشی تاریخ شمسی استفاده کنید.
مشاهده کد
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// نمونه خروجی: ۱۰ فروردین ۱۴۰۵