Calendar
گرید تاریخ برای انتخاب تکی، بازه یا چندتایی، روی react-day-picker ساخته شده. پیشفرض تقویم میلادی است؛ با calendar="jalali" به گاهشماری شمسی (با نام ماه و ارقام فارسی) سوییچ میکند، بدون اینکه API انتخاب تاریخ تغییر کند، مقدار selected/onSelect همیشه یک Date جاوااسکریپت استاندارد است.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
شمسی (جلالی)
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
میلادی
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/calendar.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/calendar.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/calendar.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/calendar.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import { Calendar } from "@/components/ui/calendar"
<Calendar mode="single" selected={date} onSelect={setDate} />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
دسترسپذیری
- گرید با role و aria-label مناسب برای ناوبری صفحهکلید ساخته شده؛ Tab به داخل جدول میرود و کلیدهای جهتنما بین روزها حرکت میکنند.
- فلشهای ماه قبل/بعد جهتآگاهاند: در چیدمان rtl فلش راست به ماه قبل و فلش چپ به ماه بعد میرود؛ با تغییر dir به ltr خودکار برعکس میشود.
- روزهای غیرفعال (disabled) هم از ناوبری کیبورد و هم از انتخاب موس/لمس کنار گذاشته میشوند؛ برای توضیح دلیل غیرفعال بودن (مثلاً روزهای تعطیل) یک راهنمای متنی جدا از خودِ تقویم بگذارید.
- وقتی Calendar داخل Popover است، فوکوس هنگام باز شدن به گرید میرود و با Escape به دکمهٔ باز کننده برمیگردد؛ رفتار همان چیزی است که در صفحهٔ Popover مستند شده.
- قرمزیِ روزهای تعطیل فقط نشانهٔ دیداری است؛ اگر تعطیل بودن روی تصمیم کاربر اثر دارد، همان اطلاعات را در متن کنار تقویم یا در aria-label روز هم بیاورید.
- نام ماه و سال در سرصفحه دکمهاند و با Tab و Enter هم باز میشوند؛ در فهرست ماه و سال، مورد فعال با aria-current مشخص است و دکمهٔ بازگشت برچسب دارد.
مرجع API
Calendar
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| calendar | "gregorian" | "jalali" | "gregorian" | گاهشماری گرید؛ jalali نام ماه و اعداد را شمسی میکند. |
| mode | "single" | "multiple" | "range" | "single" | نوع انتخاب. |
| selected / onSelect | Date | Date[] | DateRange | — | مقدار انتخابشده و رویداد تغییر آن؛ شکلش به mode بستگی دارد. |
| disabled | Matcher | Matcher[] | — | روزهای غیرقابلانتخاب (تابع، بازه، dayOfWeek، آرایهٔ تاریخ). |
| defaultMonth | Date | — | ماهی که هنگام باز شدن نشان داده میشود؛ اگر ندهید، ماه امروز. |
| startMonth / endMonth | Date | — | کرانهای ناوبری؛ در حالت کشویی بازهٔ سالهای فهرست را هم تعیین میکنند. |
| numberOfMonths | number | 1 | تعداد ماههایی که کنار هم نشان داده میشود. |
| showOutsideDays | boolean | true | نمایش روزهای ماه قبل و بعد در خانههای خالی. |
| showWeekNumber | boolean | false | ستون شمارهٔ هفته در ابتدای شبکه. |
| dir | "rtl" | "ltr" | calendar === "jalali" ? "rtl" : "ltr" | جهت گرید و فلشهای ناوبری ماه؛ پیشفرض خودش را از calendar میگیرد (شمسی راستبهچپ، میلادی چپبهراست) مگر صریح بدهید. |
| captionLayout | "panel" | "label" | "dropdown" | "dropdown-months" | "dropdown-years" | "panel" | panel یعنی نام ماه و سال دکمهاند و فهرستشان جای تقویم میآید؛ label فقط متن است و dropdown* منوی بومی مرورگر. |
| fixedWeeks | boolean | false | با true همیشه شش سطر میکشد تا ارتفاع قاب با عوض شدن ماه نپرد؛ پیشفرض سطرهای واقعی ماه است تا تقویم کوتاهتر بماند. |
| holidays | Matcher | Matcher[] | — | روزهای تعطیل رسمی؛ قرمز میشوند ولی قابل انتخاب میمانند. برای بستنشان از disabled استفاده کنید. |
| weekend | number[] | false | [5] | روزهای آخر هفته که قرمز میشوند (۰ یکشنبه تا ۶ شنبه)؛ پیشفرض جمعه. با false خاموش میشود. |
| buttonVariant | ButtonProps["variant"] | "ghost" | واریانت دکمههای قبلی/بعدی ماه. |
| className / classNames | string / Partial<ClassNames> | — | کلاس ریشه، و بازنویسی کلاس هر بخش داخلی (month، weekday، day، today و…). |
CalendarDayButton
دکمهٔ یک روز. اگر خواستید محتوای خانه را عوض کنید، مثلاً نقطهٔ رویداد زیر عدد، همین را با prop به نام components جایگزین کنید.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| day | CalendarDay | — | شیء روز؛ day.date همان تاریخ استاندارد جاوااسکریپت است. |
| modifiers | Modifiers | — | وضعیت روز: selected، today، outside، disabled، range_start، range_middle و range_end. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Date Field
ترکیب رایج: دکمهای که تاریخ انتخابشده را نشان میدهد و با کلیک، تقویم را داخل Popover باز میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Range
mode="range" بازه را با شروع و پایان برمیگرداند و numberOfMonths دو ماه را کنار هم میگذارد؛ کاربر بدون رفتوبرگشت بین ماهها بازه را میبیند.
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Two Months (Gregorian)
همان بازه در گاهشماری میلادی. calendar="gregorian" جهت را خودکار چپبهراست میکند، حتی داخل صفحهٔ فارسی؛ ماه اول سمت چپ مینشیند و فلشهای ناوبری هم با همین جهت هماهنگاند.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Multiple Days
با mode="multiple" چند روز پراکنده انتخاب میشود؛ مقدار آرایهای از Date است.
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Month and Year Panel
روی نام ماه یا سال بزنید تا فهرستش جای تقویم بیاید؛ با دکمهٔ بازگشت یا انتخاب یک مورد به تقویم برمیگردید. بازهٔ سالها از startMonth تا endMonth خوانده میشود.
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Disabled Dates
پراپ disabled یک Matcher (تابع، بازه، آرایه یا dayOfWeek) میپذیرد؛ اینجا روزهای گذشته و جمعهها غیرفعال شدهاند.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
روزهای بسته (Disabled)
روز بسته باید دیده شود ولی انتخابنشدنی باشد، نه اینکه از تقویم حذف شود؛ کاربر باید بفهمد آن روز وجود دارد و بسته است. disabled هم بازهٔ تاریخ میگیرد و هم روز هفته.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
روزهای گذشته و جمعهها بستهاند. روز بسته باید دیده شود ولی انتخابنشدنی باشد، نه اینکه از تقویم حذف شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نامعتبر (Invalid)
تقویم خودش نمیداند سقف زمانبندی سازمان چقدر است. این نوع خطا را بیرون از تقویم بسنجید و پیامش را کنارش بنویسید؛ روزها را بستن، دلیل را پنهان میکند.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
حداکثر تا ۳۰ روز آینده قابل زمانبندی است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
در حال دریافت (Loading)
تقویم خالی نشان ندهید، چون کاربر روی روزی کلیک میکند که شاید بسته باشد. تا رسیدن داده، جای خالیِ هماندازه بگذارید تا چیدمان صفحه نپرد.
در حال دریافت روزهای آزاد…
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Date Field | ترکیب رایج: دکمهای که تاریخ انتخابشده را نشان میدهد و با کلیک، تقویم را داخل Popover باز میکند. |
| Range | mode="range" بازه را با شروع و پایان برمیگرداند و numberOfMonths دو ماه را کنار هم میگذارد؛ کاربر بدون رفتوبرگشت بین ماهها بازه را میبیند. |
| Two Months (Gregorian) | همان بازه در گاهشماری میلادی |
| Multiple Days | با mode="multiple" چند روز پراکنده انتخاب میشود؛ مقدار آرایهای از Date است. |
| Month and Year Panel | روی نام ماه یا سال بزنید تا فهرستش جای تقویم بیاید؛ با دکمهٔ بازگشت یا انتخاب یک مورد به تقویم برمیگردید |
| Disabled Dates | پراپ disabled یک Matcher (تابع، بازه، آرایه یا dayOfWeek) میپذیرد؛ اینجا روزهای گذشته و جمعهها غیرفعال شدهاند. |
| روزهای بسته (Disabled) | زمانبندی که روزهای گذشته و تعطیل را نمیپذیرد |
| نامعتبر (Invalid) | تاریخی که با قاعدهٔ دیگری از همان فرم نمیخواند |
| در حال دریافت (Loading) | تقویمی که روزهای آزادش را از سرور میگیرد |
دستورالعمل استفاده
برای کاربر فارسیزبان، تقویم جلالی پیشفرض بگیرید
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
انجام بده
در فرمهای عمومی (تاریخ تولد، رزرو، سررسید) calendar="jalali" بگذارید؛ تاریخی که کاربر میبیند با چیزی که در ذهنش دارد یکی است.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
انجام نده
نمایش تقویم میلادی بهعنوان تنها گزینه، کاربر را مجبور میکند هر بار تاریخ ذهنیاش را به میلادی تبدیل کند، منبع رایج خطای انتخاب تاریخ.
بازهٔ غیرمجاز را با disabled نشان بده، نه فقط در توضیح متنی
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
انجام بده
با پراپ disabled (تابع، بازه یا روز هفته) روزهای غیرقابلانتخاب را در خودِ گرید کمرنگ و غیرفعال کنید تا کاربر قبل از کلیک بفهمد.
| Su | Mo | Tu | We | Th | Fr | Sa |
|---|---|---|---|---|---|---|
جمعهها و روزهای گذشته قابل انتخاب نیستند.
انجام نده
گذاشتن یک متن جدا مثل «جمعهها و روزهای گذشته قابل انتخاب نیستند» بدون غیرفعالکردن واقعی روزها، خطا را فقط بعد از کلیک اشتباه به کاربر نشان میدهد.
برای تاریخهای دور، فهرست سال بگذارید
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
انجام بده
سرصفحهٔ پیشفرض (panel) نام ماه و سال را دکمه میکند: یک کلیک روی سال، فهرست سالها را جای تقویم میآورد. بازهٔ فهرست را با startMonth و endMonth محدود کنید.
| ش | ی | د | س | چ | پ | ج |
|---|---|---|---|---|---|---|
انجام نده
با captionLayout="label" سرصفحه فقط متن است؛ رسیدن به سال ۱۳۷۰ دهها بار زدن فلش «ماه قبل» میشود، برای کاربر صفحهکلید و کاربر با محدودیت حرکتی عملاً غیرقابل استفاده.