فهرست مستندات پروژه

تقویم، زبان، رقم‌ها و راست‌به‌چپ

Intl Datepickerv0.4.2مشاهده منبعفارسی / انگلیسی

تقویم را مستقل از زبان تنظیم کنید و متن‌های رابط را به زبان دلخواه درآورید.

تقویم و زبان دو تنظیم جدا هستند

calendar تقویم انتخاب و محاسبه تاریخ را مشخص می‌کند. مقدار پیش‌فرض آن، مستقل از زبان، gregory است. locale نام روز و ماه، شیوه نمایش، رقم‌های پیش‌فرض، قواعد هفته و جهت رابط را تعیین می‌کند. اگر آن را مشخص نکنید، ابتدا lang سند و سپس زبان مرورگر استفاده می‌شود؛ مقدار جایگزین محیط نیز en-US است.

شناسه تقویمنوع تقویمماژول اختیاری
gregoryمیلادیهمراه ورودی اصلی
persianهجری شمسیpersian
islamic، islamic-umalquraام‌القریislamic
islamic-civilهجری قمری مدنیislamic
islamic-tblaهجری قمری جدولیislamic
hebrewعبریhebrew
buddhistبوداییbuddhist
japaneseدوره‌های ژاپنیjapanese
indianملی هندindian
ethiopic، ethioaaاتیوپی و Amete Alemethiopic
copticقبطیcoptic
rocمینگو، تایوانroc

مسیر import به شکل intl-datepicker/calendars/<module> است. جدول شامل ۱۴ شناسه پذیرفته‌شده است که نام‌های جایگزین و گونه‌های یک تقویم را هم در بر می‌گیرد. islamic هم در محاسبه و هم در نمایش به ام‌القری اشاره می‌کند. محاسبات شمسی از پیاده‌سازی وابستگی استفاده می‌کنند؛ آزمون‌ها تایید می‌کنند که ۳۰ اسفند ۱۴۰۳ برابر 2025-03-20 است.

تقویم شمسی با متن‌های فارسی

import 'intl-datepicker/calendars/persian';
import 'intl-datepicker/labels/fa';
import 'intl-datepicker';
<label for="persian-date">تاریخ</label>
<intl-datepicker id="persian-date" calendar="persian" locale="fa-IR"
  value="2024-03-20" allow-input></intl-datepicker>

تاریخ انتخاب‌شده در تقویم فعال { year: 1403, month: 1, day: 1 } است. مقدار قابل پردازش 2024-03-20 باقی می‌ماند و ورودی معمولا ۱۴۰۳/۰۱/۰۱ را نشان می‌دهد. جزئیات نشانه‌گذاری و فاصله‌ها به داده‌های Intl مرورگر وابسته‌اند. این نمونه هم ماژول تقویم و هم ترجمه رابط را وارد می‌کند؛ محلی شدن نام ماه‌ها به‌تنهایی متن دکمه‌ها و پیام‌های اعتبارسنجی را ترجمه نمی‌کند.

رقم‌ها و جهت رابط

برای نمایش رقم‌های لاتین در رابط فارسی، numerals="latn" بگذارید. شناسه‌های پشتیبانی‌شده دیگر، مانند arab، هم قابل استفاده‌اند. این تنظیم فقط نمایش را تغییر می‌دهد؛ مقدار قابل پردازش همچنان رقم‌های ASCII دارد.

کامپوننت راست‌به‌چپ بودن را از locale تشخیص می‌دهد و روی خودش dir="rtl" می‌گذارد. حرکت افقی با صفحه‌کلید هم از همین جهت پیروی می‌کند. dir روی یک والد، زبان یا قواعد صفحه‌کلید کامپوننت را تغییر نمی‌دهد. اگر جهت اهمیت دارد، locale را مشخص کنید.

first-day-of-week عدد 0 تا 6 یا نام sun تا sat را می‌پذیرد؛ یکشنبه 0 است. روزهای آخر هفته از اطلاعات محلی و در نبود آن‌ها از مقادیر جایگزین داخلی به دست می‌آیند. اگر قواعد کسب‌وکار نباید به داده‌های مرورگر وابسته باشند، disabled-days-of-week را صریح تنظیم کنید. راهنمای محدودیت‌ها را ببینید.

متن‌های رابط

