انتخابگر تاریخ و ساعت (DateTimePicker)

معرفی

کامپوننت DateTimePicker برای انتخاب یک لحظه مشخص — تاریخ به‌همراه ساعت و دقیقه — استفاده می‌شود. مثل زمان‌بندیِ اجرای یک کار، یا ثبتِ زمانِ دقیقِ یک رویداد. از تقویم شمسی (جلالی) و میلادی پشتیبانی می‌کند و به طور کامل RTL است.

چه زمانی استفاده کنیم:

• زمانی که کاربر باید هم روز و هم ساعتِ مشخصی را انتخاب کند — مثلاً «این کار را چه زمانی دوباره اجرا کن»
• ثبتِ زمانِ دقیقِ یک رویداد که ساعت آن هم اهمیت دارد (نه فقط روز)

چه زمانی استفاده نکنیم:

• وقتی فقط تاریخ (بدون ساعت) لازم است — از DatePicker با mode="single" استفاده کنید؛ سبک‌تر است و ورودیِ ساعت اضافه ندارد
• برای انتخابِ یک بازه‌ی زمانی (از تاریخ تا تاریخ) — از DatePicker (حالت پیش‌فرضِ range) یا DateRangePicker استفاده کنید
• وقتی فقط مدتِ زمان (نه یک لحظه‌ی مشخص) لازم است — این کامپوننت برای آن نیست

استفاده پایه

import { DateTimePicker } from '@partodata/ui'
import { useState } from 'react'

export default function MyComponent() {
  const [value, setValue] = useState<Date | undefined>()

  return <DateTimePicker value={value} onChange={setValue} placeholder="انتخاب تاریخ و ساعت" />
}

تقویم شمسی

مانند DatePicker و DateRangePicker، تقویم پیش‌فرض شمسی است: زبان صفحه تعیین می‌کند (در fa یا بیرون از قاب و قالب شمسی، در ar/en میلادی) و usePersianCalendar صریح بر آن مقدم است:

<DateTimePicker value={value} onChange={setValue} placeholder="انتخاب تاریخ و ساعت" usePersianCalendar={true} />

چطور کار می‌کند

دکمه‌ی trigger یک پاپاور باز می‌کند که شاملِ یک تقویم (برای انتخابِ روز) و یک فیلدِ ساعتِ 24ساعته زیرِ آن است (هیچ‌جای سیستم طراحی ق.ظ/ب.ظ یا AM/PM نشان نمی‌دهد). این دو مستقل از هم تغییر می‌کنند اما هر دو روی همان مقدارِ value می‌نویسند:

• کلیک روی یک روز، فقط بخشِ سال/ماه/روز را عوض می‌کند و ساعتِ فعلی (یا 00:00 اگر هنوز چیزی انتخاب نشده) را حفظ می‌کند.
• تغییرِ فیلدِ ساعت، فقط ساعت/دقیقه را عوض می‌کند و روزِ فعلی (یا امروز اگر هنوز چیزی انتخاب نشده) را حفظ می‌کند.

پاپاور بعد از انتخابِ روز خودش بسته نمی‌شود — چون معمولاً کاربر می‌خواهد بعد از انتخابِ روز، ساعت را هم تنظیم کند.

محدودیت تاریخ

مثل DatePicker، می‌توانید حداقل و حداکثر روز قابل انتخاب را مشخص کنید (ساعتِ خودِ minDate/maxDate نادیده گرفته می‌شود — فقط روز محدود می‌شود):

<DateTimePicker value={value} onChange={setValue} minDate={new Date(2024, 0, 1)} maxDate={new Date(2024, 11, 31)} />

غیرفعال کردن

<DateTimePicker value={value} onChange={setValue} disabled={true} />

راهنمای استفاده

Props

نکات مهم

مقدارِ Date همیشه میلادی است

حتی وقتی usePersianCalendar={true} است، value همچنان یک شیِ Date جاوااسکریپتِ معمولی است — فقط نمایشِ روی دکمه و تقویم شمسی می‌شود. اگر لازم است تاریخ را به‌صورتِ رشته با بک‌اند ردوبدل کنید، تبدیل با ابزارهای معمولِ Date (یا date-fns) روی همین مقدار انجام می‌شود.

فیلدِ ساعت همیشه چپ‌به‌راست است

فیلدِ ساعت dir="ltr" دارد — مستقل از جهتِ صفحه یا پاپاور — چون HH:mm مثلِ هر عددِ دیگری در این سیستم طراحی (مقدارِ MetricCard، StatDisplay، …) چپ‌به‌راست خوانده می‌شود.

دسترسی‌پذیری

• دکمه‌ی trigger یک <button> استاندارد است؛ با Enter/Space باز می‌شود و popover فوکس را به‌صورت Radix Popover trap می‌کند.
• در تقویم: کلیدهای جهت (← → ↑ ↓) برای جابه‌جایی روز، Page Up/Page Down برای ماه، و Home/End برای ابتدا/انتهای هفته کار می‌کنند؛ Enter روزِ زیرِ فوکس را انتخاب می‌کند.
• فیلدِ ساعت یک فیلد متنی HH:mm است، نه <input type="time"> بومی — ساعت و ارقامِ فیلد بومی از زبانِ مرورگر می‌آیند (در مرورگر انگلیسی «01:05 PM» با ارقام لاتین). ارقام فارسی و عربی و 1305 را می‌پذیرد، با خروج از فیلد یا Enter ثبت می‌شود و کلیدهای بالا/پایین یک دقیقه جابه‌جا می‌کنند؛ ارقامش در صفحهٔ فارسی فارسی دیده می‌شوند.
• Escape popover را می‌بندد و فوکس به دکمه‌ی trigger برمی‌گردد.
• در حالت usePersianCalendar={true}، نام ماه/روز و اعدادِ تقویم به فارسی اعلام می‌شوند ولی مقدار Date همچنان میلادی باقی می‌ماند.

کامپوننت‌های مرتبط

• DatePicker — اگر فقط روز (بدون ساعت) کافی است، یا بازه‌ی تاریخی لازم دارید، از DatePicker استفاده کنید — سبک‌تر است
• DateRangePicker — برای بازه‌ی تاریخی با label و امکاناتِ بیشتر
• Calendar — اگر فقط نمایشِ تقویم بدون input field و popover لازم دارید