https://virgool.ir/feed/@hamidrezafalahifa2026-11-10 18:46:58https://virgool.ir/images/default-avatar.jpghttps://virgool.ir/@hamidrezafalahihttps://virgool.ir/@hamidrezafalahi/react-persian-range-picker-j3nafcr0z14hاگر روی داشبورد فروش، پنل مالی یا یک ERP واقعی کار کرده باشید، احتمالاً این صحنه برایتان آشناست:«فروش این ماه را با ماه قبل مقایسه کن… حالا یک ماه عقب برو… حالا بازه مقایسه هم باید همزمان عقب برود.»بیشتر Date Pickerهای رایج فقط «یک تاریخ» یا حداکثر «یک بازه» میگیرند. در پروژههای بزرگ سازمانی، مسئله اصلی اغلب چیز دیگری است: مقایسه دو بازه زمانی با تجربه کاربری شبیه ابزارهای enterprise مثل Dynamics / Analytics — و اگر محصول فارسی باشد، همهٔ اینها باید روی تقویم شمسی (جلالی) درست کار کند؛ از جمله سال کبیسه.اینجا است که [react-persian-range-picker](https://www.npmjs.com/package/react-persian-range-picker) معنا پیدا میکند: کتابخانهای سبک برای React که از سادهترین سناریو (یک تاریخ) تا پیچیدهترین (حرکت همزمان بازه + مقایسه) را پوشش میدهد.مشکل واقعی در پروژه های بزرگدر اپلیکیشنهای ERP و BI معمولاً این نیازها همزمان وجود دارند:انتخاب بازه جاری (مثلاً ۱ تا ۳۰ فروردین)تعریف بازه مقایسه (مثلاً همان بازه در ماه قبل یا سال قبل)جابهجایی سریع دوره با دکمههای «یک گام عقب / جلو»پشتیبانی بومی از تقویم شمسی بدون تبدیلهای شکنندهرعایت سال کبیسه جلالی در اعتبارسنجی و محاسبه طول ماهخروجی استاندارد برای API (timestamp یا ISO string)نسخه میلادی برای محصولات دوزبانه (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 با فوکوس سگمنت (سال → ماه → روز)TimePickerCalendar قابل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-pickerPeer 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 Pagesnpm: react-persian-range-pickerGitHub: Persian-range-pickerنویسنده: Hamidreza Fallahiجمع بندیreact-persian-range-picker فقط «یک تقویم شمسی دیگر» نیست؛ یک جعبه ابزار زمانی برای React است: از DatePicker و Mask تا Range Comparison و ناوبری همزمان بازه/مقایسه — با موتور جلالی واقعی، پشتیبانی میلادی، و footprint سبک برای production.اگر روی محصول فارسی زبان سازمانی کار میکنید، یکبار دمو را با showComparison و دکمه های ناوبری امتحان کنید — همان جایی است که تفاوت را حس میکنید.npm i react-persian-range-pickerحمیدرضا فلاحیحمیدرضا فلاحیSat, 01 Aug 2026 16:56:33 +0330