کتابخانه JSS-Date یک کتابخانه جاوااسکریپتی برای کار با تاریخ و زمان است. هدف از طراحی این کتابخانه، رفع کاستیهای کتابخانههای موجود و پشتیبانی از تقویمهایی به غیر از تقویم میلادی (تقویم هجری قمری، هجری شمسی و غیره) است.
در مقاله قبلی، به اختصار وضعیت کتابخانه معروف moment.js را بررسی کردیم. از مشکلات کتابخانه moment.js می توان به موارد زیر اشاره کرد:
بعضی از کتابخانههای جاوااسکرپتی مانند کتابخانه Luxon بخشی از این مشکلات را رفع کردهاند اما همه آنها مبتنی بر تقویم میلادی هستند. کتابخانه JSS-Date با هدف رفع همه این کاستیها طراحی و ساخته شده است. هنگام طراحی این کتابخانه، موارد زیر مد نظر قرار گرفته شده است:
کتابخانه JSS-Date در ریپازیتوری npm موجود است:
npm install @js-sugar/date --save
کتابخانه JSS-Date روی سرور (node.js) و همچنین مرورگر اجرا میشود.
برای استفاده از این کتابخانه، ابتدا باید تقویمهایی که در پروژه نیاز دارید را import و معرفی کنید. این کار را در هنگام شروع پروژه (Startup) و برای یک بار انجام میدهیم.
این کتابخانه مستقل از تقویم طراحی شده است، به این معنا که هیچ تفاوتی بین تقویم میلادی و بقیه تقویم ها وجود ندارد. زمانی که یک شی DateTime ساخته میشود، پارامتر تقویم به سازنده آن شی داده میشود. در ادامه به نحوه ساخت اشیا تاریخ خواهیم پرداخت. فعلا فقط باید مشخص کنیم که در پروژه مان با چه تقویم هایی سر و کار داریم:
import { Calendars } from '@js-sugar/date'; import { GregorianCalendar } from '@js-sugar/date/calendars/gregorian'; import { PersianCalendar } from '@js-sugar/date/calendars/persian'; import { HijriCalendar } from '@js-sugar/date/calendars/hijri'; Calendars.add(new GregorianCalendar('gregorian')); Calendars.add(new PersianCalendar('persian')); Calendars.add(new HijriCalendar ('hijri'));
به ازای هر تقویم، یک کلاس مجزا وجود دارد. در اینجا کلاسهای GregorianCalendar ،PersianCalendar و HijriCalendar را import کردهایم. تنها کاری که باید انجام دهیم این است که از هر تقویم یک شی بسازیم و به مجموعه تقویم های پروژه ( کلاس Calendars) اضافه کنیم.
هر تقویم یک شناسه یکتا (ID) در سرتاسر پروژه دارد که در هنگام ساخت تقویم به سازنده (constructor) آن داده میشود. بعد از ساخت اشیا Calendar، آنها را به مجموعه تقویم های پروژه (کلاس Calendars) اضافه میکنیم. اولین تقویمی که به مجموعه Calendars اضافه میشود، تقویم پیش فرض پروژه خواهد بود.
همه تقویمها از کلاس پایه Calendar به ارث میبرند. شما به راحتی میتوانید تقویم خودتان را پیاده سازی کنید فقط باید چند متد abstract را پیاده سازی کنید.
پیکربندی کتابخانه را تنها در هنگام startup پروژه انجام میدهیم. بعد از آن فقط به سادگی اشیا DateTime را تولید و استفاده میکنیم. اگر از فریمورکهای جاوااسکریپتی مانند Angular یا React استفاده میکنید، مطمئن شوید که کد مربوط به افزودن تقویم ها به کلاس Calendars فقط یک بار اجرا میشود.
در تمامی مثالهای این مقاله فرض شده است که یک تقویم میلادی (با شناسه gregorian)، یک تقویم شمسی (با شناسه persian) و یک تقویم هجری قمری (با شناسه hijri) به پروژه اضافه شده است.
شی اصلی کتابخانه JSS-Date شی DateTime است. این شی مقدار تاریخ و زمان (با توجه به یک تقویم خاص) را در خود نگهداری میکند. شی DateTime به 3 پارامتر وابستگی دارد:
در هنگام ساخت یک شی DateTime، مقدار تقویم، لوکل و منطقه زمانی آن مشخص میشود (صراحتا و یا ضمنی) و بعد از آن به هیچ عنوان تغییر نمیکند. در واقع شی DateTime یک شی Immutable است و بعد از ساخته شدن، به هیچ عنوان تغییر نمیکند.
در ادامه با نحوه ایجاد و استفاده از اشیا DateTime آشنا خواهید شد.
مثال: ساخت یک DateTime که تقویم آن شمسی و مقدار آن برابر زمان جاری سیستم است:
import { DateTime } from '@js-sugar/date'; const pc = Calendars.find('persian'); // find a Calendar by its ID const d = new DateTime({calendar: pc}); console.log(d.year, d.month, d.day, d.hour, d.minute, d.second, d.ms); // output will be something like this: 1400, 5, 29, 12, 55, 50, 223
در مثال بالا، ابتدا تقویم فارسی را با متد find از مجموعه تقویمهای پروژه جستجو کردهایم و سپس آن را به سازنده کلاس DateTime دادهایم. یک راه سادهتر برای ساخت اشیا DateTime به صورت زیر است:
const d = new DateTime({calendar: 'persian'});
در کد بالا، شناسه (ID) تقویم را به صورت مستقیم به سازنده DateTime دادهایم. در این حالت، شی DateTime تقویم مربوطه را از میان تقویمهای پروژه (Calendars) جستجو و پس از یافتن از آن استفاده خواهد کرد.
مثال: ساخت یک DateTime با تقویم شمسی و یک مقدار مشخص:
import { DateTime } from '@js-sugar/date'; const d = new DateTime({calendar: 'persian'}, 1400, 8, 21); console.log(d.year, d.month, d.day, d.hour, d.minute, d.second, d.ms); // output: 1400, 8, 21, 0, 0, 0, 0
مثال: ساخت یک DateTime با تقویم میلادی و یک مقدار مشخص:
import { DateTime } from '@js-sugar/date'; const d = new DateTime({calendar: 'gregorian'}, 2020, 10, 27); console.log(d.year, d.month, d.day); // output: 2020, 10, 27
مثال: ساخت یک DateTime با تقویم پیش فرض و زمان جاری سیستم:
import { DateTime } from '@js-sugar/date'; const d = new DateTime(); console.log(d.year, d.month, d.day); // The output depends on the default Calendar of the project
اولین تقویمی که به کلاس Calendars اضافه میشود، تقویم پیش فرض پروژه خواهد شد. اگر بعدا تصمیم به تغییر تقویم پیشفرض پروژه داشتید، به این روش میتوانید تقویم پیشفرض را تغییر دهید:
import { Calendars } from '@js-sugar/ Calendars.default = Calendars.find('hijri');
جهت سهولت ایجاد اشیا DateTime، سازنده این کلاس دارای چندین overload است:
DateTime(); DateTime(options); DateTime(year, month, day?, hour?, minute?, second?, ms?, options?); DateTime(options, year, month, day?, hour?, minute?, second?, ms?); DateTime(timestamp, options?);
پارامترهایی که اختیاری هستند با یک علامت سوال (?) مشخص شدهاند. اگر پارامتری مشخص نشود، از مقادیر پیشفرض استفاده خواهد شد. مقدار پیشفرض برای پارامتر روز برابر 1 و برای پارامترهای ساعت، دقیقه، ثانیه و میلی ثانیه برابر 0 است.
پارامتر اختیاری options یک شی با سه فیلد اختیاری است:
{ calendar?: string | Calendar, locale?: string | Locale, zone?: string | Zone }
با استفاده از این پارامتر، میتوانید تقویم، locale و zone شی DateTime را مشخص کنید. اگر این مقادیر را مشخص نکنید، از مقادیر پیشفرض استفاده خواهد شد.
مثال: ساخت یک شی DateTime با تقویم شمسی و locale فارسی
const d = new DateTime({calendar: 'persian', locale: 'fa-IR'}, 1400, 9, 2);
تبدیل کردن یک DateTime به یک DateTime متناظر با آن ولی با تقویمی متفاوت، بسیار آسان است. برای این کار از متد to شی DateTime استفاده میکنیم.
متد to، یک شی Calendar و یا شناسه یک Calendar (که به مجموعه تقویمهای پروژه اضافه شده است) را میگیرد و یک DateTime جدید و معادل با تقویم مورد نظر را ایجاد میکند.
مثال: تبدیل یک DateTime با تقویم میلادی به یک DateTime با تاریخ شمسی معادل با آن
const d1 = new DateTime({calendar: 'gregorian'}, 2021, 11, 25); const d2 = d1.to('persian'); // OR ==> d2 = d1.to(Calendars.find('persian')); console.log(d2.year, d2.month, d2.day); // output: 1400, 9, 4
مثال: تبدیل یک DateTime با تقویم شمسی به یک DateTime با تاریخ میلادی معادل با آن
const d1 = new DateTime({calendar: 'persian'}, 1400, 9, 4); const d2 = d1.to('gregorian'); // OR ==> d2 = d1.to(Calendars.find('gregorian')); console.log(d2.year, d2.month, d2.day); // output: 2021, 11, 25
برای گزارش باگ یا ثبت درخواست برای افزودن قابلیت جدید، به ریپازیتوری پروژه JSS-Date مراجعه کنید:
https://github.com/js-sugar/date
در مقالههای بعدی، شما را بیشتر با قابلیتهای کتابخانه JSS-Date آشنا خواهیم کرد.
مقالاتی که تا کنون در رابطه با کتابخانه جاوااسکریپتی JSS-Date منتشر کرده ایم:
ریپازیتوری پروژه (جهت ثبت باگ و درخواست افزودن قابلیتهای جدید):
https://github.com/js-sugar/date
مستندات پروژه:
https://js-sugar.github.io/date