از انتخاب تاریخ ساده تا مقایسه بازه در ERP: معرفی react-persian-range-picker

اگر روی داشبورد فروش، پنل مالی یا یک ERP واقعی کار کرده باشید، احتمالاً این صحنه برایتان آشناست:

«فروش این ماه را با ماه قبل مقایسه کن… حالا یک ماه عقب برو… حالا بازه مقایسه هم باید همزمان عقب برود.»

بیشتر Date Pickerهای رایج فقط «یک تاریخ» یا حداکثر «یک بازه» میگیرند. در پروژههای بزرگ سازمانی، مسئله اصلی اغلب چیز دیگری است: مقایسه دو بازه زمانی با تجربه کاربری شبیه ابزارهای enterprise مثل Dynamics / Analytics — و اگر محصول فارسی باشد، همهٔ اینها باید روی تقویم شمسی (جلالی) درست کار کند؛ از جمله سال کبیسه.

اینجا است که [react-persian-range-picker](https://www.npmjs.com/package/react-persian-range-picker) معنا پیدا میکند: کتابخانهای سبک برای React که از سادهترین سناریو (یک تاریخ) تا پیچیدهترین (حرکت همزمان بازه + مقایسه) را پوشش میدهد.

مشکل واقعی در پروژه های بزرگ

در اپلیکیشنهای ERP و BI معمولاً این نیازها همزمان وجود دارند:

1. انتخاب بازه جاری (مثلاً ۱ تا ۳۰ فروردین)

2. تعریف بازه مقایسه (مثلاً همان بازه در ماه قبل یا سال قبل)

3. جابهجایی سریع دوره با دکمههای «یک گام عقب / جلو»

4. پشتیبانی بومی از تقویم شمسی بدون تبدیلهای شکننده

5. رعایت سال کبیسه جلالی در اعتبارسنجی و محاسبه طول ماه

6. خروجی استاندارد برای API (timestamp یا ISO string)

7. نسخه میلادی برای محصولات دوزبانه (calendarType="gregorian")

بسیاری از کتابخانههای Jalali فقط تقویم را نمایش میدهند؛ لایهٔ «مقایسه سازمانی + ناوبری همزمان» را خودتان باید از صفر بسازید.

این کتابخانه چه تمایزی دارد؟

۱) Range Comparison به سبک ابزارهای سازمانی

RangePicker برای سناریوی analytics/ERP طراحی شده: بازه اصلی + بازه مقایسه، تبهای Day / Week / Month / Year و انتخاب دستی.

۲) ناوبری همزمان بازه و مقایسه (تمایز محصول)

یکی از نقاط قوت مهم این پروژه، دکمهٔ حرکت گامی است:

• با یک کلیک، بازه اصلی یک گام عقب/جلو میرود

• همزمان بازه مقایسه هم یک گام متناظر جابهجا میشود

این رفتار برای تحلیل روند در ERP حیاتی است و در تجربهٔ کلاسیک بسیاری از pickerهای عمومی — و حتی الگوهای رایج enterprise — بهصورت آماده کمتر دیده میشود.

۳) جلالی محور، نه تبدیل وصله ای

موتور تاریخ روی [jalaali-js](https://www.npmjs.com/package/jalaali-js) (الگوریتم Borkowski) بنا شده و برای سال کبیسه و طول ماههای شمسی طراحی شده است؛ نه اینکه فقط روی یک موتور میلادی یک adapter بدلی سوار شود. پشتیبانی میلادی هم از طریق calendarType در دسترس است.

۴) مجموعه کامل برای فرم و داشبورد

علاوه بر Range:

• DatePicker (با ماسک و زمان)

• Mask کیبوردی YYYY/MM/DD با فوکوس سگمنت (سال → ماه → روز)

• TimePicker

• Calendar قابلembed

• هوکهای useRenderPosition و useMediaQuery

• توابع formatExport / formatIDateExport

۵) سبک برای production

وابستگی runtime تاریخ فقط jalaali-js است و React بهصورت peer dependency مصرف میشود — مناسب bundleهای سازمانی که از سنگینشدن پکیجها حساساند. بدون نیاز به moment-jalaali.

