تقویم (Calendar)

معرفی

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

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

• وقتی کاربر باید تاریخ تایپ کند — از DatePicker استفاده کنید
• برای نمایش رویدادها — Calendar فقط انتخاب تاریخ است، نه تقویم رویداد

زمین بازی

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

استفاده

import { Calendar } from '@partodata/ui'
import { useState } from 'react'

export default function MyComponent() {
  const [selected, setSelected] = useState<Date>()

  return <Calendar mode="single" selected={selected} onSelect={setSelected} />
}

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

تقویم شمسی

تقویم میلادی

Calendar مانند DatePicker، DateRangePicker و DateTimePicker به‌طور پیش‌فرض شمسی است و زبان صفحه تعیین‌کننده است (در ar/en میلادی)؛ usePersianCalendar صریح بر آن مقدم است. ارقام تقویم از lang خودش می‌آیند: فارسی در شمسی، لاتین در میلادی.

<Calendar mode="single" usePersianCalendar={false} />

انتخاب محدوده

<Calendar mode="range" numberOfMonths={2} />

انتخاب ماه و سال

با captionLayout="dropdown" ماه و سال را مستقیماً انتخاب کنید. fromYear و toYear سال‌های تقویم فعال‌اند؛ در تقویم شمسی سال شمسی و با usePersianCalendar={false} سال میلادی هستند. دکمه‌های ماه قبل و بعد در کنار عنوان و انتخاب‌گرهای ماه و سال قابل کلیک می‌مانند؛ این رفتار در تقویم تک‌ماهه و بازهٔ دوماهه یکسان است.

<Calendar mode="range" numberOfMonths={2} captionLayout="dropdown" fromYear={1380} toYear={1410} />

یک تقویم، یک ظاهر

همهٔ انتخاب‌گرهای تاریخ (DatePicker، DateRangePicker، DateTimePicker) همین Calendar را در پاپ‌اور خود رندر می‌کنند. تقویم مستقل همان سطحی را می‌کشد که پاپ‌اور به آن می‌دهد (زمینهٔ overlay، کادر، گوشهٔ گرد، سایه) و داخل پاپ‌اور این قاب کنار می‌رود؛ پس تقویم این صفحه و تقویم داخل انتخاب‌گرها یکی دیده می‌شوند. تقویم شمسی یا انتخاب محدوده کامپوننت جداگانه‌ای ندارد.

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

جدول ویژگی‌ها

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

• پیمایش کامل با کیبورد (Arrow keys، Enter، Escape)
• aria-selected برای روز انتخاب‌شده
• aria-disabled برای روزهای غیرفعال
• ساختار شبکه روزها با role="gridcell"

مرتبط

• Date Picker — کامپوننت کامل انتخاب بازه تاریخ (پیشنهادی)
• Popover — برای قرار دادن Calendar داخل popup
• Form — برای استفاده در فرم‌ها با اعتبارسنجی

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

• DatePicker — اگر نیاز به انتخاب تاریخ در فرم با input field و popover دارید، از DatePicker استفاده کنید
• DateRangePicker — اگر نیاز به انتخاب بازه تاریخی با label و امکانات بیشتر دارید، از DateRangePicker استفاده کنید
• PeriodSelector — اگر فقط نیاز به دوره‌های از پیش تعریف‌شده دارید (7 روز، 30 روز)، PeriodSelector ساده‌تر است