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

تاریخ‌ها و زمان‌ها به روش‌های مختلفی توسط فرهنگ‌های مختلف در سراسر جهان نمایش داده می‌شوند. این شامل تفاوت‌ در سیستم‌های تقویمی، مناطق زمانی (Timezone)، قوانین ساعت تابستانی(Daylight Saving)، فرمت‌بندی تاریخ و زمان، قوانین روزهای هفته و آخر هفته و بسیاری موارد دیگر است. هنگام ساخت برنامه‌هایی که از کاربران در سراسر جهان پشتیبانی می‌کنند، بسیار مهم است که این جنبه‌ها را برای هر منطقه به درستی مدیریت کنیم. در ادامه به معرفی بهترین کتابخانه تاریخ شمسی در جاوا اسکریپت می پردازیم.

@internationalized/date بهترین کتابخانه تاریخ شمسی در جاوا اسکریپت

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

به طور پیش‌فرض، JavaScript تاریخ و زمان‌ را با استفاده از شی Date نمایش می‌دهد. با این حال، Date مشکلات زیادی دارد، از جمله API بسیار دشوار برای استفاده، عدم پشتیبانی کامل از Internationalization (تبدیل شی تاریخ به رشته ترجمه شده در زبان مختلف) و موارد دیگر.

پروپوزالTemporal در نهایت این موضوع را در زبان JavaScript  حل خواهد کرد ولی تا زمانی که اینپروپوزال تایید شده و بر روی مرورگر و Runtime های مختلف JavaScript پیاده سازی شود، کمی طولخواهد کشید.

ویژگی‌های کلیدی@internationalized/date

در ابتدا به بررسی ویژگی های کلیدی این کتابخانه می پردازیم.

• پشتیبانی کامل از انواع تاریخ و زمان - این کتابخانه، برای ذخیره و دستکاری تاریخ، چندین کلاس مختلف ارائه داده است. این کلاس ها در ادامه شرح داده خواهند شد.
• تقویم‌های بین‌المللی - پشتیبانی از بیش از ۱۳ سیستم تقویمی مختلف که در سراسر جهان استفاده می‌شود.
• متد های دستکاری - امکان اضافه یا کم کردن مدت زمان، تنظیم فیلدها و غیره.
• متد های تبدیل - امکان تبدیل بین سیستم‌های تقویمی، مناطق زمانی و نمایش‌های متنی.
• تعریف Query - مکان مقایسه تاریخ‌ها برای ترتیب‌دهی یا بررسی برابری.

انواع کلاس های Expose شده از کتابخانه

• (CalendarDate) – یک شیء غیرقابل تغییر که یک تاریخ را در یک سیستم تقویمی خاص ذخیره می‌کند، بدون هیچ‌گونه اجزای زمانی. مثل تاریخ ۱۴۰۳/۱/۱ در تقویم شمسی
• (CalendarDateTime) – یک شیء غیرقابل تغییر که یک تاریخ و زمان را بدون منطقه زمانی در یک سیستم تقویمی خاص نمایش می‌دهد. مثل تاریخ-زمان ۱۲:۱۶:۳۲ ۱۴۰۳/۱/۱ در تقویم شمسی
• (ZonedDateTime) – یک شیء غیرقابل تغییر که یک تاریخ و زمان را در یک منطقه زمانی خاص و سیستم تقویمی خاص نمایش می‌دهد. مثل تاریخ-زمان ۱۲:۱۶:۳۲ ۱۴۰۳/۱/۱ در تقویم شمسی به وقت تهران (Asia/Tehran)
• زمان (Time) – یک شیء غیرقابل تغییر که زمان ساعت را بدون هیچ‌گونه اجزای تاریخ ذخیره می‌کند.مثل ساعت ۱۸:۲۳:۴۷

استفاده از @internationalized/date با تقویم فارسی

برای کار با تقویم فارسی با استفاده از این کتابخانه، چندین مثال ارائه می شود.

مثال ساده ساخت اولین تاریخ با کتابخانه تاریخ شمسی در جاوا اسکریپت

برای ساخت یک Calendar Date (تقویم بدون زمان)، کد زیر را بنویسید.

import {CalendarDate} from '@internationalized/date';
let date = new CalendarDate(2022, 2, 3);
date.toString(); // '2022-02-03'

این تاریخ، به طور پیش فرض در تقویم میلادی است. برای ساخت تاریخ در تقویم شمسی (فارسی) کد را به شکل زیر تغییر دهید.

import { CalendarDate, PersianDate } from '@internationalized/date';
let date = new CalendarDate(new PersianCalendar(), 1403, 3, 5);
date.toString() // '2024-05-25'

همانطور که می بینید، خروجی به شکل میلادی چاپ شده است اما تبدیل به شکل صحیح از تقویم شمسی به میلادی، انجام شده است.

