توابع کاربردی جاوااسکریپت برای مدیریت فرمت‌های تاریخ شمسی

سلام رفیق برنامه‌نویس! اگه تا حالا با نمایش تاریخهای شمسی توی پروژه‌هات در جاوااسکریپت سروکله زدی، می‌دونی که این کار می‌تونه یه چالش درست و حسابی باشه. از تبدیل میلادی گرفته تا فرمت‌دهی‌های مختلف مثل “۱۴۰۲/۰۷/۲۵” یا “سه‌شنبه، بیست و پنجم مهر ۱۴۰۲”، همه‌اش داستان خودشو داره. اما نگران نباش، این مقاله راهنمای جامع توئه که چطوری با استفاده از توابع و کتابخانه‌های قدرتمند، این مدیریت تاریخ شمسی رو برات مثل آب خوردن کنه. آماده‌ای؟ بزن بریم که یه عالمه ابزار و ترفند کاربردی رو با هم یاد بگیریم!

ضرورت مدیریت تاریخ شمسی در جاوااسکریپت

ببین، وقتی داری برای یه کاربر ایرانی اپلیکیشن یا وب‌سایت می‌نویسی، نمایش تاریخ به فرمت میلادی شاید برای خارجی‌ها اوکی باشه، اما برای کاربرای خودمون گیج‌کننده است. همه ما به تقویم شمسی عادت داریم و انتظار داریم تاریخ تولد، تاریخ ثبت‌نام، تاریخ فاکتور و هرچیزی که با زمان گره خورده، به زبون خودمونی یعنی شمسی بهمون نشون داده بشه. این فقط یه بحث فرهنگی نیست، بلکه مستقیماً روی تجربه کاربری (UX) و راحتی استفاده تاثیر می‌ذاره. تصور کن یه فرم ثبت‌نام داری که از کاربر می‌خواد تاریخ تولدش رو وارد کنه و فقط تقویم میلادی رو نشون میده؛ چقدر اذیت‌کننده است؟ یا فاکتوری که تاریخ تحویلش به میلادی خورده و مشتری باید هر بار ذهنی تبدیلش کنه.

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

ابزارهای پایه: آبجکت Date و محدودیت‌ها

خب، جاوااسکریپت یه آبجکت داخلی به اسم Date داره که برای کار با تاریخ و زمان میلادی خیلی خوبه. می‌تونی باهاش تاریخ جدید بسازی، اجزای مختلف تاریخ (سال، ماه، روز، ساعت و…) رو استخراج کنی و حتی باهاش محاسبات ساده انجام بدی. مثلاً:

کپیconst now = new Date();
console.log(now.getFullYear()); // سال میلادی
console.log(now.getMonth() + 1); // ماه میلادی (از 0 شروع میشه)
console.log(now.getDate()); // روز میلادی
console.log(now.toLocaleDateString('en-US')); // مثلاً "10/26/2023"

اما مشکل کجاست؟ مشکل اینه که Date آبجکت فقط برای تقویم میلادی طراحی شده. هیچ تابع یا متدی نداره که به‌صورت مستقیم تاریخ شمسی بهت بده، یا مثلاً بهت بگه امروز چندم مهر ماهه. برای نمایش شمسی، توابع toLocaleDateString() و toLocaleString() رو داریم که میشه باهاشون لوکال (locale) فارسی رو ست کرد، اما این کار هم همیشه دقیق نیست و ممکنه توی مرورگرهای مختلف یا سیستم‌عامل‌ها، نتایج متفاوتی بده یا فرمت دلخواهت رو نداشته باشه. مثلا:

کپیconst date = new Date();
console.log(date.toLocaleDateString('fa-IR')); // ممکنه خروجی‌هایی مثل "۱۴۰۲/۰۷/۲۵" یا "۲۵ مهر ۱۴۰۲" بده

همونطور که می‌بینی، عملکردِش به لوکال سیستم یا مرورگر بستگی داره و ممکنه کنترل کاملی روی فرمت نداشته باشی. برای همین، برای یه راهکار پایدار و قابل اعتماد، باید بریم سراغ کتابخانه‌های جانبی که اختصاصاً برای تاریخ شمسی طراحی شدن. اگه دنبال ابزارهای پیشرفته‌تر و راحت‌تر برای این کار هستی، حتماً یه سری به فروشگاه ابزارهای ما بزن.

معرفی کتابخانه‌های تاریخ شمسی در جاوااسکریپت

اینجاست که قدرت کامیونیتی جاوااسکریپت خودش رو نشون میده. چندتا کتابخانه عالی داریم که کارمون رو برای مدیریت تاریخ شمسی حسابی راحت می‌کنن. معروف‌ترین و پرکاربردترین هاشون اینان:

