آموزش جامع Day.js

📦معرفی و مقایسه

Day.js یک کتابخانه فوق‌العاده سبک (~۲KB gzip) برای کار با تاریخ و زمان است که API مشابه Moment.js دارد اما immutable و tree-shakable است.

ساعت زنده

🔧Parse و ساخت تاریخ

// تاریخ فعلی
const now = dayjs();

// از رشته ISO
dayjs('2024-03-15')
dayjs('2024-03-15T14:30:00')
dayjs('2024-03-15T14:30:00Z')     // UTC

// از timestamp
dayjs(1710504000000)              // میلی‌ثانیه
dayjs.unix(1710504000)            // ثانیه (Unix)

// از Date object
dayjs(new Date(2024, 2, 15))      // month از 0 شروع می‌شود!

// کپی (Day.js immutable است)
const d1 = dayjs();
const d2 = d1.clone();              // کپی مستقل

// بررسی اعتبار
dayjs('not-a-date').isValid()    // false
dayjs('2024-03-15').isValid()   // true

// تبدیل برعکس
dayjs().toDate()                  // به Date object
dayjs().toISOString()            // به ISO string
dayjs().valueOf()                 // timestamp میلی‌ثانیه
dayjs().unix()                    // timestamp ثانیه

🎨Format — جدول کامل توکن‌ها

جدول توکن‌ها

Format Builder — تعاملی

📋Get و Set — خواندن و تنظیم

Get — خواندن مقادیر

const d = dayjs('2024-03-15T14:30:45');

d.year()          // 2024
d.month()         // 2 (مارس = ماه سوم، اما از 0 شروع می‌شود)
d.date()          // 15 (روز ماه)
d.day()           // 5 (جمعه — 0=یکشنبه, 6=شنبه)
d.hour()          // 14
d.minute()        // 30
d.second()        // 45
d.millisecond()   // 0
d.daysInMonth()   // 31 (روزهای ماه مارس)

Set — تنظیم مقادیر (immutable — نسخه جدید برمی‌گرداند)

d.set('year', 2025)
d.set('month', 5)       // ماه ۶ (ژوئن) — از 0 شروع می‌شود
d.set('date', 1)
d.set('hour', 9)

// زنجیره‌سازی
dayjs()
  .set('year', 2025)
  .set('month', 0)
  .set('date', 1)
  .format('YYYY-MM-DD');  // "2025-01-01"

// شکل متد (shorthand)
d.year(2025)    // setter
d.month(0)     // setter
d.date(1)      // setter

➕Add و Subtract

const now = dayjs();

// اضافه کردن
now.add(7, 'day')         // ۷ روز بعد (کوتاه: 'd')
now.add(2, 'month')       // ۲ ماه بعد (کوتاه: 'M')
now.add(1, 'year')        // سال آینده (کوتاه: 'y')
now.add(3, 'hour')        // ۳ ساعت بعد (کوتاه: 'h')
now.add(30, 'minute')     // ۳۰ دقیقه بعد (کوتاه: 'm')

// کم کردن
now.subtract(1, 'week')   // هفته پیش (کوتاه: 'w')
now.subtract(6, 'month')  // ۶ ماه پیش

// startOf / endOf — ابتدا و انتهای دوره
now.startOf('day')        // امروز ۰۰:۰۰:۰۰
now.endOf('day')          // امروز ۲۳:۵۹:۵۹
now.startOf('month')      // اول ماه
now.endOf('month')        // آخر ماه
now.startOf('year')       // اول سال
now.startOf('week')       // اول هفته (یکشنبه)

// زنجیره‌سازی
dayjs()
  .add(1, 'month')
  .startOf('month')
  .format('YYYY-MM-DD'); // اول ماه آینده

⚖مقایسه و اعتبارسنجی

const d1 = dayjs('2024-01-01');
const d2 = dayjs('2024-06-15');

// مقایسه پایه
d1.isBefore(d2)             // true
d2.isAfter(d1)              // true
d1.isSame(d2)               // false
d1.isSame('2024-01-01')     // true
d1.isSame(d2, 'year')       // true (هر دو ۲۰۲۴ هستند)
d1.isSame(d2, 'month')      // false

// اختلاف (diff)
d2.diff(d1, 'day')          // 166
d2.diff(d1, 'month')        // 5
d2.diff(d1, 'year', true)   // 0.454... (با اعشار)

// اعتبارسنجی
dayjs('2024-03-15').isValid()  // true
dayjs('foo').isValid()          // false
dayjs('2024-02-30').isValid()  // false (فوریه ۳۰ روز ندارد)

// isBetween (نیاز به پلاگین isBetween)
// dayjs('2024-03-01').isBetween(d1, d2) // true

🕐Relative Time

برای نمایش "چند دقیقه پیش" یا "۳ ماه دیگر"، پلاگین relativeTime باید فعال شود. در این صفحه نسخه فارسی دستی پیاده‌سازی شده است.

