انتخابگر دوره (PeriodSelector)

معرفی

کامپوننت PeriodSelector برای انتخاب دوره‌های زمانی (مثلاً ۱ روز، ۷ روز، ۳۰ روز) استفاده می‌شود. بر پایه ToggleGroup ساخته شده و همیشه یک مقدار انتخاب‌شده دارد.

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

• برای فیلتر زمانی داشبوردها با دوره‌های از پیش تعریف‌شده
• وقتی کاربر باید بین بازه‌های زمانی ثابت (مانند ۷ روز، ۳۰ روز، ۱ سال) انتخاب کند
• در بالای نمودارها و جداول گزارشی

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

• برای انتخاب تاریخ دقیق — از DatePicker استفاده کنید
• برای بازه‌های تاریخی سفارشی — از DateRangePicker استفاده کنید
• خارج از context داشبورد — PeriodSelector مخصوص فیلتر زمانی داشبورد است

استفاده

import { PeriodSelector } from '@parto-system-design/ui'

const [period, setPeriod] = useState('7d')

;<PeriodSelector value={period} onValueChange={setPeriod} />

دوره‌های پیش‌فرض

۶ دوره پیش‌فرض: ۱ روز، ۷ روز، ۳۰ روز، ۹۰ روز، ۱ سال، همه

دوره‌های سفارشی

نوع PeriodOption:

interface PeriodOption {
  value: string
  label: {
    fa: string
    en: string
  }
}

import { PeriodSelector, type PeriodOption } from '@parto-system-design/ui'

const customPeriods: PeriodOption[] = [
  { value: '24h', label: { fa: '۲۴ ساعت', en: '24H' } },
  { value: '48h', label: { fa: '۴۸ ساعت', en: '48H' } },
  { value: '1w', label: { fa: '۱ هفته', en: '1W' } },
]

;<PeriodSelector value={period} onValueChange={setPeriod} periods={customPeriods} />

اندازه‌ها

<PeriodSelector value={period} onValueChange={setPeriod} size="sm" />
<PeriodSelector value={period} onValueChange={setPeriod} size="md" />

انگلیسی

<PeriodSelector value={period} onValueChange={setPeriod} locale="en" />

Props

حالت‌ها و انواع

دوره‌های پیش‌فرض

۶ دوره استاندارد: ۱ روز، ۷ روز، ۳۰ روز، ۹۰ روز، ۱ سال، همه.

دوره‌های سفارشی

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

اندازه‌ها

دو اندازه "sm" و "md" موجود است.

حالت غیرفعال

با disabled تمام دکمه‌ها غیرفعال می‌شوند.

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

نکات

• همیشه یک دوره انتخاب‌شده وجود دارد (deselect امکان‌پذیر نیست)
• از DEFAULT_PERIODS می‌توانید export کنید و extend کنید

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

• بر پایه ToggleGroup با نقش radiogroup برای screen reader
• پیمایش بین دوره‌ها با ← و →
• انتخاب دوره با Enter یا Space
• همیشه یک دوره فعال وجود دارد (الگوی single-select)
• پشتیبانی کامل از RTL

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

• اگر نیاز به انتخاب بازه تاریخی سفارشی دارید → DateRangePicker
• اگر نیاز به انتخاب یک تاریخ دقیق دارید → DatePicker
• اگر نیاز به نوار فیلتر کامل با چندین معیار دارید → FilterBar