• persian-date: یه کتابخانه جامع و قدرتمند که قابلیت‌های زیادی برای تبدیل، فرمت‌دهی، محاسبات و کار با تاریخ شمسی ارائه میده. API خیلی شبیه به moment.js داره (اگه باهاش کار کرده باشی).
• jalaali-js: این کتابخانه بیشتر روی تبدیل تاریخ میلادی به شمسی و برعکس تمرکز داره و حجمش کمتره. برای پروژه‌هایی که فقط نیاز به تبدیل دارن، گزینه خوبیه.
• moment-jalaali: اگه قبلاً از moment.js برای مدیریت تاریخ و زمان استفاده می‌کردی، moment-jalaali یه افزونه برای moment.js هست که قابلیت‌های شمسی رو بهش اضافه می‌کنه.

در ادامه، ما بیشتر روی persian-date تمرکز می‌کنیم چون هم جامع‌تره و هم استفاده ازش برای اکثر سناریوها راحته. حالا بیا یه نگاهی به مقایسه‌شون بندازیم تا بهتر متوجه تفاوت‌هاشون بشی:

پیاده‌سازی گام‌به‌گام با persian-date

4.1. نصب و راه‌اندازی

اولین قدم اینه که کتابخونه رو به پروژه‌ت اضافه کنی. اگه از npm یا yarn استفاده می‌کنی:

کپیnpm install persian-date
# یا
yarn add persian-date

بعدش می‌تونی تو فایل‌های جاوااسکریپتت ایمپورتش کنی:

کپیimport PersianDate from 'persian-date';
// یا برای استفاده در مرورگر بدون ماژول‌باندلر:
// <script src="path/to/persian-date.min.js"></script>
// در این حالت، PersianDate در Global Scope قابل دسترسه

4.2. تبدیل تاریخ میلادی به شمسی

حالا که persian-date رو داری، می‌تونی به راحتی تاریخ میلادی رو به شمسی تبدیل کنی. می‌تونی یه Date آبجکت جاوااسکریپتی بهش بدی، یا حتی یک رشته تاریخ میلادی:

کپیconst ميلادي_امروز = new Date();
const شمسي_امروز = new PersianDate(ميلادي_امروز);

console.log(شمسي_امروز.format('YYYY/MM/DD')); // مثلاً "1402/07/26"
console.log(شمسي_امروز.year()); // 1402
console.log(شمسي_امروز.month()); // 7 (مهر)
console.log(شمسي_امروز.date()); // 26

همچنین می‌تونی مستقیماً تاریخ شمسی ایجاد کنی:

کپیconst تاريخ_تولد = new PersianDate([1370, 5, 20]); // سال، ماه، روز شمسی
console.log(تاريخ_تولد.format('YYYY-MM-DD')); // "1370-05-20"

4.3. فرمت‌دهی تاریخ شمسی

یکی از قوی‌ترین ویژگی‌های persian-date، قابلیت فرمت‌دهی انعطاف‌پذیرشه. می‌تونی هر فرمتی که دوست داری رو بسازی:

• YYYY: سال کامل (مثلاً 1402)
• YY: دو رقم آخر سال (مثلاً 02)
• MM: ماه با صفر پیشوند (01-12)
• M: ماه بدون صفر پیشوند (1-12)
• DD: روز با صفر پیشوند (01-31)
• D: روز بدون صفر پیشوند (1-31)
• dddd: نام کامل روز هفته (مثلاً سه‌شنبه)
• MMM: نام کوتاه ماه (مثلاً مهر)
• MMMM: نام کامل ماه (مثلاً مهر)
• HH: ساعت 24 ساعته (00-23)
• mm: دقیقه (00-59)
• ss: ثانیه (00-59)

چند مثال عملی:

کپیconst pdate = new PersianDate(); // تاریخ امروز
console.log(pdate.format('YYYY/MM/DD - dddd')); // "1402/07/26 - پنج‌شنبه"
console.log(pdate.format('DD MMMM YYYY، ساعت HH:mm')); // "26 مهر 1402، ساعت 10:30"
console.log(pdate.format('dddd, DD MMMM YYYY')); // "پنج‌شنبه, 26 مهر 1402"
console.log(pdate.format('MMMM DD')); // "مهر 26"

4.4. محاسبات تاریخ (اضافه/کم کردن روز، ماه، سال)

انجام محاسبات روی تاریخ شمسی با persian-date خیلی آسونه:

کپیconst امروز = new PersianDate();

// 10 روز بعد
const ده_روز_بعد = امروز.add(10, 'days');
console.log(ده_روز_بعد.format('YYYY/MM/DD'));

