آشنایی با Intl Datepicker

Intl Datepicker یک عنصر سفارشی وب با نام intl-datepicker است. با آن می‌توانید یک روز، بازه، هفته، چند روز، ماه یا سال را انتخاب کنید. محاسبات تقویم با @internationalized/date انجام می‌شوند و نمایش محلی تاریخ از APIهای Intl مرورگر استفاده می‌کند.

ورودی اصلی بسته، تقویم میلادی و متن‌های انگلیسی رابط را ثبت می‌کند. تقویم‌ها و ترجمه‌های دیگر را جداگانه وارد می‌کنید. برای React یک کامپوننت واسط وجود دارد؛ در چارچوب‌های دیگر از خود عنصر سفارشی استفاده می‌کنید.

نخستین نمونه کاربردی

بسته را در یک برنامه مرورگری با ابزار ساخت سازگار با ماژول‌های ES نصب کنید:

npm install intl-datepicker

کد HTML را در صفحه و کد JavaScript را در ماژول ورودی مرورگر قرار دهید:

<label for="appointment">تاریخ نوبت</label>
<intl-datepicker id="appointment" name="appointment"
  locale="en-US" value="2026-03-15"></intl-datepicker>
<output id="selected-date"></output>

import 'intl-datepicker';

const picker = document.querySelector('intl-datepicker');
const output = document.querySelector('#selected-date');
output.textContent = picker.value;
picker.addEventListener('intl-change', ({ detail }) => {
  output.textContent = detail.value;
});

ماژول را پس از ایجاد عناصر صفحه اجرا کنید؛ برای نمونه، آن را با یک اسکریپت از نوع ماژول در برنامه بارگذاری کنید. خروجی اولیه 2026-03-15 است. با انتخاب روز دیگر، خروجی تغییر می‌کند و با پاک کردن انتخاب، رشته خالی می‌شود. مقدار اولیه رویداد تغییر نمی‌فرستد؛ به همین دلیل در نمونه آن را مستقیم می‌خوانیم. سبک‌ها همراه کامپوننت هستند و نیازی به وارد کردن فایل CSS جداگانه نیست.

از کدام راهنما شروع کنم؟

• نصب: ورودی‌های بسته، وارد کردن بخش‌های اختیاری و نیازمندی‌های مرورگر.
• تقویم و زبان: متن‌های فارسی، رقم‌ها، راست‌به‌چپ و تغییر تقویم.
• انواع انتخابگر: قالب مقدار هر ۶ نوع و مفهوم دوره‌های زمانی.
• محدودیت‌ها و بازه‌های آماده: قواعد رزرو و تاریخ‌های غیرقابل انتخاب.
• مقدارها، رویدادها و TypeScript: ذخیره‌سازی و API عمومی.
• فرم‌های بومی: خواندن FormData، اعتبارسنجی و بازنشانی.
• چارچوب‌ها و SSR: اتصال به React، Vue، Svelte و Angular.
• ظاهر و دسترس‌پذیری: تنظیم سبک و کار با صفحه‌کلید.
• نمونه‌های کاربردی و رفع اشکال: دوره گزارش، به‌روزرسانی ظرفیت و مشکلات رایج.

پیش از اتصال به برنامه

تقویم را جداگانه انتخاب کنید. locale="fa-IR" زبان و شیوه نمایش را تغییر می‌دهد، اما تقویم را شمسی نمی‌کند. برای تقویم شمسی، ماژول Persian را وارد کنید و calendar="persian" بگذارید.

مقدار قابل پردازش را ذخیره کنید، نه متن نمایشی را. مقدار روز حتی در تقویم شمسی، رشته تاریخ میلادی بدون ساعت است. مقدار ماه و سال در تقویم‌های غیرمیلادی، تاریخ ISO همراه با شناسه تقویم است. جزئیات در مقدارها و منطقه زمانی آمده است.

داده ارسالی را در برنامه اعتبارسنجی کنید. محدودیت‌ها در انتخاب کاربر اعمال می‌شوند، اما مقدار قابل تجزیه‌ای که با کد تنظیم شده است ممکن است باقی بماند و هم‌زمان نامعتبر باشد. ساختن FormData هم به‌تنهایی اعتبارسنجی را اجرا نمی‌کند.

API هنوز به نسخه ۱ نرسیده است. هنگام ارتقا، فهرست تغییرات را بخوانید. صفحه نمونه برای دیدن کامپوننت کاربرد دارد؛ قراردادها و محدودیت‌های آن در این راهنماها توضیح داده شده‌اند.