نصب و شروع سریع

npm i react-persian-range-picker
# یا
yarn add react-persian-range-picker

Peer dependencies: react و react-dom (نسخه ۱۷ / ۱۸ / ۱۹).

مثال ۱ — DatePicker ساده (سطح ۱)

import { useState } from 'react';
import { DatePicker } from 'react-persian-range-picker';
import type { DatePickerValue } from 'react-persian-range-picker';

export function InvoiceDateField() {
  const [value, setValue] = useState<DatePickerValue>(null);

  return (
    <DatePicker
      calendarType="jalali"
      exportType="timeStamp"
      showMask
      allowClear
      value={value}
      ={setValue}
      primaryColor="#1c39bb"
    />
  );
}

مثال ۲ — Mask مستقل (سطح ۲)

import { Mask } from 'react-persian-range-picker';

<Mask
  calendarType="jalali"
  exportType="IsoString"
  allowClear
  maskPlaceHolder="____/__/__"
  onMaskChange={(v) => console.log(v)}
  ={(msg) => console.warn(msg)}
/>

مثال ۳ — TimePicker (سطح ۳)

import { TimePicker } from 'react-persian-range-picker';

<TimePicker
  exportType="timeStamp"
  showSecond
  showNow
  minuteStep={5}
  ={(v) => console.log(v)}
/>

مثال ۴ — Range + Comparison + ناوبری (سطح ۵ و ۶)

import { useState } from 'react';
import { RangePicker } from 'react-persian-range-picker';
import type { HandleParams, IDate } from 'react-persian-range-picker';

export function SalesFilter() {
  const [range, setRange] = useState<IDate | null>(null);

  return (
    <RangePicker
      calendarType="jalali"
      exportType="timeStamp"
      showComparison
      isShowNavigationButton
      value={range ?? undefined}
      ={(e: HandleParams) => {
        const date = e.Data?.date as IDate | undefined;
        if (date) setRange(date);
      }}
      onCompareDateChange={(e) => {
        console.log('compare', e.Data);
      }}
      ={(e) => console.log('submit', e)}
      primaryColor="#1c39bb"
    />
  );
}

چه زمانی این کتابخانه انتخاب درستی است؟

انتخاب کنید اگر:

• داشبورد/ERP دارید و مقایسه بازه بخشی از UX اصلی است

• تقویم شمسی باید first-class باشد (نه adapter فرعی)

• میخواهید ناوبری دوره روی بازه + مقایسه همزمان کار کند

• محصولات دوزبانه دارید و گاهی به Gregorian هم نیاز است

• نمیخواهید فقط برای تاریخ، کل Ant Design یا MUI را به پروژه تحمیل کنید

سوالات متداول

آیا سال کبیسه شمسی پشتیبانی میشود؟
بله. موتور روی jalaali-js است و اعتبارسنجی ماسک/تقویم با آگاهی از کبیسه انجام میشود.

آیا فقط شمسی است؟
خیر. با calendarType="gregorian" میتوانید میلادی کار کنید.

React 19؟
بله؛ peer برای React ۱۷ / ۱۸ / ۱۹ تعریف شده است.

TypeScript؟
بله؛ تایپها در پکیج منتشر میشوند.

لینکها

• دمو زنده: GitHub Pages

• npm: react-persian-range-picker

• GitHub: Persian-range-picker

• نویسنده: Hamidreza Fallahi

جمع بندی

react-persian-range-picker فقط «یک تقویم شمسی دیگر» نیست؛ یک جعبه ابزار زمانی برای React است: از DatePicker و Mask تا Range Comparison و ناوبری همزمان بازه/مقایسه — با موتور جلالی واقعی، پشتیبانی میلادی، و footprint سبک برای production.

اگر روی محصول فارسی زبان سازمانی کار میکنید، یکبار دمو را با showComparison و دکمه های ناوبری امتحان کنید — همان جایی است که تفاوت را حس میکنید.

npm i react-persian-range-picker