چگونه از datetimepicker فارسی در پروژه‌های وب استفاده کنیم؟

در این آموزش، نحوه استفاده از یک datetimepicker شمسی (فارسی) را توضیح داده‌ام که قابلیت انتخاب تاریخ به‌صورت هجری شمسی را دارد و به‌راحتی در صفحات HTML یا فریم‌ورک‌های مختلف مانند Angular، ASP.NET و... قابل استفاده است.
با استفاده از این تقویم شمسی می‌توانید رابط کاربری بهتر و بومی‌تری برای کاربران خود فراهم کنید.
در این مقاله موارد زیر را یاد می‌گیرید:

• افزودن فایل‌های CSS و JavaScript مربوط به datetimepicker شمسی

• تنظیم مقدار پیش‌فرض و قالب نمایش تاریخ

• اعمال datetimepicker به ورودی‌های فرم

• حل مشکلات نمایش در مرورگر و فونت فارسی

این ابزار مناسب سایت‌های ایرانی، فرم‌های رزرو، تاریخ تولد، مدیریت محتوا، سامانه‌های بانکی و... است.

در این آموزش به‌صورت گام‌به‌گام نحوه استفاده از کتابخانه MD.BootstrapPersianDateTimePicker را در Razor Pages شرح می‌دهم. این ابزار بسیار کاربردی، امکان انتخاب تاریخ به‌صورت شمسی و ذخیره‌سازی آن به‌صورت میلادی را فراهم می‌کند.

استفاده از CDN:

<link href="https://cdn.jsdelivr.net/npm/md.bootstrappersiandatetimepicker/dist/mds.bs.datetimepicker.style.css" rel="stylesheet" />

یا از نسخه لوکال:

<link href="~/lib/MD.BootstrapPersianDateTimePicker/mds.bs.datetimepicker.style.css" rel="stylesheet" />

2. اضافه کردن اسکریپت در انتهای صفحه Razor

  @section Scripts {
        @{await Html.RenderPartialAsync("_ValidationScriptsPartial");}
<script src="https://cdn.jsdelivr.net/npm/md.bootstrappersiandatetimepicker/dist/mds.bs.datetimepicker.js"></script>
<script>
    const dtp1Instance = new mds.MdsPersianDateTimePicker(document.getElementById("shamsiDate"), {
  targetTextSelector: '[data-name="dtp1-text"]',
  targetDateSelector: '[data-name="dtp1-date"]',
});
</script>

3. اضافه کردن کنترل انتخاب تاریخ در فرم (Markup)

در فایل Razor، برای مثال داخل فرم پرداخت یا ثبت تاریخ:

<div class="col">
    <div class="form-group">
        <span class="text-danger">*</span>
        <label asp-for="Receipt.LastPayment" class="control-label"></label>
        
        <!-- نمایش تاریخ برای کاربر -->
        <input asp-for="Receipt.LastPayment" type="text" id="shamsiDate" data-name="dtp1-text" class="form-control" />
        
        <!-- مقدار واقعی میلادی که در کنترلر ارسال می‌شود -->
        <input type="hidden" data-name="dtp1-date" name="Receipt.LastPayment" />
        
        <span asp-validation-for="Receipt.LastPayment" class="text-danger"></span>
    </div>
</div>

✅ نکته مهم

مقداری که در input مخفی (<input type="hidden">) با data-name="dtp1-date" ذخیره می‌شود، تاریخ میلادی است و برای ذخیره در پایگاه داده یا ارسال به کنترلر استفاده می‌شود.
در حالی که input قابل مشاهده برای کاربر (data-name="dtp1-text") به‌صورت شمسی است و فقط برای رابط کاربری استفاده می‌شود.

<input type="hidden" data-name="dtp1-date" name="Receipt.LastPayment" />

این ابزار در فرم‌های مختلف بسیار کاربرد دارد از جمله:

• فرم‌های عضویت و ثبت‌نام

• انتخاب تاریخ تولد

• رزرو زمان ملاقات یا پرداخت

• ثبت و مدیریت سفارش‌ها

• سیستم‌های مدیریت محتوا

برای مشاهده ساختار کامل پروژه و فایل‌های Razor، به ریپوی GitHub مراجعه کنید.