کتابخانه جاوااسکریپت JSS-Date: کلاس DateTime

در مقاله قبل، شما را با کتابخانه جاوااسکریپتی JSS-Date آشنا کردیم. در این مقاله می‌خواهیم بیشتر در مورد شی اصلی این کتابخانه یعنی DateTime صحبت کنیم.

شی DateTime همانند شی Date در جاوااسکریپت، مشخص کننده یک تاریخ و زمان خاص است. هنگام ساخت این شی می‌توانید (به صورت اختیاری) تقویم، time-zone و locale را مشخص کنید:

const d = new DateTime({
    calendar: 'persian',
    zone: 'Asia/Tehran',
    locale: 'fa'
}, 1400, 11, 1);

در صورتی که یکی از پارامترهای تقویم، time-zone و locale را مشخص نکنید، از مقادیر پیش فرض استفاده خواهد شد (مقاله قبلی را بخوانید).

در ادامه، متدها و فیلدهای کلاس DateTime را شرح می‌دهیم:

• فیلدهای ms ،second ،minute ،hour ،day ،month ،year
  به ترتیب مقادیر سال، ماه، روز، ساعت، دقیقه، ثانیه و میلی ثانیه را مشخص می‌کنند.
• فیلد ts
  تعداد میلی ثانیه های سپری شده از یک مبدا زمانی را نشان می‌دهد. مقدار و معنی این فیلد بستگی به پیاده سازی شی Calendar دارد.
• فیلد config
  یک شی که مقادیر Calendar, Locale و Zone را مشخص می‌کند. برای هر شی DateTime این سه مقدار حتما غیر null هستند (مقدار دارند).

{
  calendar: Calendar,
  locale: Locale,
  zone: Zone
}

• فیلد calendar
  تقویم (Calendar) مورد استفاده توسط این DateTime را برمی گرداند.
• فیلد locale
  لوکل (Locale) مورد استفاده توسط این DateTime را برمی گرداند.
• فیلد zone
  منطقه زمانی (Zone) مورد استفاده توسط این DateTime را برمی گرداند.
• متد ()date
  یک DateTime معادل با این شی ایجاد می‌کند ولی مقدار ساعت، دقیقه، ثانیه و میلی ثانیه آن را با صفر مقداردهی می‌کند.
• متد ()to
  یک DateTime معادل با این شی و با تقویم مشخص شده را ایجاد می‌کند. با استفاده از این متد می‌توانید به سادگی تاریخ ها را از یک تقویم به تقویم دیگر تبدیل کنید (مثلا از میلادی به شمسی).

const d1 = new DateTime({calendar: 'gregorian'}, 2022, 1, 21);

const d2 = d1.to('persian');
console.log(d2.year, d2.month, d2.day); // 1400, 11, 1

const d3 = d2.to('hijri');
console.log(d3.year, d3.month, d3.day); // 1443, 6, 18

• متد ()toZone
  یک DateTime معادل با این شی و با Zone مشخص شده را ایجاد می‌کند. با استفاده از این متد می‌توانید منطقه زمانی را تغییر دهید:

const d1 = new DateTime({zone: Zones.utc}, 2022, 1, 21, 0, 0, 0, 0); 
// hour=minute=second=ms=0

const d2 = d1.toZone(Zones.iana('Asia/Tehran'));
console.log(d2.hour, d2.minute, d2.second); // 3, 30, 0

• متد ()toLocale
  یک DateTime معادل با این شی و با Locale مشخص شده ایجاد می‌کند. زمانی که یک DateTime را به رشته تبدیل می‌کنید(مثلا به کمک پلاگین format) ، نام روزهای هفته، ماه و نوع نمایش اعداد با توجه به Locale مشخص می‌شود:

import { format } from '@js-suger/date/plugins/format';

const d1 = new DateTime({locale: 'fa', calendar: 'persian'}, 1400, 1, 1);
console.log(format(d1, 'MMMM')); // فروردین

const d2 = d1.toLocale('en');
console.log(format(d2, 'MMMM')); // Farvardin

• متد ()toLocal

یک DateTime معادل با این شی و با Zone محلی ایجاد می‌کند. این متد منطقه زمانی شی را به منطقه زمانی محلی (منطقه زمانی کامپیوتری که برنامه روی آن اجرا می‌شود) تغییر می‌دهد.

const d1 = new DateTime({zone: Zones.utc});
const d2 = d1.toLocal(); // d2 would be in your local time zone

• متد ()toUtc

یک DateTime معادل با این شی و با منطقه زمانی UTC ایجاد می‌کند. این متد منطقه زمانی شی را به منطقه زمانی UTC تغییر می‌دهد.

const d1 = new DateTime({zone: Zones.local});
const d2 = d1.toUtc(); // d2 would be in UTC time zone

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

مقالاتی که تا کنون در رابطه با کتابخانه جاوااسکریپتی JSS-Date منتشر کرده ایم:

• بازنشستگی کتابخانه Moment.js
• کتابخانه جاوااسکریپت JSS-Date: معرفی
• کتابخانه جاوااسکریپت JSS-Date: کلاس DateTime

ریپازیتوری پروژه (جهت ثبت باگ و درخواست افزودن قابلیت‌های جدید):
https://github.com/js-sugar/date

مستندات پروژه:
https://js-sugar.github.io/date