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

📚معرفی و نصب

Moment.js محبوب‌ترین کتابخانه کار با تاریخ و زمان در جاوااسکریپت است. با وجود اینکه در پروژه‌های جدید Day.js توصیه می‌شود، Moment هنوز در میلیون‌ها پروژه استفاده می‌شود و دانستن آن ضروری است.

<!-- با locales (پشتیبانی از همه زبان‌ها) -->
<script src="moment-with-locales.min.js"></script>

<!-- فقط انگلیسی (سبک‌تر) -->
<script src="moment.min.js"></script>

ساعت زنده

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

// تاریخ فعلی
moment()

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

// با فرمت مشخص
moment('15/03/2024', 'DD/MM/YYYY')
moment('1402-12-25', 'YYYY-MM-DD')

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

// از Date
moment(new Date())

// اعتبارسنجی
moment('2024-03-15').isValid()  // true
moment('foo').isValid()          // false

// تبدیل برگشتی
moment().toDate()        // Date object
moment().toISOString()  // ISO string
moment().valueOf()       // timestamp ms
moment().unix()          // timestamp ثانیه

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

📋Get و Set

const m = moment('2024-03-15T14:30:45');

// Get
m.year()         // 2024
m.month()        // 2  (از 0 — مارس = 2)
m.date()         // 15 (روز ماه)
m.day()          // 5  (جمعه — 0=یکشنبه)
m.hour()         // 14
m.minute()       // 30
m.second()       // 45
m.daysInMonth()  // 31
m.dayOfYear()    // روز سال
m.week()         // شماره هفته سال

// Set (زنجیری)
moment().year(2025).month(0).date(1).format('YYYY-MM-DD')
// → "2025-01-01"

➕Add و Subtract

const now = moment();

// اضافه کردن
now.add(7, 'days')       // یا 'd'
now.add(2, 'months')     // یا 'M'
now.add(1, 'year')        // یا 'y'
now.add(3, 'hours')       // یا 'h'
now.add(30, 'minutes')    // یا 'm'

// کم کردن
now.subtract(1, 'week')
now.subtract(6, 'months')

// startOf / endOf
now.startOf('day')    // ۰۰:۰۰:۰۰ امروز
now.endOf('day')      // ۲۳:۵۹:۵۹ امروز
now.startOf('month')  // اول ماه
now.endOf('month')    // آخر ماه
now.startOf('year')   // اول سال

// ⚠️ Moment مutable است! برای کپی:
const copy = now.clone().add(7, 'days');

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

const a = moment('2024-01-01');
const b = moment('2024-06-15');

a.isBefore(b)             // true
b.isAfter(a)              // true
a.isSame(b)               // false
a.isSame(b, 'year')       // true (هر دو ۲۰۲۴)
a.isBetween('2023-01-01', '2025-01-01') // true
a.isSameOrBefore(b)        // true

// اختلاف
b.diff(a, 'days')          // 166
b.diff(a, 'months')        // 5
b.diff(a, 'years', true)   // 0.454 (اعشاری)

// اعتبارسنجی
moment('2024-02-30').isValid()  // false
moment('not-a-date').isValid()  // false

🕐Relative Time

// از الان
moment('2020-01-01').fromNow()         // "4 years ago"
moment().add(3, 'days').fromNow()     // "in 3 days"

// نسبت به تاریخ دیگر
moment('2024-06-01').from('2024-01-01')  // "5 months later"

// بدون پیشوند "ago"
moment('2020-01-01').fromNow(true)     // "4 years"

// با locale فارسی
moment.locale('fa');
moment('2020-01-01').fromNow()  // "۴ سال پیش"

🏳Locale و فارسی

// تنظیم locale سراسری
moment.locale('fa');
moment().format('MMMM D, YYYY')   // "فروردین ۱۴, ۱۴۰۳"
moment().format('dddd')            // "شنبه"
moment().fromNow()                // "چند ثانیه پیش"

// locale فقط برای یک instance
moment().locale('ar').format('MMMM')  // عربی

// برگشتن به انگلیسی
moment.locale('en');

// لیست locale های موجود
moment.locales()  // آرایه همه locale ها

⏳Duration

// ساخت Duration
const d = moment.duration(2, 'hours');
const d2 = moment.duration({ hours:1, minutes:30, seconds:45 });

// خواندن مقادیر
d.hours()        // 2
d.asMinutes()   // 120
d.asSeconds()   // 7200
d.humanize()    // "2 hours"

// Duration از diff
const diff = moment.duration(
  moment('2024-12-31').diff(moment())
);
diff.humanize()   // "a few months"
diff.days()       // روزهای باقیمانده
diff.hours()      // ساعت‌های باقیمانده

// جمع duration ها
d.add(30, 'minutes').asHours()  // 2.5

🔥نکات مهم

Mutable بودن Moment

// ⚠️ خطرناک — same object تغییر می‌کند
const a = moment();
const b = a.add(7, 'days');  // a هم تغییر کرد!

// ✓ درست — clone بگیرید
const a = moment();
const b = a.clone().add(7, 'days');

مقایسه Moment در مقابل Day.js

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

کد Moment.js را اجرا کن و خروجی را در پنل کنسول ببین. parse/format، add/subtract و locale فارسی را امتحان کن. نسخهٔ ۲.۳۰.۱ (همراه locales) آفلاین بارگذاری می‌شود.