پرتوپرتو

انتخابگر بازه تاریخ (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

Prop

Type

مثال‌های کاربردی

فرم رزرو هتل

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 '@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 مستقیماً استفاده کنید