// با پلاگین relativeTime (بعد از npm install dayjs)
import relativeTime from 'dayjs/plugin/relativeTime'
dayjs.extend(relativeTime)

dayjs().from(dayjs('2024-01-01'))   // "a few months ago"
dayjs('2025-12-01').fromNow()        // "in X months"
dayjs().toNow()                       // "a few seconds ago"
dayjs('2020-01-01').toNow(true)     // بدون "ago" پیش/دیگر

🔌پلاگین‌های مهم

Day.js به‌صورت پیش‌فرض سبک است. قابلیت‌های اضافی با پلاگین اضافه می‌شوند:

نحوه استفاده در NPM

import dayjs from 'dayjs'
import relativeTime  from 'dayjs/plugin/relativeTime'
import utc           from 'dayjs/plugin/utc'
import timezone      from 'dayjs/plugin/timezone'
import isBetween     from 'dayjs/plugin/isBetween'
import fa            from 'dayjs/locale/fa'

dayjs.extend(relativeTime)
dayjs.extend(utc)
dayjs.extend(timezone)
dayjs.extend(isBetween)
dayjs.locale('fa')

// مثال‌ها
dayjs().tz('Asia/Tehran').format('HH:mm')
dayjs('2024-03-01').isBetween('2024-01-01', '2024-12-31') // true

⏳Duration و Countdown

با محاسبه diff می‌توانید یک Countdown (شمارش معکوس) بسازید — بدون نیاز به پلاگین Duration.

// محاسبه Countdown
function getCountdown(targetDate) {
  const target = dayjs(targetDate);
  const now    = dayjs();

  const totalSeconds = target.diff(now, 'second');
  if (totalSeconds < 0) return null;

  const days    = target.diff(now, 'day');
  const hours   = target.diff(now, 'hour')   % 24;
  const minutes = target.diff(now, 'minute') % 60;
  const seconds = target.diff(now, 'second') % 60;

  return { days, hours, minutes, seconds };
}

// هر ثانیه آپدیت کن
setInterval(() => {
  const cd = getCountdown('2025-03-21'); // نوروز ۱۴۰۴
  if (cd) updateDisplay(cd);
}, 1000);

محاسبه سن

function calculateAge(birthDate) {
  const birth = dayjs(birthDate);
  const now   = dayjs();
  const years   = now.diff(birth, 'year');
  const months  = now.diff(birth, 'month')  % 12;
  const days    = now.diff(birth.add(years, 'year').add(months, 'month'), 'day');
  return `${years} سال، ${months} ماه و ${days} روز`;
}

🏳Locale و فارسی

Day.js از بیش از ۱۳۰ locale پشتیبانی می‌کند. برای نمایش نام ماه‌ها و روزها به فارسی، locale fa را بارگذاری کنید.

// NPM — بارگذاری locale فارسی
import 'dayjs/locale/fa'
dayjs.locale('fa')

dayjs().format('MMMM')          // "فروردین" یا "Esfand"
dayjs().format('dddd')          // "شنبه" یا "دوشنبه"

// locale فقط برای یک instance
dayjs().locale('fa').format('MMMM D, YYYY')

// CDN — بارگذاری locale از اینترنت
// <script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/fa.js"></script>
// dayjs.locale('fa')

// نمایش تقویم فارسی — نیاز به jalali-dayjs دارد
// import jalali from 'jalali-dayjs'
// dayjs.extend(jalali)
// dayjs().calendar('jalali').format('YYYY/MM/DD') // ← تاریخ شمسی

📅تقویم و پروژه کامل

با ترکیب قابلیت‌های Day.js می‌توانید یک تقویم کامل بسازید:

کد تقویم

function renderCalendar(current) {
  const firstDay  = current.startOf('month');
  const lastDay   = current.endOf('month');
  const startDow  = firstDay.day();   // روز هفته اول ماه (0=یکشنبه)
  const daysCount = lastDay.date();   // تعداد روزهای ماه
  const today     = dayjs();

  // روزهای ماه قبل برای پر کردن
  const prevDays = startDow;
  for (let i = prevDays - 1; i >= 0; i--) {
    const d = firstDay.subtract(i + 1, 'day');
    // نمایش با کلاس other-month
  }

  // روزهای این ماه
  for (let d = 1; d <= daysCount; d++) {
    const date    = current.date(d);
    const isToday = date.isSame(today, 'day');
    // نمایش با کلاس today اگر امروز باشد
  }
}

🚀زمین بازی کد (Playground)

کد Day.js را همین‌جا اجرا کن و خروجی را در پنل کنسول ببین. parse/format، add/subtract و مقایسه را امتحان کن. نسخهٔ ۱.۱۱.۱۰ آفلاین بارگذاری می‌شود.