Datetime Range Picker

کامپوننت x-datetime-range-picker برای انتخاب بازه تاریخ و زمان (از - تا) در فرم‌ها با امکانات پیشرفته و قابل شخصی‌سازی استفاده می‌شود. این کامپوننت دو ورودی (from و to) را با کنترل کامل روی مقدار، بازه مجاز، فرمت، غیرفعال‌سازی، پیام‌ها و ... ارائه می‌دهد.

---

ویژگی‌ها

• پشتیبانی از لیبل جداگانه برای هر ورودی (fromLabel, toLabel)
• امکان تعیین نام جداگانه برای هر ورودی (fromName, toName) یا استفاده از یک نام پایه
• تعیین مقدار اولیه، حداقل و حداکثر تاریخ برای هر ورودی (fromValue, toValue, fromMinDate, toMinDate, ...)
• پشتیبانی از روزها و تاریخ‌های غیرفعال برای هر ورودی (disabledDays, fromDisabledDates, toDisabledDates)
• قابلیت فقط‌خواندنی و غیرفعال بودن هر ورودی به صورت مستقل (fromDisabled, toDisabled)
• تعیین فرمت نمایش (dateFormat)
• تعیین نوع انتخاب (type: تاریخ، زمان، تاریخ‌-زمان)
• پشتیبانی از انتخابگر زمان با گزینه‌های قابل تنظیم (timePickerOptions)
• نمایش آیکن تقویم و دکمه پاک‌کردن مقدار برای هر ورودی (showIcon, fromClearable, toClearable)
• پشتیبانی از پیشوند و پسوند برای هر ورودی (fromPrefix, fromSuffix, toPrefix, toSuffix)
• امکان تعیین placeholder جداگانه برای هر ورودی (fromPlaceholder, toPlaceholder)
• پشتیبانی از تقویم میلادی (allowGregorian)
• امکان انتخاب یکسان بودن روز شروع و پایان (allowSameDaySelection)
• کنترل راست‌چین یا چپ‌چین بودن (dir, textAlign)
• امکان تایپ دستی مقدار (allowTyping)
• نمایش پیام راهنما و پیام خطا با استایل‌های مختلف برای هر ورودی (fromMessageStyle, toMessageStyle, ...)
• پشتیبانی از پیام راهنما هنگام غیرفعال بودن هر ورودی (fromDisabledTooltip, toDisabledTooltip)
• شخصی‌سازی کلاس‌های CSS برای کانتینر و ردیف (containerClass, rowClass)
• تعیین فاصله بین دو اینپوت بر اساس اولین .row والد
• پشتیبانی از پیام راهنما کلی (hint)

---

ورودی‌های کامپوننت