برای اینکه بتوان تاریخ را به شکل شمسی چاپ کرد، نیاز است که از قابلیت Internationalization این کتابخانه، استفاده کنیم. به مثال بعدی توجه کنید.

import {CalendarDate, DateFormatter, PersianCalendar} from '@internationalized/date';
const formatter = new DateFormatter("fa")
let date = new CalendarDate(new PersianCalendar(), 1403, 3, 5);
formatter.format(date.toDate("UTC")) // '۱۴۰۳/۳/۵'

در این مثال، یک DateFormatter تعریف کرده و به آن یک Locale ارائه شده است. Locale خروجی که می خواهیم چاپ کنیم، فارسی است. پس از حالت ISO آن برای زبان فارسی یعنی ‘fa’ استفاده می کنیم. سپس برای چاپ آن، ابتدا تاریخ را به Date در Javascript تبدیل کرده و سپس به کمک تابع Format از DateFormatter، چاپ می کنیم.

مثال ساده ساخت تاریخ از شی Date در JavaScript

تا کنون با CalendarDate کار کردیم، کار با CalendarDateTime نیز مشابه مثال های قبلی است، با این تفاوت که باید برای ساخت آن ساعت، دقیقه ثانیه و میلی ثانیه نیز ارائه شود.

برای ساخت یک تاریخ تقویم دار با پشتیبانی از Timezone های مختلف (یعنی کامل ترین شی تاریخ ممکن) از کلاس ZonedDateTime استفاده می کنیم. برای ساخت یک شی از این جنس با ورودی JavaScript Date از تابع fromDate استفاده می کنیم.

import { DateFormatter, fromDate } from '@internationalized/date';
const
formatter = new DateFormatter("fa", { 
    dateStyle: "short",
    timeStyle: "medium"
})
let date = fromDate(new Date(), 'UTC');
formatter.format(date.toDate()) // '۱۴۰۳/۱۱/۲۰, ۱۲:۴۸:۰۹'

به تنظیمات DateFormatter دقت کنید، این تنظیمات به Formatter در رابطه با چگونگی نمایش تاریخ، کمک می کند. برای پافتن تمامی تنظیمات ممکن به مستند MDN در رابطه با شی Intl.DateTimeFormat  مراجعه کنید.

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

در اینجا مقایسه‌ای از @internationalized/date  با سایر کتابخانه‌های محبوب، شامل اندازه و کامل بودن ویژگی‌ها آورده شده است:

Moment js

Moment js به دلیل ویژگی‌های جامع و سهولت استفاده، زمانی محبوب ترین کتابخانه برای مدیریت تاریخ‌ها در JavaScript بود. با این حال، به دلیل مشکلات عملکردی و عدم نگهداری، منسوخ شده است. در حالی که برخی از پشتیبانی‌های بین‌المللی را از طریق پلاگین‌هایی مانند  moment-timezone و moment-locales  ارائه می‌دهد، دیگر برای پروژه‌های جدید توصیه نمی‌شود مگر اینکه کاملاً ضروری باشد.

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

Luxon به عنوان جایگزینی مدرن برای Moment.js طراحی شده است که بر عملکرد و سادگی تأکید دارد و در عین حال عملکرد قوی دارد. این کتابخانه پشتیبانی عالی از زبان‌ها و مناطق مختلف ارائه می‌دهد و شیء DateTime  آن می‌تواند به راحتی مطابق با Localeمختلف فرمت شود اما تبدیل تاریخ و پشتیبانی از تقویم شمسی در آن وجود ندارد.

کتابخانه تاریخ شمسی در جاوا اسکریپت Date-fns

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

intl/Date (@internationalized/Date)

این پکیج به طور خاص بر ارائه ابزارهایی متمرکز است که برای مدیریت سیستم‌های تقویمی متنوع در سطح جهانی طراحی شده است—که آن را برای برنامه‌هایی که نیاز به کنترل دقیق بر نمایش تاریخ‌ها در Locale مختلف دارند، ایده‌آل می‌کند.

با توجه به سایز کوچک، این کتابخانه می تواند جایگزین بسیاز مناسبی برای کتاب خانه های مختلف کار با تقویم و تاریخ فارسی باشد. اگرچه Moment.js جامع است اما منسوخ شده است، Luxon  جایگزین خوبی است اما پشتیبانی کاملی از تقویم شمسی ندارد، و Date-fns سبک وزن اما محدودیت‌هایی دارد.در نهایت تا زمانی که پروپوزال Temporal پیاده‌سازی شود، استفاده از کتابخانه‌هایی مانند @intl/Date بهترین گزینه برای مدیریت تاریخ و زمان در برنامه‌های چند Locale خواهد بود.

حال که با بهترین کتابخانه تاریخ شمسی در جاوا اسکریپت آشنا شدید، می توانید از دیگر مقالات سایت ایوولرن دیدن کنید.