TimePicker

کامپوننت TimePicker برای انتخاب زمان استفاده می‌شود؛ مثل تعیین زمان ارسال یک زمان‌بندی‌شده یا ساعت رزرو. انتخاب زمان با اسکرول کردن ستون‌های ساعت/دقیقه/ثانیه انجام می‌شود و با کلیک روی «تایید» ثبت می‌گردد.

Import

import { TimePicker } from "fara-ui";
import { getCurrentTime } from "fara-ui/jalali";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

import { useState } from "react";

function AppointmentTime() {
  const [time, setTime] = useState(null);

  return <TimePicker value={time} onChange={setTime} placeholder="زمان قرار را انتخاب کنید" />;
}

value را حتی پیش از اولین انتخاب null نگه دار؛ مقدار جدید فقط بعد از کلیک روی «تایید» به onChange می‌رسد.

Playground

format24h12h

showSeconds

disabled

placeholder

<TimePicker
  format="24h"
  placeholder="انتخاب زمان"
  value={time}
  onChange={setTime}
/>

Display Format

• "24h" (پیش‌فرض) — نمایش مثل 14:30
• "12h" — نمایش مثل 02:30 ب.ظ؛ در این حالت ستون «ق.ظ / ب.ظ» هم به پنل اضافه می‌شود

با showSeconds ستون ثانیه هم نمایش داده می‌شود.

Initial Value

• "current" (پیش‌فرض) — هنگام باز کردن پنل، زمان فعلی سیستم انتخاب است.
• "zero" — مقدار اولیه 00:00 است.

اگر value پاس بدهی، همان مقدار هنگام باز شدن پنل انتخاب است.

Time Value

value همیشه به‌صورت ۲۴ ساعته است؛ فرمت "12h" فقط روی نمایش اثر دارد:

interface TimeValue {
  hour: number; // 0-23
  minute: number; // 0-59
  second?: number; // فقط با showSeconds
}

برای مقدار اولیه‌ی «الان» می‌توانی از تابع کمکی getCurrentTime() استفاده کنی.

const [time, setTime] = useState(getCurrentTime());

<TimePicker value={time} onChange={setTime} showSeconds />;

Behavior

• پنل با کلیک بیرون از کامپوننت یا کلید Escape بسته می‌شود.
• مقادیر پنل (draft) فقط با کلیک روی «تایید» در onChange ثبت می‌شوند؛ بستن پنل بدون تأیید، مقدار قبلی را حفظ می‌کند.

Data Attributes and Customize CSS

TimePicker hookهای ساختاری زیر را ارائه می‌کند:

Attribute	کاربرد
data-fara-time-picker	wrapper اصلی
data-fara-time-picker-input	input فقط‌خواندنی برای بازکردن پنل
data-fara-time-picker-panel	پنل انتخاب زمان؛ در Portal رندر می‌شود
data-fara-time-picker-header	ردیف عنوان ستون‌ها
data-fara-time-picker-column-label	عنوان ساعت، دقیقه یا ثانیه
data-fara-time-picker-scroll-container	ظرف ستون‌ها
data-fara-time-picker-column	هر ستون
data-column	نوع ستون: hour, minute, second, period
data-fara-time-picker-item	هر مقدار قابل انتخاب
data-selected	مقدار انتخاب‌شده در draft
data-fara-time-picker-separator	جداکننده‌ی :
data-fara-time-picker-confirm-row	ردیف دکمه‌ی تأیید
data-fara-time-picker-confirm-button	دکمه‌ی تأیید

<TimePicker
  className="booking-time"
  inputClassName="booking-time-input"
  value={time}
  onChange={setTime}
/>

.booking-time-input {
  width: 180px;
}

[data-fara-time-picker-column][data-column="hour"] {
  color: #2563eb;
}

[data-fara-time-picker-item][data-selected] {
  font-weight: 700;
}

[data-fara-time-picker-confirm-button] {
  width: 100%;
}

پنل با Portal در document.body قرار می‌گیرد؛ selectorهای آن را به wrapper والد وابسته نکن. className روی wrapper و inputClassName روی input اعمال می‌شود.

Accessibility and SSR

• input نمایش‌دهنده readOnly است و با کلیک باز می‌شود؛ برای توضیح آن یک <label> یا متن راهنما در اطراف کامپوننت قرار بده.
• برای غیرفعال‌کردن انتخاب، disabled را روی خود TimePicker تنظیم کن.
• TimePicker با SSR و Next.js سازگار است؛ پنل در رندر سرور خروجی تولید نمی‌کند و پس از hydration در مرورگر فعال می‌شود.

Props

Prop	Type	Default	Description
value	TimeValue | null	-	زمان انتخاب‌شده (الزامی، controlled)
onChange	(value: TimeValue) => void	-	با کلیک روی «تایید» صدا زده می‌شود (الزامی)
format	"24h" | "12h"	"24h"	فرمت نمایش
showSeconds	boolean	false	نمایش ستون ثانیه
defaultTime	"current" | "zero"	"current"	مقدار اولیه‌ی پنل وقتی value خالی است
placeholder	string	"انتخاب زمان"	متن پیش‌فرض ورودی
disabled	boolean	false	غیرفعال کردن کامپوننت
className	string	-	کلاس CSS اضافی روی wrapper
inputClassName	string	-	کلاس CSS اضافی روی input نمایش