نام پراپ	نوع داده	مقدار پیش‌فرض	توضیحات
name	string	—	نام پایه فیلد (در صورت عدم تعیین fromName و toName)
fromName	string	null	نام فیلد شروع بازه
toName	string	null	نام فیلد پایان بازه
fromLabel	string	null	لیبل ورودی شروع بازه
toLabel	string	null	لیبل ورودی پایان بازه
fromValue	Carbon	null	مقدار اولیه ورودی شروع بازه
toValue	Carbon	null	مقدار اولیه ورودی پایان بازه
fromMinDate	Carbon	null	حداقل تاریخ مجاز برای شروع
toMinDate	Carbon	null	حداقل تاریخ مجاز برای پایان
fromMaxDate	Carbon	null	حداکثر تاریخ مجاز برای شروع
toMaxDate	Carbon	null	حداکثر تاریخ مجاز برای پایان
fromDisabledDates	array	null	آرایه‌ای از تاریخ‌های غیرفعال برای شروع (آرایه‌ای از Carbon)
toDisabledDates	array	null	آرایه‌ای از تاریخ‌های غیرفعال برای پایان (آرایه‌ای از Carbon)
disabledDays	array	null	آرایه‌ای از شماره روزهای هفته (0 تا 6) که غیرفعال هستند
fromDisabled	bool	false	غیرفعال بودن ورودی شروع
toDisabled	bool	false	غیرفعال بودن ورودی پایان
fromMessageStyle	string	"message"	استایل پیام برای شروع (message, tooltip, ...)
toMessageStyle	string	"message"	استایل پیام برای پایان (message, tooltip, ...)
fromMessageType	string	"info"	نوع پیام برای شروع (info, error, success, ...)
toMessageType	string	"info"	نوع پیام برای پایان (info, error, success, ...)
fromDefaultMessage	string	null	پیام پیش‌فرض برای شروع
toDefaultMessage	string	null	پیام پیش‌فرض برای پایان
fromClearable	bool	true	امکان پاک‌کردن مقدار شروع
toClearable	bool	true	امکان پاک‌کردن مقدار پایان
fromPlaceholder	string	" "	placeholder شروع
toPlaceholder	string	" "	placeholder پایان
fromPrefix	string	null	پیشوند شروع
fromSuffix	string	null	پسوند شروع
toPrefix	string	null	پیشوند پایان
toSuffix	string	null	پسوند پایان
labelSpaceReserved	bool	false	آیا فضای لیبل حتی بدون مقدار رزرو شود؟
containerClass	string	null	کلاس CSS سفارشی برای کانتینر
rowClass	string	null	کلاس CSS سفارشی برای ردیف
id	string	null	شناسه یکتا برای ورودی
class	string	null	کلاس CSS سفارشی برای خود ورودی
required	bool	false	اجباری بودن فیلد
hint	string	null	پیام راهنما یا توضیح کوتاه
type	string	"date"	نوع انتخاب: date, time, datetime
dateFormat	string	null	فرمت نمایش تاریخ/زمان (مثلاً Y/m/d H:i)
autoClose	bool	true	بستن خودکار انتخابگر پس از انتخاب
allowGregorian	bool	false	اجازه انتخاب تقویم میلادی
allowSameDaySelection	bool	true	اجازه انتخاب یکسان بودن روز شروع و پایان
timePickerOptions	array	-	گزینه‌های انتخابگر زمان ['hours'=>true,'minutes'=>true,'seconds'=>true]
dir	string	"ltr"	جهت نوشتار ورودی (ltr یا rtl)
textAlign	string	"left"	جهت متن ورودی
showIcon	bool	true	نمایش آیکن تقویم
allowTyping	bool	false	اجازه تایپ دستی مقدار
fromDisabledTooltip	string	null	پیام راهنما هنگام غیرفعال بودن ورودی شروع
toDisabledTooltip	string	null	پیام راهنما هنگام غیرفعال بودن ورودی پایان
selectableRange	string	null	تعیین بازه مجاز انتخاب برای فیلد مقابل بر اساس فاصله زمانی مشخص (مثلاً فقط هر 30 روز)

هشدار

توجه داشته باشید که هرگونه تغییر در مقدار dateFormat باعث غیرفعال شدن امکان تایپ دستی می‌شود، زیرا کنترل ماسک ورودی در این حالت ممکن نیست. همچنین، با تغییر گزینه‌های timePickerOptions، فرمت تاریخ، ماسک و placeholder به‌صورت خودکار تنظیم می‌شوند و نیازی به تعیین دستی مقدار dateFormat نخواهید داشت.

---

مقداردهی با جاوااسکریپت

برای مقداردهی یا تغییر مقدار هر یک از اینپوت‌های کامپوننت x-datetime-range-picker به صورت داینامیک با جاوااسکریپت، می‌توانید از متد زیر استفاده کنید:

$("#date-selector-create").setValue({from: ... , to: ...});

• اگر مقدار ورودی رشته تاریخ باشد، به صورت خودکار به timestamp تبدیل می‌شود.
• مقدار جدید در اینپوت قرار گرفته و مقدار پیش‌فرض (برای ریست) نیز به‌روزرسانی می‌شود.
• اگر مقدار جدید خارج از بازه مجاز انتخاب باشد، مقدار اینپوت تغییر نخواهد کرد.
• برای پاک کردن مقدار هر فیلد، کافی است آن را برابر با null قرار دهید (مثلاً {from: null} یا {to: null}).

---

تغییر بازه زمانی قابل انتخاب با جاوااسکریپت

برای تغییر بازه زمانی کامپوننت x-datetime-range-picker به صورت داینامیک با جاوااسکریپت، می‌توانید از متد زیر استفاده کنید:

$("#date-selector-create").setRange({fromMinDate:"1403/01/01",fromMaxDate:"1403/06/01",toMinDate:"1403/04/01",toMaxDate:"1403/09/01"});
// یا مقدار unix
$("#date-selector-create").setRange({fromMinDate:1700000000,fromMaxDate:1710000000,toMinDate:1715000000,toMaxDate:1752000000});

---

مثال‌ها

نمونه پایه

<x-datetime-range-picker
    containerClass="mt-5"
    id="date-selector-range"
    from-name="created_at_from"
    to-name="created_at_to"
    name="created_at"
    fromLabel="تاریخ ایجاد از"
    toLabel="تاریخ ایجاد تا"
    autoClose="true"
    selectableRange="10"
    :allowSameDaySelection="false"
>
</x-datetime-range-picker>