// 2 ماه قبل
const دو_ماه_قبل = امروز.subtract(2, 'months');
console.log(دو_ماه_قبل.format('YYYY/MM/DD'));

// 1 سال بعد
const یک_سال_بعد = امروز.add(1, 'years');
console.log(یک_سال_بعد.format('YYYY/MM/DD'));

همونطور که می‌بینی، با متدهای add() و subtract() و تعیین واحد (days, months, years, hours, minutes, seconds) می‌تونی به راحتی تاریخ رو جابجا کنی. برای دیدن کدهای آماده و اسنیپت‌های بیشتر می‌تونی به بخش مربوطه در سایت سر بزنی.

4.5. کار با ورودی‌های فرم

یکی از سناریوهای رایج، گرفتن تاریخ از کاربره. اگه کاربر تاریخ رو به فرمت شمسی (مثلاً “1402/07/26”) وارد کنه، باید بتونیم اون رو به درستی پردازش کنیم. persian-date این قابلیت رو هم داره:

کپیconst inputDateString = "1402/07/26"; // ورودی از کاربر
const pDateFromInput = new PersianDate(inputDateString);

console.log(pDateFromInput.format('dddd, DD MMMM YYYY'));
// اگه لازم باشه به میلادی برگردونیم:
console.log(pDateFromInput.toCalendar('gregorian').format('YYYY-MM-DD'));

توجه داشته باش که persian-date به صورت هوشمند سعی می‌کنه فرمت ورودی رو تشخیص بده، اما برای ورودی‌های خاص یا نامنظم، بهتره خودت ورودی رو قبل از پاس دادن به PersianDate کمی پردازش کنی.

مدیریت تقویم شمسی در رابط کاربری (UI)

فقط داشتن توابع بک‌اند برای تاریخ کافی نیست؛ تو باید این تاریخ‌ها رو به شکلی کاربرپسند تو رابط کاربریت هم نمایش بدی. این یعنی استفاده از Date Pickerهای شمسی. کتابخانه‌های UI زیادی برای فریم‌ورک‌های مختلف (React, Vue, Angular) وجود دارن که Date Picker شمسی رو به راحتی در اختیارت می‌ذارن. مثلا:

• برای React: react-persian-datepicker
• برای Vue: vue-persian-datetime-picker
• برای Vanilla JS: می‌تونی با استفاده از persian-date و یک کتابخانه Date Picker میلادی، خودت یه Date Picker شمسی بسازی یا از پکیج‌های آماده استفاده کنی.

این کامپوننت‌ها معمولاً خودشون از کتابخانه‌هایی مثل persian-date یا jalaali-js برای مدیریت منطق تاریخ استفاده می‌کنن و فقط کار تو رو برای نمایش و تعامل با کاربر راحت‌تر می‌کنن.

نکات مهم و بهترین روش‌ها

برای اینکه مدیریت تاریخ شمسی تو پروژه‌هات بی‌عیب و نقص باشه، این نکته‌ها رو در نظر بگیر:

• انتخاب کتابخانه مناسب: اگه فقط تبدیل ساده نیاز داری، jalaali-js سبک‌تره. اما برای فرمت‌دهی پیشرفته، محاسبات و یک راهکار جامع، persian-date بهترین انتخابه.
• مدیریت Timezone: همیشه حواست به Timezone باشه. جاوااسکریپت با UTC و زمان محلی کار می‌کنه. اگه تاریخ‌ها رو از سرور می‌گیری، مطمئن شو که Timezone درستی دارن و در صورت نیاز تبدیلشون کن. persian-date هم به صورت پیش‌فرض با زمان محلی کار می‌کنه اما می‌تونی Timezone رو هم مدیریت کنی.
• اعتبارسنجی ورودی: همیشه ورودی‌های تاریخ از کاربر رو اعتبارسنجی کن. مطمئن شو که فرمت صحیحی دارن و تاریخ معتبری هستن (مثلاً “31 بهمن” نداریم، ولی “30 بهمن” داریم).
• ثبات فرمت‌دهی: در سراسر اپلیکیشن یا وب‌سایتت، یه فرمت تاریخ ثابت و یکپارچه رو برای نمایش تاریخ شمسی انتخاب کن تا کاربر سردرگم نشه.
• کَش کردن: اگه نیاز داری بارها و بارها یه تاریخ رو به شمسی تبدیل کنی و فرمت بدی، اگه ورودی ثابت هست، نتیجه رو کَش کن تا عملکرد (performance) برنامه‌ات افت نکنه.
• به‌روزرسانی کتابخانه‌ها: کتابخانه‌هایی مثل persian-date مدام در حال به‌روزرسانی هستن. از آخرین نسخه استفاده کن تا از باگ‌فیکس‌ها و قابلیت‌های جدید بهره‌مند بشی.