انگلیسی همیشه در دسترس است. برای فارسی، عربی یا عبری، به‌ترتیب /labels/fa، /labels/ar یا /labels/he را وارد کنید. ابتدا متن‌های انگلیسی، سپس ترجمه ثبت‌شده زبان و در پایان تغییرهای شما اعمال می‌شوند. تشخیص زبان با پیشوند انجام می‌شود؛ مثلا fa-IR از fa استفاده می‌کند. زبان‌های دیگر تا زمانی که متن جایگزین ندهید، رابط انگلیسی دارند.

import 'intl-datepicker/labels/fa';
import 'intl-datepicker';

const picker = document.querySelector('intl-datepicker');
picker.labels = {
  today: 'امروز',
  dateTooEarly: 'این تاریخ یا بعد از آن را انتخاب کنید: {date}',
  nights: '{n} شب',
};

ویژگی HTML به نام labels همین شیء را به شکل JSON می‌پذیرد. تنظیم property برای هر کلید بر تنظیم attribute اولویت دارد. برای به‌روزرسانی، شیء تازه‌ای اختصاص دهید؛ تغییر مستقیم شیء خوانده‌شده، روش به‌روزرسانی رابط نیست. خواندن labels متن‌های نهایی را برمی‌گرداند. رشته خالی در تنظیم‌های شما نادیده گرفته می‌شود.

کلیدهاکاربرد و جای‌نگهدارها
today، clear، clearDateدکمه‌های پایین تقویم و پاک کردن ورودی
datePicker، rangePresets، calendarNavigationنام ناحیه‌ها برای ابزارهای کمکی
monthSelection، yearSelectionنام نمای ماه و سال
previousMonth، nextMonth، previousDecade، nextDecadeجابه‌جایی؛ با وجود نام کلید، هر صفحه سال شامل ۲۰ سال است
selectMonth، selectYear، weekNumberکنترل‌های سربرگ و ستون شماره هفته
selected، rangeStart، rangeEndوضعیت افزوده‌شده به نام دسترس‌پذیر روز
rangeSelectedاعلام بازه کامل با {start} و {end}
formatHint، invalidDateراهنمای تایپ با {format} و {example}
dateUnavailable، pleaseSelectDateتاریخ غیرقابل انتخاب یا الزامی
dateTooEarly، dateTooLateخطای حد تاریخ با {date}
rangeTooShort، rangeTooLongخطای طول بازه با {nights}
rangeUnavailable، rangeIncompleteبازه غیرمجاز یا پایان انتخاب‌نشده
minNightsHint، maxNightsHintراهنمای بازه در حال انتخاب با {nights}
nightsرشته شامل {n} یا شکل‌های جمع با کلید الزامی other

شکل جمع با Intl.PluralRules انتخاب می‌شود و {n} از تنظیم رقم‌ها پیروی می‌کند. نوع‌های IntlDatepickerLabels و PluralLabel در راهنمای نوع‌ها معرفی شده‌اند.

تغییر تقویم با حفظ روز انتخاب‌شده

این ماژول مرورگر را همراه HTML نمونه فارسی بالا اجرا کنید:

import 'intl-datepicker/calendars/persian';
import 'intl-datepicker/labels/fa';
import 'intl-datepicker';

const picker = document.querySelector('intl-datepicker');
picker.setValue('2024-03-20');
picker.setAttribute('calendar', 'gregory');
picker.setAttribute('locale', 'en-GB');
console.log(picker.value); // 2024-03-20
picker.setAttribute('calendar', 'persian');
picker.setAttribute('locale', 'fa-IR');
console.log(picker.getValue().calendar); // { year: 1403, month: 1, day: 1 }

در نوع date همان روز حفظ می‌شود. تغییر attribute تقویم یا زبان، intl-change نمی‌فرستد؛ اگر برنامه به مقدار تازه نیاز دارد، پس از تغییر آن را بخوانید. در نوع ماه یا سال، دوره‌ای از تقویم جدید انتخاب می‌شود که روز اول دوره قبلی را در بر می‌گیرد؛ بنابراین مقدار و مرزهای دوره ممکن است تغییر کنند. مرز هفته هم با تغییر قواعد شروع هفته می‌تواند جابه‌جا شود.

جستجو در مستندات

در همه پروژه‌ها جستجو کنید. با بستن این پنجره به راهنما برمی‌گردید.

Tab برای جابه‌جایی · Enter برای باز کردنEsc برای بستن