انتخابگر بازه تاریخ (DateRangePicker)

معرفی

کامپوننت Date Range Picker برای انتخاب بازه تاریخ (از تاریخ شروع تا تاریخ پایان) استفاده می‌شود. این کامپوننت از تقویم شمسی (جلالی) و میلادی پشتیبانی می‌کند و به طور کامل RTL است.

چه زمانی استفاده کنیم:

• برای فیلتر کردن گزارش‌ها و داشبوردها بر اساس بازه زمانی دلخواه کاربر
• در فرم‌هایی که تاریخ شروع و پایان به هم وابسته‌اند (مانند بازه اجرای کمپین تخفیف فصلی یا رزرو اقامت)
• زمانی که کاربر باید بازه دقیقی را روی تقویم شمسی یا میلادی انتخاب کند و دیدن روزهای بین شروع و پایان به تصمیم او کمک می‌کند

چه زمانی استفاده نکنیم:

• برای انتخاب فقط یک تاریخ (مانند تاریخ انتشار یک گزارش) — از DatePicker استفاده کنید
• برای نمایش دائمی تقویم در صفحه بدون popover و دکمه trigger — از Calendar با mode="range" به صورت مستقیم استفاده کنید
• برای دوره‌های درشت و از پیش تعریف‌شده (مانند «۷ روز اخیر» یا «ماه اخیر») — از یک Select ساده یا PeriodSelector استفاده کنید تا کاربر مجبور به باز کردن تقویم نشود

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده پایه

import { DateRangePicker } from '@partodata/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 '@partodata/ui'
;<DateRangePickerInline value={dateRange} onChange={setDateRange} placeholder="انتخاب تاریخ" />

راهنمای استفاده

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>
  )
}

نکات مهم

1. تقویم شمسی: هنگام استفاده از usePersianCalendar={true}, تاریخ‌ها به صورت شمسی نمایش داده می‌شوند اما مقادیر Date همچنان میلادی هستند.

2. بسته شدن خودکار: پس از انتخاب هر دو تاریخ (شروع و پایان), popover به صورت خودکار بسته می‌شود.

3. RTL: این کامپوننت به طور کامل از RTL پشتیبانی می‌کند و در محیط راست به چپ به درستی کار می‌کند.

4. دسترسی: کامپوننت از استانداردهای دسترسی پیروی می‌کند و با کیبورد قابل استفاده است.

توابع کمکی

برای کار با تاریخ‌های شمسی، می‌توانید از توابع utility استفاده کنید:

import { formatPersianDateRange, toPersianDigits, getPersianMonthName } from '@partodata/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

تبدیل تاریخ شمسی به میلادی

دسترسی‌پذیری

• دکمه trigger یک <button> استاندارد است؛ با Enter/Space باز می‌شود و popover تقویم به‌صورت Radix Popover فوکس را trap می‌کند.
• در تقویم: کلیدهای جهت (← → ↑ ↓) برای جابه‌جایی روز، Page Up/Page Down برای ماه، و Home/End برای ابتدا/انتهای هفته کار می‌کنند.
• Enter تاریخ زیر فوکس را انتخاب می‌کند؛ پس از انتخاب هر دو تاریخ شروع و پایان، popover خودکار بسته می‌شود.
• Escape popover را بدون اعمال تغییر می‌بندد و فوکس به دکمه trigger برمی‌گردد.
• روزهای انتخاب‌شده با aria-selected="true"، روزهای داخل بازه با aria-current متمایز می‌شوند، و بازه با data-range-middle markup می‌شود.
• label به عنوان label قابل-دسترس به صورت بصری بالای trigger ظاهر می‌شود و screen reader هدف فیلد را اعلام می‌کند.
• در حالت usePersianCalendar={true}، نام ماه/روز و اعداد به فارسی اعلام می‌شوند ولی مقدار Date همچنان میلادی است — بنابراین i18n value معنادار باقی می‌ماند.

کامپوننت‌های مرتبط

• DatePicker — اگر نیاز به انتخاب یک تاریخ (نه بازه) دارید، از DatePicker با mode="single" استفاده کنید
• PeriodSelector — اگر کاربر فقط از بین دوره‌های از پیش تعریف‌شده انتخاب می‌کند، PeriodSelector ساده‌تر است
• Calendar — اگر نیاز به نمایش تقویم بدون popover و input دارید، از Calendar مستقیماً استفاده کنید