اگه در مورد پیاده‌سازی این نکات یا چالش‌های پیچیده‌تر به کمک نیاز داری، می‌تونی با تیم فنی ما تماس بگیری.

عیب‌یابی سریع (Troubleshooting)

تو مسیر برنامه‌نویسی همیشه یه سری مشکل پیش میاد. اینجا به چندتا مشکل رایج و راه‌حلشون اشاره می‌کنم:

• مشکل: تاریخ شمسی اشتباه نمایش داده می‌شود یا یک روز عقب/جلو است.

  راه‌حل: این مشکل معمولاً به تفاوت Timezone (منطقه زمانی) برمی‌گرده. وقتی یک Date آبجکت جاوااسکریپتی بدون پارامترهای مشخص Timezone می‌سازی، به صورت محلی (Local Time) ایجاد میشه. اما اگر از سرور تاریخ UTC بگیری و مستقیم به PersianDate بدی، باید مطمئن بشی که تبدیل‌ها درست انجام میشن. همیشه تاریخ میلادی رو به UTC تبدیل کن و بعد به PersianDate بده، یا برعکس، مطمئن شو که داری با زمان محلی یکسانی کار می‌کنی.

  کپی// فرض کن '2023-10-26T07:30:00.000Z' از سرور اومده (UTC)
  const utcDate = new Date('2023-10-26T07:30:00.000Z');
  const pDateFromUtc = new PersianDate(utcDate); // PersianDate به طور خودکار به Timezone محلی سیستم تبدیل میکنه
  console.log(pDateFromUtc.format('YYYY/MM/DD HH:mm')); // تاریخ شمسی صحیح محلی

• مشکل: فرمت‌دهی دلخواه من با persian-date.format() کار نمی‌کند.

  راه‌حل: اولاً، حروف فرمت‌دهی (مثل YYYY، MM، DD و…) در persian-date حساس به بزرگی و کوچکی حروف هستند. مطمئن شو که از حروف درست استفاده می‌کنی. دوماً، برای برخی کاراکترهای خاص که نمی‌خوای تفسیر بشن، می‌تونی از بک‌اسلش () استفاده کنی تا Escaped بشن. مثلاً برای نمایش “MM” واقعی به جای ماه، باید بنویسی 'YYYY/MM/DD'.

  کپیconst pdate = new PersianDate();
  console.log(pdate.format('YYYY-M-D \MM')); // برای نمایش عدد ماه و سپس رشته 'MM'

• مشکل: ورودی تاریخ از فیلدهای فرم، هنگام ایجاد new PersianDate() منجر به خطای Invalid Date می‌شود.

  راه‌حل: persian-date سعی می‌کنه فرمت‌های مختلف رو تشخیص بده، اما اگه ورودی خیلی نامنظم باشه، نیاز به کمک داره. مطمئن شو که رشته ورودی تاریخ، فرمت استانداردی مثل "YYYY/MM/DD" یا "YYYY-MM-DD" داره. اگه تاریخ رو به صورت جداگانه (سال، ماه، روز) از کاربر می‌گیری، بهتره اون‌ها رو به صورت آرایه به PersianDate پاس بدی:

  کپیconst year = 1402;
  const month = 7;
  const day = 26;
  const pDate = new PersianDate([year, month, day]); // بهترین راه برای ورودی‌های تفکیک شده
  console.log(pDate.format('YYYY/MM/DD'));

نتیجه‌گیری

همونطور که دیدی، مدیریت فرمت‌های تاریخ شمسی در جاوااسکریپت دیگه یه کابوس نیست. با استفاده از کتابخانه‌های قدرتمندی مثل persian-date، می‌تونی به راحتی تاریخ‌های میلادی رو تبدیل کنی، به هر فرمتی که دوست داری نمایششون بدی، محاسبات پیچیده انجام بدی و ورودی‌های کاربر رو هم پردازش کنی. این کار نه تنها کد تو رو تمیزتر و قابل نگهداری‌تر می‌کنه، بلکه یک تجربه کاربری بی‌نظیر برای مخاطبان فارسی‌زبانت فراهم می‌آوره. پس دیگه وقتشه دست به کار بشی و این قابلیت رو به پروژه‌هات اضافه کنی.

امیدوارم این مقاله برات مفید بوده باشه و تونسته باشم بهت کمک کنم که با اعتماد به نفس بیشتری با تاریخ‌های شمسی در جاوااسکریپت کار کنی. موفق باشی رفیق!