مقدار نمایش در برابر مقدار ذخیره

سامانه تقویم یک تنظیم نمایش است. یک تنظیم ذخیره نیست. یک مؤلفه می‌تواند تقویم جلالی را به کاربر نشان دهد و همچنان مقداری به برنامه بدهد که هیچ وابستگی خاصی به تقویم ندارد.

رفتار پیش‌فرض

هر مؤلفه و هر تابع تبدیل هسته، به‌صورت پیش‌فرض یک مقدار میلادی و مستقل از تقویم برمی‌گرداند. شکل آن از لایه دقت فعال پیروی می‌کند:

لایه دقت	شکل مقدار پیش‌فرض
CalendarDate	رشته تاریخ ISO میلادی، YYYY-MM-DD
CalendarDateTime	رشته تاریخ‌زمان ISO میلادی، بدون افست
ZonedCalendarDateTime	رشته تاریخ‌زمان ISO میلادی با افست، یا میلی‌ثانیه epoch

این با رفتار <input type="date"> بومی هم‌خوان است: هر تقویمی که سیستم‌عامل نشان دهد، مقدار همیشه یک رشته ISO میلادی است. jalali-js همین شکاف را به‌عمد نگه می‌دارد، به‌جای بستن مقدار ذخیره‌شده به تقویمی که روی صفحه است. یک انتخابگر تقویم پارسی موجود برای React، یعنی react-multi-date-picker، این دو را به هم گره می‌زند: اگر آن را برای نمایش تقویم پارسی پیکربندی کنید، مقداری که برمی‌گرداند هم پارسی است و برای گرفتن مقدار میلادی به فراخوانی صریح .convert() نیاز دارید. آن پیوند باعث می‌شود خروجی خام انتخابگر آسان وارد فرم یا فیلد پایگاه داده شود، بدون گام تبدیل. jalali-js با نگه داشتن خروجی پیش‌فرض میلادی، صرف‌نظر از تقویم نمایش، از آن پرهیز می‌کند.

انتخاب مقدار بومی جلالی

برخی برنامه‌ها باید مقدار جلالی را همان‌طور ذخیره کنند (برای مثال سامانه ثبت دولتی یا حقوقی که تاریخ را به شکل جلالی نگه می‌دارد). گزینه valueFormat، هرجا که مؤلفه یا toStorageValue() آن را بپذیرد، این را پوشش می‌دهد:

import { toStorageValue } from 'jalali-js';

const date = { year: 1403, month: 5, day: 15 };

toStorageValue(date, 'gregorian-iso'); // '2024-08-05' (پیش‌فرض)
toStorageValue(date, 'date'); // Date بومی JS
toStorageValue(date, 'epoch'); // میلی‌ثانیه epoch
toStorageValue(date, 'jalali-iso'); // '1403-05-15'
toStorageValue(date, 'jalali-object'); // { year: 1403, month: 5, day: 15 }

'jalali-iso' و 'jalali-object' با وجود نام، واقعاً ویژه جلالی نیستند: همان سامانه تقویم خود تاریخ (system) را بدون تبدیل می‌دهند، نه معادل میلادی. برای مورد اصلی (ذخیره تاریخ جلالی به‌همان شکل) نام‌گذاری شده‌اند و برای تاریخ با سامانه میلادی هم همین‌طور کار می‌کنند.

این درباره طرح‌واره خود شما تصمیم نمی‌گیرد. فقط مشخص می‌کند مؤلفه چه مقداری برگرداند، و مقدار مستقل از تقویم را پیش‌فرض می‌کند تا انتخاب درست نیاز به فکر اضافه نداشته باشد.

رفت و برگشت کامل

یک برنامه معمول: مقدار ذخیره‌شده را بخوانید (پیش‌فرض میلادی) → فقط برای نمایش به تقویم نمایش تبدیل کنید → بگذارید کاربر تاریخ تازه بگزیند → هنگام تغییر دوباره به مقدار ذخیره برگردید. onChange در DatePicker هر دو شکل را در یک فراخوانی می‌دهد، پس بیشتر برنامه‌ها این تبدیل را دستی نمی‌نویسند:

<DatePicker
  system="jalali"
  locale="fa"
  onChange={(value, date) => {
    // value: مقدار ذخیره، شکل‌گرفته با valueFormat (آنچه ذخیره می‌کنید)
    // date: CalendarDate خام (اگر لازم باشد برای وضعیت محلی UI نگه دارید)
  }}
/>