آموزش جامع Flatpickr - انتخابگر تاریخ و زمان

📚معرفی و نصب

Flatpickr یک date picker بدون هیچ وابستگی خارجی (zero dependency) است که بدون jQuery یا هر فریم‌ورک دیگری کار می‌کند. حجم بسیار کمی دارد (~۱۶KB gzip) و در تمام مرورگرهای مدرن کار می‌کند.

✅ مزایای Flatpickr

بدون وابستگی خارجی
بسیار سبک (~۱۶KB gzip)
پشتیبانی از range و multiple
سازگار با موبایل
API کامل و انعطاف‌پذیر
۱۳۰+ locale از جمله فارسی

❌ input[type=date] مرورگر

ظاهر متفاوت در هر مرورگر
بدون امکان شخصی‌سازی
فرمت ثابت و غیرقابل تغییر
بدون پشتیبانی از range/multiple
مشکل در Safari قدیمی

نصب

<!-- ۱. CSS در <head> -->
<link rel="stylesheet" href="flatpickr.min.css">

<!-- ۲. JS قبل از </body> -->
<script src="flatpickr.min.js"></script>

مقداردهی اولیه

// ساده‌ترین روش
flatpickr("#myInput");

// با گزینه‌ها
flatpickr("#myInput", {
  dateFormat: "Y-m-d",
  defaultDate: "today"
});

// روی همه المان‌های یک کلاس
flatpickr(".date-input");

▶ دمو: اولین Date Picker

انتخاب تاریخ (پیش‌فرض)

با تاریخ پیش‌فرض امروز

📅انتخاب تاریخ پایه

توکن‌های dateFormat

توکن	توضیح	مثال
Y	سال ۴ رقمی	2025
y	سال ۲ رقمی	25
m	ماه با صفر (01–12)	05
n	ماه بدون صفر (1–12)	5
d	روز با صفر (01–31)	09
j	روز بدون صفر (1–31)	9
l	نام روز هفته کامل	Thursday
D	نام کوتاه روز هفته	Thu
F	نام کامل ماه	January
M	نام کوتاه ماه	Jan
U	Unix timestamp	1716667200

flatpickr("#myDate", {
  dateFormat: "Y-m-d",       // خروجی: 2025-05-22
  minDate:    "2025-01-01",  // حداقل تاریخ
  maxDate:    "2025-12-31",  // حداکثر تاریخ
  defaultDate: "today"       // مقدار پیش‌فرض
});

// فرمت‌های مختلف
flatpickr("#date2", { dateFormat: "d/m/Y" });    // 22/05/2025
flatpickr("#date3", { dateFormat: "D, d F Y" }); // Thu, 22 May 2025

💡 نکته: minDate: "today" به‌صورت پویا هر روز به‌روز می‌ماند. همچنین می‌توانید از Date object یا timestamp استفاده کنید.

▶ دمو: فرمت‌های مختلف

فرمت Y-m-d

فرمت d/m/Y

از امروز به بعد

⏰انتخاب زمان (Time Picker)

گزینه‌های زمانی

گزینه	نوع	توضیح
enableTime	Boolean	فعال کردن انتخاب ساعت
noCalendar	Boolean	نمایش فقط ساعت (بدون تقویم)
time_24hr	Boolean	فرمت ۲۴ ساعته
enableSeconds	Boolean	انتخاب ثانیه
minuteIncrement	Number	گام تغییر دقیقه (پیش‌فرض: ۵)
minTime / maxTime	String	محدوده زمانی

// تاریخ + زمان (DateTime)
flatpickr("#datetime", {
  enableTime: true,
  dateFormat: "Y-m-d H:i",   // H=ساعت، i=دقیقه
  time_24hr: true
});

// فقط ساعت - بدون تقویم
flatpickr("#timePicker", {
  enableTime: true,
  noCalendar: true,
  dateFormat: "H:i",
  time_24hr: true,
  defaultDate: "09:00"
});

// با ثانیه و گام ۱۵ دقیقه
flatpickr("#timeAdv", {
  enableTime: true, noCalendar: true,
  dateFormat: "H:i:S", enableSeconds: true,
  minuteIncrement: 15, time_24hr: true
});

ⓘ توکن‌های زمانی: H ساعت ۲۴ه، h ساعت ۱۲ه، i دقیقه، S ثانیه، K برای AM/PM.

▶ دمو: انتخاب زمان

تاریخ + زمان

فقط ساعت

