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

معرفی

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

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

• در سرِ یک کارت نمودار (actions در DashboardChart یا ChartCard) برای عوض کردن پنجرهٔ زمانی همان نمودار بین چند دورهٔ ثابت (مانند 7، 30 و 90 روز)

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

• برای بازهٔ کل صفحه، نوارابزار یا فیلتر — از DateRangePicker با بازه‌های آماده‌اش استفاده کنید
• برای انتخاب تاریخ دقیق — از DatePicker با mode="single" استفاده کنید

زمین بازی

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

استفاده

import { PeriodSelector } from '@partodata/ui'

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

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

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

6 دوره پیش‌فرض: 1 روز، 7 روز، 30 روز، 90 روز، 1 سال، همه

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

نوع PeriodOption:

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

import { PeriodSelector, type PeriodOption } from '@partodata/ui'

const customPeriods: PeriodOption[] = [
  { value: '24h', label: { fa: '24 ساعت', ar: '24 ساعة', en: '24H' } },
  { value: '48h', label: { fa: '48 ساعت', ar: '48 ساعة', en: '48H' } },
  { value: '1w', label: { fa: '1 هفته', ar: 'أسبوع 1', en: '1W' } },
]

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

اندازه‌ها

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

انگلیسی

locale فقط زبان برچسب‌ها را تغییر می‌دهد و جهت چیدمان را دست نمی‌زند؛ جهت از سند خوانده می‌شود.

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

جهت (dir)

// جهت از سند گرفته می‌شود (حالت پیش‌فرض و توصیه‌شده)
<PeriodSelector value={period} onValueChange={setPeriod} />

// فقط برای جزیرهٔ عمداً دوجهته
<PeriodSelector value={period} onValueChange={setPeriod} dir="ltr" />

Props

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

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

6 دوره استاندارد: 1 روز، 7 روز، 30 روز، 90 روز، 1 سال، همه.

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

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

اندازه‌ها

مقیاس استاندارد 5 سطحی سیستم طراحی موجود است: "xs"، "sm" (پیش‌فرض)، "md"، "lg"، "xl" — همسو با Input، Button و Select در همان ردیف ابزار.

حالت غیرفعال

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

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

نکات

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

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

• بر پایه ToggleGroup با نقش radiogroup برای screen reader
• پیمایش بین دوره‌ها با ← و →
• انتخاب دوره با Enter یا Space
• همیشه یک دوره فعال وجود دارد (الگوی single-select)
• جهت چیدمان و محور کلیدهای جهت‌دار از جهت سند گرفته می‌شود، نه از locale؛ بنابراین یک صفحهٔ RTL با برچسب‌های انگلیسی همچنان مانند بقیهٔ کنترل‌های صفحه رفتار می‌کند. برای جزیره‌های عمداً دوجهته، dir را صریح بدهید

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

• برای بازهٔ صفحه، نوارابزار و فیلترها (بازه‌های آماده و بازهٔ دلخواه) → DateRangePicker
• اگر نیاز به انتخاب یک تاریخ دقیق دارید → DatePicker
• اگر نیاز به نوار فیلتر کامل با چندین معیار در یک صفحهٔ فهرست دارید → ListPage (search و filters قالب)