انتخابگر بازه تاریخ (Date Range Picker)
کامپوننت انتخاب بازه تاریخ با پشتیبانی از تقویم شمسی و میلادی
معرفی
کامپوننت Date Range Picker برای انتخاب بازه تاریخ (از تاریخ شروع تا تاریخ پایان) استفاده میشود. این کامپوننت از تقویم شمسی (جلالی) و میلادی پشتیبانی میکند و به طور کامل RTL است.
استفاده پایه
import { DateRangePicker } from '@parto-system-design/ui'
import { useState } from 'react'
import { DateRange } from 'react-day-picker'
export default function MyComponent() {
const [dateRange, setDateRange] = useState<DateRange | undefined>()
return (
<DateRangePicker value={dateRange} onChange={setDateRange} label="بازه تاریخ" placeholder="انتخاب بازه تاریخ" />
)
}تقویم شمسی
برای استفاده از تقویم شمسی، prop usePersianCalendar را true قرار دهید:
<DateRangePicker
value={dateRange}
onChange={setDateRange}
label="بازه تاریخ شمسی"
placeholder="انتخاب بازه تاریخ"
usePersianCalendar={true}
/>ویژگیها
تعداد ماهها
میتوانید تعداد ماههای نمایش داده شده را تغییر دهید:
<DateRangePicker numberOfMonths={1} value={dateRange} onChange={setDateRange} />محدودیت تاریخ
میتوانید حداقل و حداکثر تاریخ قابل انتخاب را مشخص کنید:
<DateRangePicker
value={dateRange}
onChange={setDateRange}
minDate={new Date(2024, 0, 1)}
maxDate={new Date(2024, 11, 31)}
/>انتخابگر سال و ماه
برای نمایش dropdown برای انتخاب سال و ماه:
<DateRangePicker
value={dateRange}
onChange={setDateRange}
captionLayout="dropdown"
fromYear={1380}
toYear={1410}
usePersianCalendar={true}
/>نسخه inline (بدون label)
برای استفاده در inline:
import { DateRangePickerInline } from '@parto-system-design/ui'
;<DateRangePickerInline value={dateRange} onChange={setDateRange} placeholder="انتخاب تاریخ" />راهنمای استفاده
بکنید
- از DateRangePicker برای انتخاب بازه تاریخی (شروع و پایان) در فیلترها و فرمها استفاده کنید - از
labelبرای مشخص کردن هدف فیلد استفاده کنید - برای محدود کردن بازه قابل انتخاب، ازminDateوmaxDateاستفاده کنید
نکنید
- برای انتخاب فقط یک تاریخ از DateRangePicker استفاده نکنید — از
DatePickerباmode="single"استفاده کنید - برای دورههای از پیش تعریفشده (هفته اخیر، ماه اخیر) از DateRangePicker استفاده نکنید — ازPeriodSelectorاستفاده کنید - فراموش نکنید که مقادیرDateهمیشه میلادی هستند، حتی وقتی تقویم شمسی فعال است
Props
مثالهای کاربردی
فرم رزرو هتل
export default function HotelBookingForm() {
const [checkInOut, setCheckInOut] = useState<DateRange | undefined>()
return (
<form>
<DateRangePicker
value={checkInOut}
onChange={setCheckInOut}
label="تاریخ ورود و خروج"
placeholder="انتخاب تاریخ"
minDate={new Date()}
numberOfMonths={2}
/>
</form>
)
}فیلتر گزارش با تقویم شمسی
export default function ReportFilter() {
const [reportRange, setReportRange] = useState<DateRange | undefined>()
return (
<div className="flex gap-4">
<DateRangePicker
value={reportRange}
onChange={setReportRange}
label="بازه گزارش"
placeholder="از تاریخ - تا تاریخ"
usePersianCalendar={true}
captionLayout="dropdown"
fromYear={1400}
toYear={1404}
/>
<Button onClick={() => console.log(reportRange)}>مشاهده گزارش</Button>
</div>
)
}نکات مهم
-
تقویم شمسی: هنگام استفاده از
usePersianCalendar={true}, تاریخها به صورت شمسی نمایش داده میشوند اما مقادیرDateهمچنان میلادی هستند. -
بسته شدن خودکار: پس از انتخاب هر دو تاریخ (شروع و پایان), popover به صورت خودکار بسته میشود.
-
RTL: این کامپوننت به طور کامل از RTL پشتیبانی میکند و در محیط راست به چپ به درستی کار میکند.
-
دسترسی: کامپوننت از استانداردهای دسترسی پیروی میکند و با کیبورد قابل استفاده است.
توابع کمکی
برای کار با تاریخهای شمسی، میتوانید از توابع utility استفاده کنید:
import { formatPersianDateRange, toPersianDigits, getPersianMonthName } from '@parto-system-design/ui'
const formattedRange = formatPersianDateRange(new Date(2024, 0, 1), new Date(2024, 0, 15))
// خروجی: "۱ فروردین - ۱۵ فروردین ۱۴۰۲"دسترسی به توابع کمکی
formatPersianDateRange(from: Date, to: Date): string
تبدیل بازه تاریخ به رشته فارسی
toPersianDigits(num: number | string): string
تبدیل اعداد انگلیسی به فارسی
getPersianMonthName(date: Date): string
دریافت نام ماه شمسی
getPersianYear(date: Date): number
دریافت سال شمسی
jalaliToGregorian(year: number, month: number, day: number): Date
تبدیل تاریخ شمسی به میلادی
کامپوننتهای مرتبط
- DatePicker — اگر نیاز به انتخاب یک تاریخ (نه بازه) دارید، از DatePicker با
mode="single"استفاده کنید - PeriodSelector — اگر کاربر فقط از بین دورههای از پیش تعریفشده انتخاب میکند، PeriodSelector سادهتر است
- Calendar — اگر نیاز به نمایش تقویم بدون popover و input دارید، از Calendar مستقیماً استفاده کنید