با ثانیه (گام ۱۵')

📈بازه تاریخ (Date Range)

با mode: "range" کاربر می‌تواند یک بازه تاریخ (از–تا) انتخاب کند. ایده‌آل برای رزرو، گزارش‌گیری و جستجو.

// بازه ساده
flatpickr("#dateRange", {
  mode: "range",
  dateFormat: "Y-m-d"
});

// بازه با ۲ ماه نمایشی و callback
flatpickr("#dateRange2", {
  mode: "range",
  dateFormat: "Y-m-d",
  showMonths: 2,
  onChange: function(selectedDates) {
    if (selectedDates.length === 2) {
      const diff = Math.round(
        (selectedDates[1] - selectedDates[0]) / (1000*60*60*24)
      );
      console.log(`بازه: ${diff} روز`);
    }
  }
});

💡 دسترسی به مقادیر: مقدار input به صورت تاریخ1 to تاریخ2 ذخیره می‌شود. برای دسترسی جداگانه از selectedDates[0] و selectedDates[1] در callback استفاده کنید.

▶ دمو: انتخاب بازه تاریخ

بازه تاریخ ساده

رزرو آینده (minDate: today)

📋چند تاریخ (Multiple)

با mode: "multiple" کاربر می‌تواند چندین تاریخ غیرپیوسته انتخاب کند. کلیک مجدد روی تاریخ = حذف از لیست.

flatpickr("#multiDate", {
  mode: "multiple",
  dateFormat: "Y-m-d",
  conjunction: ", ",       // جداکننده در input

  defaultDate: ["2025-05-20", "2025-05-22"],

  onChange: function(selectedDates) {
    console.log(`انتخاب‌شده: ${selectedDates.length} تاریخ`);
  }
});

▶ دمو: انتخاب چند تاریخ

چند تاریخ (کلیک = انتخاب / کلیک مجدد = حذف)

تعداد انتخاب‌شده:

۰ تاریخ

🎨تنظیمات ظاهری

تقویم Inline

// تقویم همیشه نمایش داده می‌شود
flatpickr("#inlineDate", {
  inline: true,
  dateFormat: "Y-m-d"
});

غیرفعال کردن تاریخ‌های خاص

// غیرفعال کردن آخر هفته (شنبه=6، یکشنبه=0)
flatpickr("#noWeekend", {
  disable: [
    function(date) {
      return date.getDay() === 0 || date.getDay() === 6;
    }
  ]
});

// غیرفعال کردن تاریخ‌های مشخص و یک بازه
flatpickr("#disabledDates", {
  disable: [
    "2025-05-26",
    "2025-06-04",
    { from: "2025-06-21", to: "2025-07-01" }
  ]
});

// فقط روزهای خاص فعال باشند
flatpickr("#onlyWeekdays", {
  enable: [function(date) { return date.getDay() !== 5; }] // بجز جمعه
});

locale فارسی دستی

const faLocale = {
  weekdays: {
    shorthand: ["یک","دو","سه","چه","پن","جم","شن"],
    longhand: ["یکشنبه","دوشنبه","سه‌شنبه","چهارشنبه","پنجشنبه","جمعه","شنبه"]
  },
  months: {
    shorthand: ["ژان","فور","مار","آور","می","ژون","ژوی","اوت","سپت","اکت","نوو","دس"],
    longhand: ["ژانویه","فوریه","مارس","آوریل","می","ژوئن","ژوئیه","اوت","سپتامبر","اکتبر","نوامبر","دسامبر"]
  }
};
flatpickr("#faDate", { locale: faLocale });

▶ دمو: تنظیمات ظاهری

Inline Calendar

بدون آخر هفته

Locale فارسی

⚡رویدادها و API

رویدادهای اصلی

flatpickr("#eventDemo", {
  dateFormat: "Y-m-d",

  // هر بار که تاریخ تغییر کند
  onChange: function(selectedDates, dateStr, instance) {
    console.log("تاریخ:", dateStr);
  },

  // باز / بسته شدن تقویم
  onOpen:  function() { console.log("باز شد"); },
  onClose: function(dates, str) { console.log("بسته شد:", str); },

  // یک بار هنگام init
  onReady: function() { console.log("آماده است"); },

  // تغییر ماه/سال
  onMonthChange: function(d, s, inst) { console.log("ماه:", inst.currentMonth); },
  onYearChange:  function(d, s, inst) { console.log("سال:", inst.currentYear); }
});

کنترل برنامه‌نویسی

const fp = flatpickr("#myInput", { dateFormat: "Y-m-d" });

fp.setDate("2025-06-15");    // تنظیم تاریخ
fp.setDate(new Date());        // امروز
fp.clear();                      // پاک کردن
fp.open();                       // باز کردن
fp.close();                      // بستن
fp.destroy();                    // از بین بردن (برگشت به input عادی)
fp.set("minDate", "2025-06-01"); // تغییر گزینه بعد از init

// خواندن مقدار انتخاب‌شده
const dates = fp.selectedDates;   // آرایه Date object
const str   = fp.input.value;     // رشته فرمت‌شده

جدول خلاصه گزینه‌های اصلی

گزینه	پیش‌فرض	توضیح
dateFormat	"Y-m-d"	فرمت نمایش و ذخیره تاریخ
mode	"single"	single / multiple / range
enableTime	false	فعال کردن انتخاب ساعت
noCalendar	false	فقط نمایش ساعت
time_24hr	false	فرمت ۲۴ ساعته
inline	false	نمایش تقویم همیشه
allowInput	false	تایپ دستی تاریخ
weekNumbers	false	نمایش شماره هفته
showMonths	1	تعداد ماه‌های نمایشی
minDate / maxDate	null	محدوده قابل انتخاب
defaultDate	null	مقدار پیش‌فرض ("today" هم قبول می‌کند)
disable / enable	[]	آرایه تاریخ‌های غیرفعال/فعال

▶ دمو: رویدادها — انتخاب کنید و نتیجه را ببینید

Date Picker با رویداد onChange

تاریخ انتخاب‌شده:

هنوز انتخاب نشده

💡 الگوهای کاربردی:

رزرو هتل/پرواز: mode:"range" + minDate:"today" + showMonths:2
تاریخ تولد (ثبت‌نام): maxDate:"today" + defaultDate روی ۱۸ سال پیش
گزارش‌گیری: دو input با onChange که minDate/maxDate یکدیگر را تنظیم می‌کنند

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

روی فیلد کلیک کن تا تقویم باز شود. تنظیمات Flatpickr (حالت بازه، انتخاب زمان، چند تاریخ) را تغییر بده و ▶ اجرا را بزن. نسخهٔ ۴.۶.۱۳ آفلاین بارگذاری می‌شود.

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