فهرست مستندات پروژه
محدودیت‌ها، قواعد بازه و بازه‌های آماده
روزهای مجاز را تعیین کنید و شب‌های رزروشده و محدودیت طول اقامت را در نظر بگیرید.
حد تاریخ و روزهای غیرقابل انتخاب
| تنظیم | رفتار |
|---|---|
min، max | حدهای شامل ابتدا و انتها؛ روز ISO برای روز، بازه و چند روز؛ هفته یا روز ISO برای هفته؛ مقدار دوره یا روز ISO برای ماه و سال |
disabled-dates | آرایه JSON از روزهای ISO یا بازه‌های ISO شامل دو سر بازه |
disable-weekends | روزهای آخر هفته را بر اساس زبان و منطقه غیرفعال می‌کند |
disabled-days-of-week | فهرست 0 تا 6 یا sun تا sat با ویرگول؛ همراه محدودیت آخر هفته اعمال می‌شود |
disabledDatesFilter | تابع JavaScript که برای غیرفعال کردن روز true برمی‌گرداند |
disable-past، disable-future | حدها را نسبت به امروز مرورگر محدود می‌کنند؛ هفته، ماه یا سال جاری برای نوع مربوط مجاز می‌ماند |
برای min و max در نوع بازه یا چند روز، رشته start/end یا فهرست با ویرگول ندهید؛ هر حد یک روز ISO است. حد نامعتبر نادیده گرفته می‌شود. ترتیب min <= max را رعایت کنید؛ رابط برای حدهای متناقض، قرارداد کاربردی مشخصی ندارد.
import 'intl-datepicker';
const picker = document.querySelector('intl-datepicker');
picker.setAttribute('min', '2026-03-01');
picker.setAttribute('max', '2026-03-31');
picker.setAttribute('disabled-dates', JSON.stringify([
'2026-03-12/2026-03-13',
'2026-03-25',
]));
picker.disabledDatesFilter = ({ iso, dayOfWeek }) =>
iso === '2026-03-20' || dayOfWeek === 0;در انتخابگر روز، علاوه بر حدها و تاریخ‌های فهرست‌شده، ۲۰ مارس و یکشنبه‌ها هم قابل انتخاب نیستند. تابع فیلتر { year, month, day, dayOfWeek, iso } را دریافت می‌کند. بخش‌های عددی تاریخ به تقویم فعال تعلق دارند؛ iso میلادی است و یکشنبه همیشه شماره 0 دارد. اختصاص فیلتر جدید، نما و اعتبارسنجی را بهروز می‌کند. خطای پرتاب‌شده در تابع گرفته می‌شود و روز را غیرفعال نمی‌کند؛ پس خطای دریافت ظرفیت را در برنامه مدیریت کنید.
ورودی نامعتبر disabled-dates نادیده گرفته می‌شود و بازه معکوس مرتب می‌شود. قواعد روزانه برای روز، چند روز و بازه کاربرد دارند. ماه و سال دوره کامل را انتخاب می‌کنند و هفته بررسی روزانه محدودی دارد.
قواعد بازه
در type="range"، تعداد شب اختلاف روز تقویمی پایان و شروع، یعنی end - start است.
| تنظیم | قاعده |
|---|---|
min-nights | حداقل شب؛ نبود آن یا مقدار 0 شروع و پایان یکسان را مجاز می‌کند |
max-nights | حداکثر شب؛ نبود آن یعنی طول نامحدود |
exclude-disabled یا exclude-disabled="days" | همه روزها، از جمله روز پایان، باید در دسترس باشند |
exclude-disabled="nights" | همه شب‌های [start, end) باید آزاد باشند؛ پایان می‌تواند اولین روز غیرفعال باشد |
نبود exclude-disabled | فقط دو سر بازه باید مجاز باشند؛ روزهای غیرفعال میانی مانعی ندارند |
استثنای روز خروج، پایان خارج از min یا max را مجاز نمی‌کند. شروع غیرفعال همچنان ممنوع است. حتی اگر بازه را برعکس انتخاب کنید، قواعد روی ترتیب زمانی اعمال می‌شوند. min-nights="1" بازه همروز را ممنوع می‌کند. در HTML، مقدار exclude-disabled="false" هم حالت روزها را فعال می‌کند؛ برای خاموش کردن، attribute را حذف کنید.
نمونه رزرو اقامت
این نمونه بازه ثابت دارد تا پس از گذشت تاریخ‌ها هم قابل بررسی باشد. فقط ماژول اصلی را وارد کنید و سپس از این HTML استفاده کنید:
<intl-datepicker id="stay" type="range" name="stay" locale="en-GB"
months="2" required min="2026-03-01" max="2026-04-30"
min-nights="2" max-nights="14" exclude-disabled="nights"
disabled-dates='["2026-03-12/2026-03-13","2026-03-25"]'
value="2026-03-08/2026-03-12"></intl-datepicker>مقدار اولیه 2026-03-08/2026-03-12 معتبر است: ۴ شب اقامت با خروج در اولین شب غیرقابل رزرو. اقامت تا ۱۴ مارس نامعتبر است، چون شب‌های رزروشده را در بر می‌گیرد. اقامت از ۸ تا ۹ مارس هم کوتاه‌تر از حد مجاز است. پس از انتخاب شروع، پایان‌های غیرمجاز aria-disabled می‌گیرند، راهنمای طول اقامت نمایش داده می‌شود و تلاش برای انتخاب پایان ممنوع با صفحه‌کلید، دلیل را اعلام می‌کند.
برای اجباری بودن پایان، از اعتبارسنجی فرم استفاده کنید. کامپوننت ظرفیت را رزرو نمی‌کند و رزروهای همزمان را مدیریت نمی‌کند؛ هنگام ثبت رزرو، ظرفیت را دوباره بررسی کنید. قاعده جداگانه برای روزی که فقط ورود در آن مجاز باشد وجود ندارد.
با mapDays و وضعیت‌های isCheckoutOnly و isRangeBlocked می‌توانید ظاهر روزها را تغییر دهید، اما خروجی disabled این تابع در پیمایش بازه یا اعتبارسنجی فرم شرکت نمی‌کند. قواعد ظرفیت را در disabled-dates یا disabledDatesFilter قرار دهید.
بازه‌های آماده
بازه‌های آماده فقط در حالت بازه نمایش داده می‌شوند. property آرایه می‌پذیرد و attribute آرایه JSON می‌پذیرد.
import 'intl-datepicker';
const picker = document.querySelector('intl-datepicker');
picker.type = 'range';
picker.presets = [
{ label: 'بازه گزارش مارس', value: '2026-03-01/2026-03-07' },
{ label: 'هفت روز اخیر', value: '-6d/today' },
{ label: 'ماه قبل', value: 'prevMonthStart/prevMonthEnd' },
];در انتخابگر بدون محدودیت، گزینه اول مقدار 2026-03-01/2026-03-07 را می‌دهد. دو گزینه دیگر به امروز وابسته‌اند. هر سر بازه می‌تواند یکی از این موارد باشد:
- یک روز معتبر میلادی به شکل ISO یا
today. -Ndیا+Ndبرای جابهجایی چند روز نسبت به امروز.monthStartوmonthEndیا نام‌های جایگزینstartOfMonthوendOfMonth.prevMonthStartوprevMonthEnd.yearStartوyearEndیا نام‌های جایگزینstartOfYearوendOfYear.
ماه و سال در تقویم فعال محاسبه می‌شوند. ابتدا دو سر بازه به حدهای موثر min و max محدود می‌شوند و سپس قواعد بازه بررسی می‌شوند. گزینه ناسازگار با قواعد غیرفعال می‌شود؛ برای سازگاری با max-nights یا ظرفیت، خودکار کوتاه نمی‌شود. در تعریف گزینه‌ها از تاریخ ISO معتبر استفاده کنید؛ تجزیه‌کننده بازه آماده، اعتبارسنج سختگیر ورودی نیست.
مقدار تنظیم‌شده با کد و اعتبارسنجی
مقدار قابل تجزیه‌ای که با کد تنظیم شده است، حتی اگر خارج از حد، روی روز غیرفعال یا ناسازگار با قواعد بازه باشد، نگه داشته می‌شود. این رفتار اجازه می‌دهد رزرو قدیمی هنگام اصلاح همچنان دیده شود. checkValidity() مشکل را نشان می‌دهد و مقدار را پاک نمی‌کند. فهرست چند روز استثنا دارد: max-dates فهرست تازه اختصاص‌یافته را کوتاه می‌کند. راهنمای مقدارها و جدول اعتبارسنجی را ببینید.